Domain Services

High-level services that wrap API calls with validation

Domain services provide a validated, task-focused interface over the raw API functions. They’re the recommended way to interact with Komga.

Why use domain services?

Automatic Validation

All responses are validated against Zod schemas. Invalid data throws immediately.

Type Safety

Full TypeScript support with proper return types. No manual casting.

Simplified API

Intuitive method names and parameters. Less boilerplate code.

Error Handling

Consistent error types across all operations. Easy to catch and handle.

Available services

Service	Domain	Key Operations
BookService	Individual books	List, get, update metadata, pages, thumbnails
SeriesService	Series (grouped books)	List, get, update metadata, get books
LibraryService	Libraries (file locations)	List, get, create, update, scan, delete

For Collections and Read Lists, use Direct API functions as they’re not yet wrapped in domain services. See the Collections and Read Lists guides.

BookService

Manage individual books in your library.

import { BookService } from 'komga-sdk';

const service = new BookService(client);

Methods

list(options)

List books with pagination and search.

const books = await service.list({
  search: { fullTextSearch: 'manga' },
  page: 0,
  size: 20,
  sort: ['metadata.title,asc'],
});

console.log(books.totalElements); // Total matching books
console.log(books.content);       // Current page

Parameters:

• search - Search filters (fullTextSearch, tags, etc.)
• page - Page index (0-based)
• size - Items per page
• sort - Sort fields and directions
• unpaged - Return all results (use carefully)

getById(bookId)

Get a single book by ID.

const book = await service.getById('book-123');
console.log(book.metadata.title);
console.log(book.metadata.summary);

updateMetadata(bookId, updates)

Update book metadata.

await service.updateMetadata('book-123', {
  title: 'New Title',
  summary: 'Updated summary',
  tags: ['favorite', 'manga'],
});

getPages(bookId)

Get all pages in a book.

const pages = await service.getPages('book-123');
console.log(`${pages.length} pages`);
pages.forEach((page, i) => {
  console.log(`Page ${i + 1}: ${page.width}x${page.height}`);
});

getThumbnailUrl(bookId)

Get the thumbnail URL for a book.

const url = service.getThumbnailUrl('book-123');
// /api/v1/books/book-123/thumbnail

deleteReadProgress(bookId)

Clear read progress for a book.

await service.deleteReadProgress('book-123');

SeriesService

Manage series (collections of books).

import { SeriesService } from 'komga-sdk';

const service = new SeriesService(client);

Methods

list(options)

List series with pagination and search.

const series = await service.list({
  search: { fullTextSearch: 'fantasy' },
  page: 0,
  size: 20,
  sort: ['metadata.title,asc'],
});

getById(seriesId)

Get a single series by ID.

const series = await service.getById('series-123');
console.log(series.metadata.title);
console.log(series.booksCount);

updateMetadata(seriesId, updates)

Update series metadata.

await service.updateMetadata('series-123', {
  status: 'ONGOING',
  publisher: 'Example Publisher',
  genres: ['Fantasy', 'Adventure'],
});

getBooks(seriesId, options)

Get books in a series.

const books = await service.getBooks('series-123', {
  page: 0,
  size: 50,
  sort: ['metadata.number,asc'],
});

getCollections(seriesId)

Get collections containing this series.

const collections = await service.getCollections('series-123');
collections.forEach(c => console.log(c.name));

LibraryService

Manage libraries (root folders where Komga scans for content).

import { LibraryService } from 'komga-sdk';

const service = new LibraryService(client);

Methods

getAll()

Get all libraries.

const libraries = await service.getAll();
libraries.forEach(lib => {
  console.log(`${lib.name}: ${lib.root}`);
});

getById(libraryId)

Get a single library by ID.

const library = await service.getById('library-123');
console.log(library.name);
console.log(library.root);

create(payload)

Create a new library.

const library = await service.create({
  name: 'Comics',
  root: '/data/comics',
  // ... many other options
});

See Libraries guide for full creation options.

update(libraryId, updates)

Update library settings.

await service.update('library-123', {
  name: 'Updated Name',
});

scan(libraryId)

Trigger a library scan.

await service.scan('library-123');
// Scan runs async on server

delete(libraryId)

Delete a library.

await service.delete('library-123');

This permanently removes the library from Komga (files on disk are not deleted).

Domain services vs direct API

When to use services

Use domain services when:

• Building application features
• You want automatic validation
• You prefer a cleaner API
• The endpoint is supported by a service

// Clean, validated, typed
const book = await bookService.getById('book-123');
console.log(book.metadata.title); // TypeScript knows the shape

When to use direct API

Use direct API when:

• Endpoint not covered by services (Collections, Read Lists, Users, etc.)
• You need full control over the request
• You’re building custom abstractions
• You need access to raw response data

import { getCollections } from 'komga-sdk';

const result = await getCollections({
  client,
  query: { page: 0, size: 20 },
});

if (result.data) {
  console.log(result.data.content);
}

Comparison table

Aspect	Domain Services	Direct API
Validation	Automatic	Manual
Return type	BookDto	{ data?, error? }
Error handling	Throws	Returns error object
Coverage	~60% of API	100% of API
Boilerplate	Minimal	More verbose

Next steps

Books Guide

Deep dive into book operations.

Direct API

Use low-level API functions.

Validation

Understand response validation.