Request customization

Each generated client exposes low-level interceptors for requests, responses, and errors. They run for every generated operation made with that client. The SDK does not export logging, validation, or error-transform interceptor factories. Use a custom fetch when you need a transport wrapper, retry policy, timeout policy, or tracing around the platform call. Use interceptors when you need access to the constructed Request, returned Response, or error lifecycle for one client instance.

Register hooks

use returns a numeric identifier. Return the request, response, or error from the hook so the generated pipeline can continue. Hooks may be synchronous or async:

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});

const requestId = client.interceptors.request.use(async (request, options) => {
  console.debug('Komga request', request.method, request.url);
  return request;
});

const responseId = client.interceptors.response.use((response, request, options) => {
  console.debug('Komga response', response.status, request.url);
  return response;
});

const errorId = client.interceptors.error.use((error, response, request, options) => {
  console.error('Komga transport error', { error, status: response?.status });
  return error;
});

The callback signatures are low-level Fetch hooks:

Request hooks receive (request, options) and return a Request.
Response hooks receive (response, request, options) and return a Response.
Error hooks receive (error, response, request, options) and return the error. response and request can be undefined.

The options value is the generated client’s resolved request configuration. Keep hooks focused on transport concerns; operation parameters and generated result handling remain at the operation call site.

Add headers safely

Request hooks can return a new Request with application metadata. Do not overwrite auth-owned headers or log their values:

const requestId = client.interceptors.request.use((request) => {
  const headers = new Headers(request.headers);
  headers.set('X-Request-Source', 'batch-job');
  return new Request(request, { headers });
});

Authorization, X-API-Key, Cookie, and other secrets may be present. Redact values before logging. Prefer client-level headers for static metadata and a request hook for dynamic correlation IDs.

Observe responses without consuming them

A response body is a stream. If a response interceptor reads it, clone it first or return a replacement response so the generated parser still receives a body:

const responseId = client.interceptors.response.use(async (response, request) => {
  if (response.headers.get('content-type')?.includes('application/json')) {
    const copy = response.clone();
    console.debug('Komga status', response.status, await copy.text());
  }
  return response;
});

Avoid logging response bodies in production when they may contain private metadata. A response hook can observe status and headers without parsing the body.

Error hooks

Error hooks run for response errors, Fetch/network failures, request construction failures, and parser failures. Preserve the original error unless your application deliberately maps it:

const errorId = client.interceptors.error.use((error, response, request) => {
  const status = response?.status;
  console.warn('Komga request failed', { status, url: request?.url });
  return error;
});

Returning a replacement value changes what the generated client places in result.error or throws when generated throwOnError is enabled. If callers rely on generated error payload types, do not replace them globally.

Remove or replace hooks

Use the returned identifier with eject, or clear a whole interceptor collection:

client.interceptors.request.eject(requestId);
client.interceptors.response.eject(responseId);
client.interceptors.error.eject(errorId);

const replacementId = client.interceptors.request.update(
  requestId,
  (request, options) => request,
);

client.interceptors.response.clear();
if (replacementId !== false) {
  console.log(client.interceptors.request.exists(replacementId));
}

update returns the identifier when it replaces an existing hook and false when the identifier is not active. clear removes every hook in that collection. Register hooks once during client setup, not inside a request handler, or a long-lived process can accumulate duplicate logging and mutations.

Interceptors versus custom Fetch

Use a custom Fetch wrapper for policies that must surround the actual transport call:

const fetchWithTiming: typeof fetch = async (input, init) => {
  const started = Date.now();
  try {
    return await fetch(input, init);
  } finally {
    console.log(`Fetch completed in ${Date.now() - started}ms`);
  }
};

const tracedClient = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  fetch: fetchWithTiming,
});

Use an interceptor for Request/Response lifecycle visibility. Neither mechanism supplies Komga schemas, domain services, or a universal retry/cache policy.

A response interceptor can change the Response passed to every generated operation on the client. Scope clients carefully when different features need different transport behavior, and clone bodies before inspecting them.

For response validation, see Runtime validation. For result branches and KomgaApiError, see Result handling.

Get started

Core SDK

API guides

Reference

Request customization

Register hooks

Add headers safely

Observe responses without consuming them

Error hooks

Remove or replace hooks

Interceptors versus custom Fetch

​Register hooks

​Add headers safely

​Observe responses without consuming them

​Error hooks

​Remove or replace hooks

​Interceptors versus custom Fetch

Register hooks

Add headers safely

Observe responses without consuming them

Error hooks

Remove or replace hooks

Interceptors versus custom Fetch