@redseat/api 0.3.5 → 0.3.7

package/server.md

@@ -1,277 +1,538 @@
-# ServerApi
-
-The `ServerApi` class provides server-level operations for managing libraries, settings, plugins, and credentials.
-
-## Overview
-
-`ServerApi` handles operations that are not specific to a single library, such as:
-- Listing and creating libraries
-- Getting current user information
-- Managing server settings
-- Listing plugins and credentials
-- Adding credentials to libraries
-
-## Constructor
-
-```typescript
-new ServerApi(client: RedseatClient)
-```
-
-**Parameters:**
-- `client`: An initialized `RedseatClient` instance
-
-**Example:**
-```typescript
-import { RedseatClient, ServerApi } from '@redseat/api';
-
-const client = new RedseatClient({ /* ... */ });
-const serverApi = new ServerApi(client);
-```
-
-## Methods
-
-### `getLibraries(): Promise<ILibrary[]>`
-
-Retrieves all libraries available to the current user.
-
-**Returns:** Promise resolving to an array of `ILibrary` objects
-
-**Example:**
-```typescript
-const libraries = await serverApi.getLibraries();
-libraries.forEach(library => {
-    console.log(`Library: ${library.name} (${library.type})`);
-});
-```
-
-### `getMe(): Promise<any>`
-
-Gets information about the current authenticated user.
-
-**Returns:** Promise resolving to user information object
-
-**Example:**
-```typescript
-const user = await serverApi.getMe();
-console.log(`Logged in as: ${user.name}`);
-```
-
-### `addLibrary(library: Partial<ILibrary>): Promise<ILibrary>`
-
-Creates a new library.
-
-**Parameters:**
-- `library`: Partial library object with required fields:
-  - `name`: Library name (required)
-  - `type`: Library type - `'photos'`, `'shows'`, `'movies'`, or `'iptv'` (required)
-  - `source`: Optional source type
-  - `crypt`: Optional boolean to enable encryption
-  - `hidden`: Optional boolean to hide library
-
-**Returns:** Promise resolving to the created `ILibrary` object with generated `id`
-
-**Example:**
-```typescript
-const newLibrary = await serverApi.addLibrary({
-    name: 'My Photos',
-    type: 'photos',
-    crypt: true // Enable encryption
-});
-console.log(`Created library with ID: ${newLibrary.id}`);
-```
-
-### `getSetting(key: string): Promise<string>`
-
-Retrieves a server setting value by key.
-
-**Parameters:**
-- `key`: The setting key to retrieve
-
-**Returns:** Promise resolving to the setting value as a string
-
-**Example:**
-```typescript
-const maxUploadSize = await serverApi.getSetting('max_upload_size');
-console.log(`Max upload size: ${maxUploadSize}`);
-```
-
-### `getPlugins(): Promise<any[]>`
-
-Retrieves all available plugins on the server.
-
-**Returns:** Promise resolving to an array of plugin objects
-
-**Example:**
-```typescript
-const plugins = await serverApi.getPlugins();
-plugins.forEach(plugin => {
-    console.log(`Plugin: ${plugin.name} - ${plugin.description}`);
-});
-```
-
-### `getCredentials(): Promise<ICredential[]>`
-
-Retrieves all available credentials configured on the server.
-
-**Returns:** Promise resolving to an array of `ICredential` objects
-
-**Example:**
-```typescript
-const credentials = await serverApi.getCredentials();
-credentials.forEach(cred => {
-    console.log(`Credential: ${cred.name} (${cred.type.type})`);
-});
-```
-
-### `saveCredential(credential: ICredential): Promise<ICredential>`
-
-Creates a new credential on the server.
-
-**Parameters:**
-- `credential`: Credential object with required fields:
-  - `name`: Credential name (required)
-  - `source`: Plugin/source name (required)
-  - `type`: Authentication type object (required)
-  - `settings`: Settings record for plugin params (required)
-  - `login`: Optional login/username
-  - `password`: Optional password/token
-
-**Returns:** Promise resolving to the created `ICredential` object with generated `id`
-
-**Example:**
-```typescript
-const newCredential = await serverApi.saveCredential({
-    name: 'My API Key',
-    source: 'jackett',
-    type: { type: PluginAuthType.Token },
-    settings: { url: 'http://localhost:9117' },
-    password: 'my-api-key'
-});
-console.log(`Created credential with ID: ${newCredential.id}`);
-```
-
-### `updateCredential(credential: ICredential): Promise<ICredential>`
-
-Updates an existing credential.
-
-**Parameters:**
-- `credential`: Credential object with `id` and fields to update
-
-**Returns:** Promise resolving to the updated `ICredential` object
-
-**Example:**
-```typescript
-const updated = await serverApi.updateCredential({
-    id: 'cred-123',
-    name: 'Updated Name',
-    source: 'jackett',
-    type: { type: PluginAuthType.Token },
-    settings: { url: 'http://localhost:9117' },
-    password: 'new-api-key'
-});
-```
-
-### `deleteCredential(id: string): Promise<void>`
-
-Deletes a credential by ID.
-
-**Parameters:**
-- `id`: The credential ID to delete
-
-**Returns:** Promise resolving when deletion is complete
-
-**Example:**
-```typescript
-await serverApi.deleteCredential('cred-123');
-```
-
-### `saveOAuthCredentials(pluginId: string, params: Record<string, string>): Promise<void>`
-
-Exchanges OAuth tokens and saves credentials for a plugin.
-
-**Parameters:**
-- `pluginId`: The plugin ID to save credentials for
-- `params`: OAuth parameters including tokens and name
-
-**Returns:** Promise resolving when credentials are saved
-
-**Example:**
-```typescript
-await serverApi.saveOAuthCredentials('trakt', {
-    name: 'My Trakt Account',
-    code: 'oauth-code',
-    access_token: 'token123'
-});
-```
-
-### `addLibraryCredential(credential: any): Promise<ILibrary>`
-
-Adds a credential to a library. This is used to configure external service access for libraries.
-
-**Parameters:**
-- `credential`: Credential configuration object (structure depends on credential type)
-
-**Returns:** Promise resolving to the updated `ILibrary` object
-
-**Example:**
-```typescript
-const library = await serverApi.addLibraryCredential({
-    libraryId: 'library-123',
-    credentialId: 'credential-456',
-    // Additional credential-specific configuration
-});
-```
-
-## Usage Examples
-
-### Complete Workflow: Create Library and Get Info
-
-```typescript
-import { RedseatClient, ServerApi } from '@redseat/api';
-
-// Initialize
-const client = new RedseatClient({ /* ... */ });
-const serverApi = new ServerApi(client);
-
-// Get current user
-const user = await serverApi.getMe();
-console.log(`User: ${user.name}`);
-
-// List existing libraries
-const libraries = await serverApi.getLibraries();
-console.log(`Found ${libraries.length} libraries`);
-
-// Create a new encrypted photo library
-const newLibrary = await serverApi.addLibrary({
-    name: 'Encrypted Photos',
-    type: 'photos',
-    crypt: true
-});
-
-// Get server settings
-const maxUpload = await serverApi.getSetting('max_upload_size');
-console.log(`Max upload size: ${maxUpload}`);
-```
-
-### Error Handling
-
-```typescript
-try {
-    const libraries = await serverApi.getLibraries();
-} catch (error) {
-    if (error.response?.status === 401) {
-        console.error('Authentication failed');
-    } else if (error.response?.status === 403) {
-        console.error('Insufficient permissions');
-    } else {
-        console.error('Failed to get libraries:', error.message);
-    }
-}
-```
-
-## Related Documentation
-
-- [RedseatClient Documentation](client.md) - HTTP client used by ServerApi
-- [LibraryApi Documentation](libraries.md) - Library-specific operations
-- [README](README.md) - Package overview
-
+# ServerApi
+
+The `ServerApi` class provides server-level operations for managing libraries, settings, plugins, and credentials.
+
+## Overview
+
+`ServerApi` handles operations that are not specific to a single library, such as:
+- Listing and creating libraries
+- Getting current user information
+- Managing server settings
+- Listing plugins and credentials
+- Adding credentials to libraries
+
+## Constructor
+
+```typescript
+new ServerApi(client: RedseatClient)
+```
+
+**Parameters:**
+- `client`: An initialized `RedseatClient` instance
+
+**Example:**
+```typescript
+import { RedseatClient, ServerApi } from '@redseat/api';
+
+const client = new RedseatClient({ /* ... */ });
+const serverApi = new ServerApi(client);
+```
+
+## Methods
+
+### `getLibraries(): Promise<ILibrary[]>`
+
+Retrieves all libraries available to the current user.
+
+**Returns:** Promise resolving to an array of `ILibrary` objects
+
+**Example:**
+```typescript
+const libraries = await serverApi.getLibraries();
+libraries.forEach(library => {
+    console.log(`Library: ${library.name} (${library.type})`);
+});
+```
+
+### `getMe(): Promise<any>`
+
+Gets information about the current authenticated user.
+
+**Returns:** Promise resolving to user information object
+
+**Example:**
+```typescript
+const user = await serverApi.getMe();
+console.log(`Logged in as: ${user.name}`);
+```
+
+### `addLibrary(library: Partial<ILibrary>): Promise<ILibrary>`
+
+Creates a new library.
+
+**Parameters:**
+- `library`: Partial library object with required fields:
+  - `name`: Library name (required)
+  - `type`: Library type - `'photos'`, `'shows'`, `'movies'`, or `'iptv'` (required)
+  - `source`: Optional source type
+  - `crypt`: Optional boolean to enable encryption
+  - `hidden`: Optional boolean to hide library
+
+**Returns:** Promise resolving to the created `ILibrary` object with generated `id`
+
+**Example:**
+```typescript
+const newLibrary = await serverApi.addLibrary({
+    name: 'My Photos',
+    type: 'photos',
+    crypt: true // Enable encryption
+});
+console.log(`Created library with ID: ${newLibrary.id}`);
+```
+
+### `getSetting(key: string): Promise<string>`
+
+Retrieves a server setting value by key.
+
+**Parameters:**
+- `key`: The setting key to retrieve
+
+**Returns:** Promise resolving to the setting value as a string
+
+**Example:**
+```typescript
+const maxUploadSize = await serverApi.getSetting('max_upload_size');
+console.log(`Max upload size: ${maxUploadSize}`);
+```
+
+### `getPlugins(): Promise<any[]>`
+
+Retrieves all available plugins on the server.
+
+**Returns:** Promise resolving to an array of plugin objects
+
+**Example:**
+```typescript
+const plugins = await serverApi.getPlugins();
+plugins.forEach(plugin => {
+    console.log(`Plugin: ${plugin.name} - ${plugin.description}`);
+});
+```
+
+### `getCredentials(): Promise<ICredential[]>`
+
+Retrieves all available credentials configured on the server.
+
+**Returns:** Promise resolving to an array of `ICredential` objects
+
+**Example:**
+```typescript
+const credentials = await serverApi.getCredentials();
+credentials.forEach(cred => {
+    console.log(`Credential: ${cred.name} (${cred.type.type})`);
+});
+```
+
+### `saveCredential(credential: ICredential): Promise<ICredential>`
+
+Creates a new credential on the server.
+
+**Parameters:**
+- `credential`: Credential object with required fields:
+  - `name`: Credential name (required)
+  - `source`: Plugin/source name (required)
+  - `type`: Authentication type object (required)
+  - `settings`: Settings record for plugin params (required)
+  - `login`: Optional login/username
+  - `password`: Optional password/token
+
+**Returns:** Promise resolving to the created `ICredential` object with generated `id`
+
+**Example:**
+```typescript
+const newCredential = await serverApi.saveCredential({
+    name: 'My API Key',
+    source: 'jackett',
+    type: { type: PluginAuthType.Token },
+    settings: { url: 'http://localhost:9117' },
+    password: 'my-api-key'
+});
+console.log(`Created credential with ID: ${newCredential.id}`);
+```
+
+### `updateCredential(credential: ICredential): Promise<ICredential>`
+
+Updates an existing credential.
+
+**Parameters:**
+- `credential`: Credential object with `id` and fields to update
+
+**Returns:** Promise resolving to the updated `ICredential` object
+
+**Example:**
+```typescript
+const updated = await serverApi.updateCredential({
+    id: 'cred-123',
+    name: 'Updated Name',
+    source: 'jackett',
+    type: { type: PluginAuthType.Token },
+    settings: { url: 'http://localhost:9117' },
+    password: 'new-api-key'
+});
+```
+
+### `deleteCredential(id: string): Promise<void>`
+
+Deletes a credential by ID.
+
+**Parameters:**
+- `id`: The credential ID to delete
+
+**Returns:** Promise resolving when deletion is complete
+
+**Example:**
+```typescript
+await serverApi.deleteCredential('cred-123');
+```
+
+### `saveOAuthCredentials(pluginId: string, params: Record<string, string>): Promise<void>`
+
+Exchanges OAuth tokens and saves credentials for a plugin.
+
+**Parameters:**
+- `pluginId`: The plugin ID to save credentials for
+- `params`: OAuth parameters including tokens and name
+
+**Returns:** Promise resolving when credentials are saved
+
+**Example:**
+```typescript
+await serverApi.saveOAuthCredentials('trakt', {
+    name: 'My Trakt Account',
+    code: 'oauth-code',
+    access_token: 'token123'
+});
+```
+
+### `addLibraryCredential(credential: any): Promise<ILibrary>`
+
+Adds a credential to a library. This is used to configure external service access for libraries.
+
+**Parameters:**
+- `credential`: Credential configuration object (structure depends on credential type)
+
+**Returns:** Promise resolving to the updated `ILibrary` object
+
+**Example:**
+```typescript
+const library = await serverApi.addLibraryCredential({
+    libraryId: 'library-123',
+    credentialId: 'credential-456',
+    // Additional credential-specific configuration
+});
+```
+
+## Watch History API
+
+The Watch History API tracks what content users have watched and their playback progress. This is a **global** system that operates independently of specific libraries or servers.
+
+### Key Concepts
+
+#### External ID Format
+
+Watch history uses **external IDs** (from providers like IMDb, Trakt, TMDb) rather than local database IDs. This design enables:
+
+- **Cross-server portability**: Your watch history syncs across different Redseat servers
+- **External service synchronization**: Seamless sync with Trakt, Plex, and other services
+- **Library independence**: History is global, not tied to a specific library
+
+**ID Format: `provider:value`**
+
+| Provider | Format | Example |
+|----------|--------|---------|
+| IMDb | `imdb:ttXXXXXXX` | `imdb:tt0111161` (The Shawshank Redemption) |
+| Trakt | `trakt:XXXXX` | `trakt:28` |
+| TMDb | `tmdb:XXX` | `tmdb:278` |
+| TVDB | `tvdb:XXXXX` | `tvdb:81189` |
+| Redseat | `redseat:XXXXX` | `redseat:abc123` (local fallback) |
+
+#### Library vs Direct History Endpoints
+
+There are two ways to mark content as watched:
+
+1. **Library endpoints** (recommended for most use cases):
+   - `LibraryApi.setMovieWatched(movieId, date)`
+   - `LibraryApi.setEpisodeWatched(serieId, season, number, date)`
+   - Uses local database IDs
+   - Server automatically resolves to external IDs
+
+2. **Direct history endpoints** (for external sync):
+   - `ServerApi.addToHistory({ type, id, date })`
+   - Requires external IDs in `provider:value` format
+   - Used for importing from external services
+
+### History Methods
+
+#### `getHistory(query?: HistoryQuery): Promise<IWatched[]>`
+
+Retrieves the current user's watch history.
+
+**Parameters:**
+- `query`: Optional query object with filtering parameters:
+  - `sort`: Sort key using `RsSort` enum
+  - `order`: Sort direction using `SqlOrder` enum (`ASC` or `DESC`)
+  - `before`: Filter entries before this timestamp
+  - `after`: Filter entries after this timestamp
+  - `types`: Array of `MediaType` to filter by (`'episode'`, `'movie'`, `'book'`, `'song'`, `'media'`)
+  - `id`: Filter by specific external ID (e.g., `imdb:tt0111161`)
+  - `pageKey`: Pagination key
+
+**Returns:** Promise resolving to an array of `IWatched` objects
+
+**Example:**
+```typescript
+// Get all history
+const history = await serverApi.getHistory();
+
+// Get recent movie watch history
+const movieHistory = await serverApi.getHistory({
+    types: ['movie'],
+    order: SqlOrder.DESC,
+    after: Date.now() - 86400000 * 30 // Last 30 days
+});
+
+// Check if specific movie was watched (using external ID)
+const shawshank = await serverApi.getHistory({
+    id: 'imdb:tt0111161'
+});
+```
+
+#### `addToHistory(watched: IWatchedForAdd): Promise<void>`
+
+Adds an entry to the user's watch history using external IDs.
+
+**Parameters:**
+- `watched`: Object containing:
+  - `type`: The `MediaType` (`'episode'`, `'movie'`, `'book'`, `'song'`, `'media'`)
+  - `id`: **External ID** in `provider:value` format (e.g., `imdb:tt0111161`)
+  - `date`: Timestamp when it was watched (unix milliseconds)
+
+**Returns:** Promise resolving when the entry is added
+
+**Example:**
+```typescript
+// Mark The Shawshank Redemption as watched using IMDb ID
+await serverApi.addToHistory({
+    type: 'movie',
+    id: 'imdb:tt0111161',
+    date: Date.now()
+});
+
+// Mark a Breaking Bad episode as watched using Trakt ID
+await serverApi.addToHistory({
+    type: 'episode',
+    id: 'trakt:62085',  // S01E01
+    date: Date.now()
+});
+```
+
+**Note:** For easier usage with local content, prefer the library methods which handle ID resolution automatically:
+```typescript
+// This is simpler - uses local ID, server resolves to external
+await libraryApi.setMovieWatched('local-movie-id', Date.now());
+```
+
+#### `getProgressById(id: string): Promise<IViewProgress | null>`
+
+Gets the view progress for a specific item by external ID.
+
+**Parameters:**
+- `id`: External ID in `provider:value` format (e.g., `imdb:tt0111161`)
+
+**Returns:** Promise resolving to `IViewProgress` object or `null` if not found
+
+**Example:**
+```typescript
+const progress = await serverApi.getProgressById('imdb:tt0111161');
+if (progress) {
+    console.log(`Progress: ${progress.progress}ms`);
+}
+```
+
+#### `addProgress(progress: IViewProgressForAdd): Promise<void>`
+
+Adds or updates view progress for an item using external IDs.
+
+**Parameters:**
+- `progress`: Object containing:
+  - `type`: The `MediaType`
+  - `id`: **External ID** in `provider:value` format
+  - `progress`: Progress value in milliseconds
+  - `parent`: Optional parent external ID (e.g., series ID for episodes)
+
+**Returns:** Promise resolving when progress is saved
+
+**Example:**
+```typescript
+// Save playback position at 1 hour
+await serverApi.addProgress({
+    type: 'movie',
+    id: 'imdb:tt0111161',
+    progress: 3600000 // milliseconds
+});
+
+// Save episode progress with parent series
+await serverApi.addProgress({
+    type: 'episode',
+    id: 'imdb:tt0959621',      // Breaking Bad S01E01
+    parent: 'imdb:tt0903747',  // Breaking Bad series
+    progress: 1800000 // 30 minutes
+});
+```
+
+### Admin History Methods
+
+#### `getAdminHistory(): Promise<IWatched[]>`
+
+**Admin only.** Retrieves watch history for all users.
+
+**Returns:** Promise resolving to an array of `IWatched` objects
+
+**Example:**
+```typescript
+const allHistory = await serverApi.getAdminHistory();
+```
+
+#### `importHistory(watcheds: IWatchedForAdd[]): Promise<void>`
+
+**Admin only.** Imports watch history entries in bulk. Useful for migrating from external services.
+
+**Parameters:**
+- `watcheds`: Array of `IWatchedForAdd` objects with external IDs
+
+**Returns:** Promise resolving when import is complete
+
+**Example:**
+```typescript
+// Import watch history from an external service
+await serverApi.importHistory([
+    { type: 'movie', id: 'imdb:tt0111161', date: Date.now() - 86400000 },
+    { type: 'movie', id: 'tmdb:278', date: Date.now() - 172800000 },
+    { type: 'episode', id: 'trakt:62085', date: Date.now() }
+]);
+```
+
+### Complete Example: Syncing with External Service
+
+```typescript
+import { RedseatClient, ServerApi, SqlOrder } from '@redseat/api';
+
+// Initialize
+const client = new RedseatClient({ /* ... */ });
+const serverApi = new ServerApi(client);
+
+// Export: Get all watched movies to sync to external service
+const watchedMovies = await serverApi.getHistory({
+    types: ['movie'],
+    order: SqlOrder.ASC
+});
+
+// The IDs are already in external format for easy sync
+for (const entry of watchedMovies) {
+    console.log(`Watched: ${entry.id} on ${new Date(entry.date).toISOString()}`);
+    // entry.id is e.g., "imdb:tt0111161"
+}
+
+// Import: Bring in history from external service
+const externalHistory = [
+    { type: 'movie' as const, id: 'imdb:tt0468569', date: 1609459200000 }, // The Dark Knight
+    { type: 'movie' as const, id: 'trakt:120', date: 1612137600000 },       // LOTR
+];
+await serverApi.importHistory(externalHistory);
+```
+
+### SSE Events
+
+Real-time watch state changes are broadcast via SSE. These are **user-scoped** events (not library-specific).
+
+#### `watched$: Observable<SSEWatchedEvent>`
+
+Emitted when content is marked as watched.
+
+```typescript
+client.watched$.subscribe(event => {
+    console.log(`Watched: ${event.type} ${event.id} at ${new Date(event.date)}`);
+    // event.id is external ID, e.g., "imdb:tt0111161"
+});
+```
+
+**Event fields:**
+- `type`: Content type ('movie', 'episode')
+- `id`: External ID (e.g., 'imdb:tt0111161')
+- `date`: Timestamp when watched (unix ms)
+- `userRef`: User reference
+- `modified`: Last modified timestamp
+
+#### `unwatched$: Observable<SSEUnwatchedEvent>`
+
+Emitted when content is removed from watch history. Contains **all possible IDs** so clients can match against any cached external ID.
+
+```typescript
+client.unwatched$.subscribe(event => {
+    console.log(`Unwatched: ${event.type}`);
+    // event.ids contains ALL possible external IDs
+    for (const id of event.ids) {
+        console.log(`  - ${id}`);  // e.g., "imdb:tt0111161", "trakt:481"
+    }
+});
+```
+
+**Event fields:**
+- `type`: Content type ('movie', 'episode')
+- `ids`: Array of all external IDs (e.g., `["imdb:tt0111161", "trakt:481", "tmdb:278"]`)
+- `userRef`: User reference
+- `modified`: Last modified timestamp
+
+## Usage Examples
+
+### Complete Workflow: Create Library and Get Info
+
+```typescript
+import { RedseatClient, ServerApi } from '@redseat/api';
+
+// Initialize
+const client = new RedseatClient({ /* ... */ });
+const serverApi = new ServerApi(client);
+
+// Get current user
+const user = await serverApi.getMe();
+console.log(`User: ${user.name}`);
+
+// List existing libraries
+const libraries = await serverApi.getLibraries();
+console.log(`Found ${libraries.length} libraries`);
+
+// Create a new encrypted photo library
+const newLibrary = await serverApi.addLibrary({
+    name: 'Encrypted Photos',
+    type: 'photos',
+    crypt: true
+});
+
+// Get server settings
+const maxUpload = await serverApi.getSetting('max_upload_size');
+console.log(`Max upload size: ${maxUpload}`);
+```
+
+### Error Handling
+
+```typescript
+try {
+    const libraries = await serverApi.getLibraries();
+} catch (error) {
+    if (error.response?.status === 401) {
+        console.error('Authentication failed');
+    } else if (error.response?.status === 403) {
+        console.error('Insufficient permissions');
+    } else {
+        console.error('Failed to get libraries:', error.message);
+    }
+}
+```
+
+## Related Documentation
+
+- [RedseatClient Documentation](client.md) - HTTP client used by ServerApi
+- [LibraryApi Documentation](libraries.md) - Library-specific operations
+- [README](README.md) - Package overview
+