> ## Documentation Index
> Fetch the complete documentation index at: https://komga-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Answers to common questions about komga-sdk 1.0

The snippets that use `{ client }` assume a client created with `createKomgaClient` as shown in [Authentication](/authentication).

> **What does komga-sdk 1.0 contain?**
>
> `komga-sdk` 1.0 is generated from Komga API **1.25.0**. It exposes **165 typed operations** and has **zero runtime dependencies**. The core package provides generated operation functions, generated TypeScript types, `createKomgaClient`, `unwrap`, and `KomgaApiError`.
>
> The package does not include the former domain-service classes, handwritten DTO schemas, legacy error hierarchy, or built-in retry/cache middleware. Add those policies in your application when they are useful.

> **How do I call an operation?**
>
> Pass endpoint parameters as one flat object. Pass the configured client as the optional second argument:
>
> ```typescript theme={null}
> import { getBookById } from 'komga-sdk';
>
> const result = await getBookById({ bookId: 'book-123' }, { client });
> ```
>
> Operations without endpoint parameters accept only the options object:
>
> ```typescript theme={null}
> import { getLibraries } from 'komga-sdk';
>
> const result = await getLibraries({ client });
> ```
>
> The removed grouped `{ path, query, body }` shape is not part of the 1.0 public operation signatures. Check the generated function or [Direct API](/direct-api) when an operation has a body plus query fields.

> **Which authentication methods are supported?**
>
> `createKomgaClient` supports:
>
> * HTTP Basic Auth with `auth: { type: 'basic', username, password }`
> * Komga API keys with `auth: { type: 'apiKey', key }`
> * No built-in authentication, when `auth` is omitted
> * Application-owned headers through `headers`
> * Fetch cookie credentials through `credentials: 'include'`
>
> The SDK does not implement OAuth login, JWT/Bearer authentication, or a browser login UI. `getOAuth2Providers` can list server-configured providers, but the application must own any provider flow and session handoff. See [Authentication](/authentication) for examples.

> **Can I use the SDK in a browser or Node.js?**
>
> Yes. The client uses native Fetch APIs and runs in Node.js 18+, modern browsers, and compatible edge runtimes. The runtime must provide Fetch, `Headers`, `Request`, `Response`, `TextEncoder`, and Web Crypto. Pass a custom `fetch` implementation to `createKomgaClient` when the host runtime needs one.
>
> For a browser session, configure `credentials: 'include'` and ensure Komga's CORS and cookie policies allow the exact origin. Do not ship long-lived Basic credentials or API keys in a public bundle.

> **Do requests throw errors?**
>
> Not by default. A generated operation resolves to fields containing `data`, `error`, `request`, and `response`:
>
> ```typescript theme={null}
> import { getBookById } from 'komga-sdk';
>
> const result = await getBookById({ bookId: 'book-123' }, { client });
>
> if (result.error) {
>   console.error(result.response?.status, result.error);
> }
> ```
>
> `request` and `response` are optional for request-construction and network failures. Use `unwrap` when your application wants a throwing boundary; it returns response data or throws `KomgaApiError` with `status`, `body`, `request`, and `response` fields.

> **What happens for void, binary, or text responses?**
>
> A successful `204 No Content` operation has `data: undefined`; success is represented by `error === undefined`. Generated binary and text operations can use Fetch parser options:
>
> ```typescript theme={null}
> import { getBookPageByNumber } from 'komga-sdk';
>
> const result = await getBookPageByNumber(
>   { bookId: 'book-123', pageNumber: 1 },
>   { client, parseAs: 'blob' },
> );
> ```
>
> Use `blob`, `arrayBuffer`, or `text` only for an endpoint whose generated response supports that representation. Inspect the generated type before assuming a JSON object.

> **Does the SDK validate response bodies at runtime?**
>
> No. Generated TypeScript types provide compile-time guidance; the core client does not validate response bodies at runtime and does not export Zod schemas or validation helpers. Add an application-owned validator at the boundary where untrusted data enters your system. See [Runtime validation](/validation).

> **Are retries, caching, or timeouts enabled?**
>
> No. The core client uses native Fetch and does not enable retries, caching, timeout handling, or debug logging by default. Add those policies around operation calls or provide a custom Fetch implementation. Any retry policy should account for whether an operation is safe to repeat, honor `Retry-After`, and avoid retrying `401` or `403` unchanged.

> **How do I customize Fetch or add logging?**
>
> Pass standard client options when creating the client:
>
> ```typescript theme={null}
> import { createKomgaClient } from 'komga-sdk';
>
> const client = createKomgaClient({
>   baseUrl: 'https://komga.example.com',
>   headers: { 'X-Request-Source': 'dashboard' },
>   credentials: 'include',
>   fetch: async (input, init) => fetch(input, init),
> });
> ```
>
> For lifecycle hooks, register `client.interceptors.request`, `.response`, or `.error`; `use` returns an id that can be passed to `eject`. Redact credentials and cookies, and remember that hooks run for every operation made with that client.

> **How do I paginate book results?**
>
> Use `getBooks` with its required `bookSearch` field and the flat `page`, `size`, `sort`, or `unpaged` parameters:
>
> ```typescript theme={null}
> import { getBooks } from 'komga-sdk';
>
> const result = await getBooks(
>   {
>     page: 0,
>     size: 20,
>     sort: ['metadata.title,asc'],
>     bookSearch: { fullTextSearch: 'manga' },
>   },
>   { client },
> );
>
> for (const book of result.data?.content ?? []) {
>   console.log(book.metadata.title);
> }
> ```
>
> Page indexes are zero-based. Use `last`, `totalPages`, and `content` defensively because generated page fields may be optional. See [Pagination](/pagination).

> **What does a 401, 403, or 404 mean?**
>
> Inspect `result.response?.status` and `result.error` on the nonthrowing result. A `401` usually means configured credentials or a session were rejected, a `403` means the authenticated user lacks permission, and a `404` means the endpoint or resource was not found. If you use `unwrap`, inspect `error instanceof KomgaApiError` and its `status` and `body` fields.

> **Can I use separate clients for separate servers?**
>
> Yes. `createKomgaClient` returns an isolated client instance. Create one client per Komga server or distinct authentication context, then pass the appropriate `{ client }` options object to each operation. Interceptors and custom Fetch implementations are also instance-local.

> **How do I use generated TypeScript types?**
>
> Import DTOs, search types, page types, and operation result types as type-only imports:
>
> ```typescript theme={null}
> import type { BookDto, BookSearch, PageBookDto } from 'komga-sdk';
>
> const search: BookSearch = { fullTextSearch: 'manga' };
> function firstBook(page: PageBookDto): BookDto | undefined {
>   return page.content?.[0];
> }
> ```
>
> Types describe the API contract to TypeScript; they do not prove that a runtime response is valid. Use an application-owned schema if your boundary needs runtime checks.

## More information

* [Quickstart](/quickstart) for installation and the first request
* [Authentication](/authentication) for Basic Auth, API keys, headers, sessions, and credentials
* [Quick reference](/quick-reference) for common flat-call patterns
* [Direct API](/direct-api) for request mapping and result handling
* [API reference](/reference/api-reference) for the generated Komga API surface


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.