npm package: @redseat/api
Description: TypeScript API client library for interacting with Redseat servers
Author: Arnaud JEZEQUEL
Latest version: 0.6.1

# @redseat/api

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.

## Overview

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

- **RedseatClient**: Low-level HTTP client with automatic token management and local server detection
- **ServerApi**: Server-level operations (libraries, settings, plugins, credentials)
- **LibraryApi**: Library-specific operations (media, tags, people, series, movies, encryption)

## Quick Start

```typescript
import { RedseatClient, ServerApi, LibraryApi } from '@redseat/api';
import { IServer, ILibrary } from '@redseat/api';

// Initialize the client
const client = new RedseatClient({
    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](client.md)** - RedseatClient documentation
  - HTTP client configuration
  - Automatic token refresh
  - Local server detection
  - Request/response interceptors

- **[server.md](server.md)** - ServerApi documentation
  - Server-level operations
  - Library management
  - Settings and plugins
  - Credentials management
  - **Watch History API** (global history with external IDs)

- **[libraries.md](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.md)** - Encryption module documentation
  - Key derivation (PBKDF2)
  - Text and binary encryption/decryption
  - File encryption with thumbnails
  - Cross-platform compatibility

- **[test.md](test.md)** - Testing guide
  - How to run tests
  - Test file descriptions
  - Test coverage information

- **[agents.md](agents.md)** - AI agent instructions
  - Documentation maintenance guidelines
  - Code change workflow
  - Best practices for keeping docs updated

## Package Exports

### Classes
- `RedseatClient` - HTTP client with authentication
- `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
- `IServer` - Server interface
- `MediaRequest` - Media query filter
- `IWatched` - Watch history entry (uses external IDs)
- `IWatchedForAdd` - Request body for adding to watch history
- `IViewProgress` - View progress entry
- `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
- `fetchServerToken()` - Fetch server authentication token
- Base64 encoding/decoding utilities
- Crypto utilities for cross-platform support

## Installation

```bash
npm install @redseat/api
```

## Requirements

- Node.js 15+ (for Web Crypto API support)
- TypeScript 5.0+
- Axios 1.11.0+

## License

See the main project LICENSE file.