Introduction

Type-safe TypeScript SDK for the Komga media server API

Komga SDK

Build powerful applications for managing comics, manga, and ebooks with a type-safe TypeScript client.

Type-Safe API

Full TypeScript support with autocompletion and compile-time type checking. Know your data structure before runtime.

Runtime Validation

Zod schemas validate all API responses. Catch mismatches between expected and actual data immediately.

Domain Services

High-level services for Books, Series, and Libraries. Write less boilerplate, focus on your app logic.

Flexible Auth

Support for Basic Auth, API Keys, and Bearer tokens. Secure your connections your way.

What is Komga?

Komga is a media server for comics, manga, BDs, magazines, and eBooks. It organizes your digital library, manages metadata, and serves content to readers.

Komga SDK provides a modern TypeScript client to interact with the Komga API programmatically.

What you get

Type Safety

Full TypeScript coverage means:

• Autocomplete in your IDE
• Compile-time error catching
• Inline documentation
• Refactoring support

import { BookService } from 'komga-sdk';

const service = new BookService(client);
const book = await service.getById('book-123');
// book.metadata.title is fully typed

Validation

Runtime validation with Zod ensures data integrity:

• All responses validated against schemas
• Strict mode catches unexpected fields
• Clear error messages when validation fails
• Type inference from schemas

import { BookDtoSchema, validateResponse } from 'komga-sdk';

const validated = validateResponse(BookDtoSchema, responseData);
// validated is fully typed AND runtime-checked

Interceptors

Hook into request/response lifecycle:

• Logging for debugging
• Error transformation
• Custom validation
• Request modification

const { request, response } = createLoggingInterceptor();
client.interceptors.request.use(request);
client.interceptors.response.use(response);

Error Handling

Typed error hierarchy for reliable handling:

• ApiError for HTTP errors
• ValidationError for schema mismatches
• NetworkError for connection issues
• Type guards for safe error checking

import { isApiError, isValidationError } from 'komga-sdk';

try {
  await bookService.getById('invalid');
} catch (error) {
  if (isApiError(error)) {
    console.log(`HTTP ${error.status}`);
  }
}

Choose your integration style

Domain services (recommended)

Use high-level services that validate responses and expose friendly methods.

import { BookService } from 'komga-sdk';

const service = new BookService(client);

// Simple, validated methods
const book = await service.getById('book-123');
const books = await service.list({ page: 0, size: 20 });
await service.updateMetadata('book-123', { title: 'New Title' });

Best for: Application code, rapid development, validated workflows

Direct API functions

Call low-level endpoints directly for full API coverage and advanced use cases.

import { getBookById } from 'komga-sdk';

const result = await getBookById({
  client,
  path: { bookId: 'book-123' },
});

if (result.data) {
  console.log(result.data.metadata.title);
}

Best for: Advanced usage, custom workflows, endpoints not covered by services

Typical workflow

1. Create a client

   Initialize with your Komga server URL and authentication:

   import { createKomgaClient } from 'komga-sdk';
   
   const client = createKomgaClient({
     baseUrl: 'http://localhost:25600',
     auth: {
       type: 'basic',
       username: '[e-mail]',
       password: 'your-password',
     },
   });
   
2. Use a domain service

   Work with high-level services for common tasks:

   import { BookService } from 'komga-sdk';
   
   const bookService = new BookService(client);
   const books = await bookService.list({ page: 0, size: 20 });
   
3. Add interceptors

   Enhance behavior with logging, validation, or error handling:

   const { request, response } = createLoggingInterceptor();
   client.interceptors.request.use(request);
   client.interceptors.response.use(response);
   

API Coverage

This SDK covers Komga API v1.24.1 with:

• 130 endpoint paths
• 165 operations
• 100% coverage of documented endpoints
• All 6 deprecated endpoints properly marked

Requirements

• Runtime with Fetch and Web Crypto (Node 18+ or modern browsers)
• Komga server (API v1.24.1)
• TypeScript 5.0+ (recommended)

Next steps

Quickstart

Install the SDK and make your first request in under 5 minutes.

Authentication

Configure Basic Auth, API keys, or Bearer tokens.

Domain Services

Learn about BookService, SeriesService, and LibraryService.