@redseat/api

See media units, numeric representation and encrypted video upload.

TypeScript API client library for interacting with Redseat servers. This package provides a comprehensive set of APIs for managing libraries, media, tags, people, series, movies, and more.

Canonical person types are exported as PersonType, with custom strings also supported. See people types and linked movie/show people for examples.

Overview

The @redseat/api package is organized into three main API classes:

• RedseatClient: Transport-neutral client with automatic token management
• ServerApi: Server-level operations (libraries, settings, plugins, credentials)
• LibraryApi: Library-specific operations (media, tags, people, series, movies, encryption)

Quick Start

import { ServerApi, LibraryApi } from '@redseat/api';
import { createHttpClient } from '@redseat/api-http';
import { IServer, ILibrary } from '@redseat/api';

// Initialize the client
const client = createHttpClient({
	server: {
		id: 'server-id',
		url: 'example.com',
		port: 443
	},
	getIdToken: async () => {
		// Return your ID token from your auth provider
		return 'your-id-token';
	}
});

// Get server API
const serverApi = new ServerApi(client);

// Get libraries
const libraries = await serverApi.getLibraries();

// Get library API for a specific library
const library = libraries[0];
const libraryApi = new LibraryApi(client, library.id!, library);

// For encrypted libraries, set the encryption key
if (library.crypt) {
	await libraryApi.setKey('your-passphrase');
}

// Get media
const medias = await libraryApi.getMedias();

Documentation

• client.md - RedseatClient documentation

  • Client and transport composition
  • Automatic token refresh
  • Local server detection
  • Transport injection

• transport.md - Transport abstraction, package boundaries, and documented URL bypasses

• server.md - ServerApi documentation

  • Server-level operations
  • Library management
  • Settings and plugins
  • Credentials management
  • Watch History API (global history with external IDs)

• libraries.md - LibraryApi documentation

  • Media operations (upload, download, update)
  • Tags, people, series, movies management
  • Face recognition operations
  • Encryption support for encrypted libraries

• encryption.md - Encryption module documentation

  • Key derivation (PBKDF2)
  • Text and binary encryption/decryption
  • File encryption with thumbnails
  • Cross-platform compatibility

• test.md - Testing guide

  • How to run tests
  • Test file descriptions
  • Test coverage information

• agents.md - AI agent instructions

  • Documentation maintenance guidelines
  • Code change workflow
  • Best practices for keeping docs updated

Package Exports

Classes

• RedseatClient - Transport-neutral client with authentication
• RedseatTransport - Transport interface for custom implementations
• ServerApi - Server-level API operations
• LibraryApi - Library-level API operations

Interfaces

• IFile - Media file interface
• ILibrary - Library interface
• ITag - Tag interface
• IPerson - Person interface
• ISerie - Series interface
• IMovie - Movie interface
• IBook - Book interface with request-user watched projection and canonical provider aliases
• IMovieForCreate / IMovieForUpdate - Movie inputs, including title tag and series relationship deltas
• ISerieForCreate / ISerieForUpdate - Show inputs, including title tag relationship deltas
• IBookForCreate / IBookForUpdate - Book metadata inputs that exclude watched
• IServer - Server interface
• MediaRequest - Media query filter
• EpisodeQuery - Episode filters and page parameters
• EpisodePaginationOptions - Complete episode snapshot pagination options
• MediaLookupOptions - Alternate title, source selection, and opaque cursor options for entity lookups
• TitleSearchQuery / BookLookupQuery - Typed metadata search fields and relation filters
• LookupRelationFilters - People, series, and tag constraints for plugin metadata searches
• RsLookupPersonFilter / RsLookupSerieFilter / RsLookupTagFilter - Server 0.41.0 filter shapes
• MetadataSearchOptions - Source selection and opaque cursor options for metadata searches
• LookupSourceResults - Per-source grouped downloads and continuation cursor
• IWatched - Watch history entry (uses external IDs)
• IWatchedForAdd - Request body for adding to watch history
• IViewProgress - View progress entry
• IBackup - Backup configuration, including media and database/configuration retention limits
• HistoryQuery - Query parameters for history endpoint
• And more (see src/interfaces.ts)

Encryption Functions

• deriveKey() - Derive encryption key from passphrase
• encryptText() / decryptText() - Text encryption
• encryptBuffer() / decryptBuffer() - Binary encryption
• encryptFile() / decryptFile() - File encryption with metadata
• getRandomIV() - Generate random IV

Utilities

• Base64 encoding/decoding utilities
• Crypto utilities for cross-platform support

Installation

npm install @redseat/api
# Add the standard HTTP implementation when needed:
npm install @redseat/api-http
# Or use the direct DataChannel transport:
npm install @redseat/api-webrtc

Requirements

• Node.js 15+ (for Web Crypto API support)
• TypeScript 5.0+

Publishing

Bumping the version in packages/api/package.json and merging it into main triggers .github/workflows/publish-api.yml. The workflow skips versions that already exist on npm, then tests, builds, and publishes the package through npm trusted publishing.

Before the first automated release, configure the trusted publisher for @redseat/api on npm:

• Provider: GitHub Actions
• Organization or user: neckaros
• Repository: redseat-svelte
• Workflow filename: publish-api.yml
• Allowed action: npm publish

License

See the main project LICENSE file.

IPersonWithRoles adds optional contextual roles, characters, rank, and conf to a person. Relations.peopleDetails and SearchRelations.peopleDetails use these inline credit objects. rank is an optional non-negative integer: lower comes first, 0 is first, and null/absent means unknown. SDK 0.13.0 adds typed relation filters for metadata searches and matches server interfaces 0.41.x. SDK 0.14.0 adds IBackup.maxVersions and IBackup.maxDatabaseVersions retention settings. SDK 0.16.0 adds pluggable transports, typed RedSeat transport errors, and direct domain return values. SDK 0.17.0 moves HTTP/Axios into the standalone @redseat/api-http package. SDK 0.18.2 adds ISerie.lang (original language), ISerie.original and ISerie.overview (server interfaces 0.42.x). SDK 0.19.0 adds viewProgress$ (resume positions saved from any device) and fixes watched$/unwatched$, which emitted the server's {"watched": ...} wrapper instead of the event. Needs @redseat/api-http 0.2.1 or @redseat/api-webrtc 0.1.2. The standalone @redseat/api-webrtc package provides direct, multiplexed DataChannel delivery without an Axios dependency. SDK 0.12.0 removed the separate role/character maps introduced by server interfaces 0.40.x. Use getBookPeople / refreshBookPeople for book credits; movie/show people methods also return this extended, backward-compatible shape.