Komga SDK
komga-sdk 1.0 is a generated TypeScript client for the Komga REST API. It targets Komga API 1.25.0, exposes 165 operations, and has zero runtime dependencies.
The package gives you:
- TypeScript types generated from the Komga API description
- Direct operation functions with flat endpoint parameters
- Nonthrowing request results containing
data,error,request, andresponse - An explicit
unwraphelper when an exception boundary is useful - A native Fetch client for Node.js, browsers, and compatible edge runtimes
Generated operations
Call the endpoint you need directly. Parameters match the generated operation signature.
Structured results
Requests return their result fields by default. Inspect
error or response without wrapping every call in a try/catch.Native Fetch
The SDK uses the platform Fetch API and accepts a custom Fetch implementation when your runtime needs one.
Basic and API-key auth
Configure HTTP Basic credentials or an
X-API-Key once when you create the client.What is Komga?
Komga is a media server for comics, manga, BDs, magazines, and ebooks. It organizes a digital library, manages metadata, and serves content to readers. This SDK maps Komga’s documented HTTP operations to typed functions. It intentionally does not add response validation, retries, caching, or logging on top of Fetch; those are application policies you can add at the boundary where they make sense.Choose an integration style
Generated operations
Use a generated operation when you need the complete API surface or want the request and result contract visible at the call site. Each endpoint input is a property of one flat first argument; client configuration is the optional second argument:Application-owned wrappers
The 1.0 package does not includeBookService, SeriesService, or LibraryService classes. If your application wants domain-oriented methods, compose a small repository around generated functions and choose whether it returns KomgaResult or calls unwrap. This keeps caching, pagination state, and business rules with the application that owns them.
Make a request
Create a client, pass it as the second argument to an operation, and inspect the returned fields:data; an HTTP, parsing, or network error has error. request and response are optional because a failure can occur before a Request or Response exists.
Request and result anatomy
An operation’s first object contains only endpoint inputs. The generated client maps those fields to path, query, or body slots:result.data is the generated response type. On failure, result.error is the generated error payload (or a transport/parsing error), and result.response?.status gives the HTTP status when the server responded. The request and response objects are the original Fetch objects, which is useful for headers, tracing, and status-specific handling.
Successful empty responses, such as a 204 No Content mutation, have data: undefined. Binary and text endpoints can be requested with generated Fetch options such as parseAs: 'blob', parseAs: 'arrayBuffer', or parseAs: 'text' when the endpoint’s generated response type supports that representation.
Opt into throwing errors
Useunwrap at the boundary where your application wants exceptions. It returns response data on success and throws KomgaApiError when the generated result contains an API error:
unwrap when an exception is the clearer boundary for a repository, job, or request handler.
Runtime requirements
The SDK uses platform APIs rather than a bundled HTTP library:- Node.js 18 or newer
- A modern browser with Fetch,
Headers,Request,Response,TextEncoder, and Web Crypto support - An edge runtime that provides those same Web APIs
credentials mode and server-side CORS permission. In Node or another host with a wrapped transport, pass a compatible implementation with the client’s fetch option.
API coverage
The generated client targets Komga API 1.25.0 with:- 165 operations
- Typed request parameters, response types, and documented error types
- Deprecated operations represented according to the generated API surface
- Zero runtime dependencies in the core package
Next steps
Quickstart
Install the package, create a client, and make a typed request.
Authentication
Configure Basic Auth, API keys, headers, sessions, and Fetch credentials.
Quick reference
Copy common flat-call, result, pagination, and TypeScript patterns.