@redseat/api 0.3.6 → 0.3.7

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import { Method, AxiosRequestConfig } from 'axios';
 import { Observable } from 'rxjs';
 import { IToken } from './auth.js';
 import { IServer } from './interfaces.js';
-import { SSEConnectionState, SSEConnectionOptions, SSEConnectionError, SSELibraryEvent, SSELibraryStatusEvent, SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSEBackupsEvent, SSEBackupFilesEvent, SSEMediaRatingEvent, SSEMediaProgressEvent, SSEPlayersListEvent } from './sse-types.js';
+import { SSEConnectionState, SSEConnectionOptions, SSEConnectionError, SSELibraryEvent, SSELibraryStatusEvent, SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSEBackupsEvent, SSEBackupFilesEvent, SSEMediaRatingEvent, SSEMediaProgressEvent, SSEPlayersListEvent, SSEWatchedEvent, SSEUnwatchedEvent } from './sse-types.js';
 export interface ClientOptions {
     server: IServer;
     getIdToken: () => Promise<string>;
@@ -45,6 +45,8 @@ export declare class RedseatClient {
     readonly mediaRating$: Observable<SSEMediaRatingEvent>;
     readonly mediaProgress$: Observable<SSEMediaProgressEvent>;
     readonly playersList$: Observable<SSEPlayersListEvent>;
+    readonly watched$: Observable<SSEWatchedEvent>;
+    readonly unwatched$: Observable<SSEUnwatchedEvent>;
     /**
      * Creates a typed observable for a specific SSE event type.
      * Unwraps the nested data structure from the server (e.g., {uploadProgress: {...}} -> {...})

package/dist/client.js

@@ -55,6 +55,8 @@ export class RedseatClient {
         this.mediaRating$ = this.createEventStream('media_rating');
         this.mediaProgress$ = this.createEventStream('media_progress');
         this.playersList$ = this.createEventStream('players-list');
+        this.watched$ = this.createEventStream('watched');
+        this.unwatched$ = this.createEventStream('unwatched');
         this.server = options.server;
         this.redseatUrl = options.redseatUrl;
         this.getIdToken = options.getIdToken;

package/dist/interfaces.d.ts

@@ -483,40 +483,191 @@ export declare enum RsSort {
     Name = "name",
     Size = "size"
 }
+/**
+ * Media type for history/watched tracking.
+ * Used to categorize watched entries and view progress.
+ */
 export type MediaType = 'episode' | 'movie' | 'book' | 'song' | 'media';
+/**
+ * Watch history entry - returned from GET /users/me/history.
+ *
+ * ## 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**: History syncs across different Redseat servers
+ * - **External service synchronization**: Seamless sync with Trakt, Plex, etc.
+ * - **Library independence**: History is global, not tied to a specific library
+ *
+ * ### ID Format: `provider:value`
+ *
+ * Examples:
+ * - `imdb:tt1234567` - IMDb ID for movies/episodes
+ * - `trakt:123456` - Trakt ID
+ * - `tmdb:550` - TMDb ID
+ * - `tvdb:12345` - TVDB ID for series/episodes
+ * - `redseat:abc123` - Local fallback when no external ID is available
+ *
+ * When marking content as watched via library endpoints (e.g., `setMovieWatched`),
+ * the server automatically resolves the local ID to an external ID.
+ */
 export interface IWatched {
+    /** Content type (episode, movie, etc.) */
     type: MediaType;
+    /**
+     * External ID in format `provider:value` (e.g., `imdb:tt1234567`).
+     * See interface documentation for details on the ID format.
+     */
     id: string;
+    /** User reference (for admin queries) */
     userRef?: string;
+    /** Timestamp when content was watched (unix milliseconds) */
     date: number;
+    /** Timestamp when entry was last modified (unix milliseconds) */
     modified: number;
 }
+/**
+ * Unwatched event data - emitted via SSE when content is removed from watch history.
+ *
+ * Unlike IWatched which has a single `id`, this uses `ids[]` array containing
+ * all possible external IDs (imdb, trakt, tmdb, local) so clients can match
+ * against any provider they have cached.
+ *
+ * This is a user-scoped event - not library-scoped.
+ */
+export interface IUnwatched {
+    /** Content type (episode, movie, etc.) */
+    type: MediaType;
+    /**
+     * All possible external IDs for this content.
+     * Format: `provider:value`
+     * Examples: ["imdb:tt0111161", "trakt:481", "tmdb:278"]
+     */
+    ids: string[];
+    /** User reference */
+    userRef?: string;
+    /** Timestamp when entry was removed (unix milliseconds) */
+    modified: number;
+}
+/**
+ * Request body for adding to watch history via POST /users/me/history.
+ *
+ * ## External ID Requirement
+ *
+ * When using the direct history endpoint, you must provide an external ID.
+ * The ID format is `provider:value`:
+ * - `imdb:tt1234567` - IMDb ID
+ * - `trakt:123456` - Trakt ID
+ * - `tmdb:550` - TMDb ID
+ * - `tvdb:12345` - TVDB ID
+ *
+ * **Tip**: For easier usage, prefer the library-specific endpoints
+ * (`setMovieWatched`, `setEpisodeWatched`) which automatically resolve IDs.
+ *
+ * @example
+ * ```typescript
+ * // Direct history endpoint - requires external ID
+ * await serverApi.addToHistory({
+ *     type: 'movie',
+ *     id: 'imdb:tt0111161',  // The Shawshank Redemption
+ *     date: Date.now()
+ * });
+ *
+ * // Library endpoint - uses local ID, server resolves to external
+ * await libraryApi.setMovieWatched('local-movie-id', Date.now());
+ * ```
+ */
 export interface IWatchedForAdd {
+    /** Content type (episode, movie, etc.) */
     type: MediaType;
+    /**
+     * External ID in format `provider:value` (e.g., `imdb:tt1234567`).
+     * See interface documentation for details on the ID format.
+     */
     id: string;
+    /** Timestamp when content was watched (unix milliseconds) */
     date: number;
 }
+/**
+ * View progress entry - returned from GET /users/me/history/progress/:id.
+ *
+ * Tracks playback position for resumable viewing.
+ * Uses the same external ID format as watch history.
+ */
 export interface IViewProgress {
+    /** Content type (episode, movie, etc.) */
     type: MediaType;
+    /**
+     * External ID in format `provider:value` (e.g., `imdb:tt1234567`).
+     */
     id: string;
+    /** User reference */
     userRef: string;
+    /** Playback progress in milliseconds */
     progress: number;
+    /** Parent ID for episodes (series external ID) */
     parent?: string;
+    /** Timestamp when progress was last modified (unix milliseconds) */
     modified: number;
 }
+/**
+ * Request body for updating view progress via POST /users/me/history/progress.
+ *
+ * Uses external IDs in format `provider:value` (e.g., `imdb:tt1234567`).
+ *
+ * @example
+ * ```typescript
+ * await serverApi.addProgress({
+ *     type: 'movie',
+ *     id: 'imdb:tt0111161',
+ *     progress: 3600000  // 1 hour in milliseconds
+ * });
+ * ```
+ */
 export interface IViewProgressForAdd {
+    /** Content type (episode, movie, etc.) */
     type: MediaType;
+    /**
+     * External ID in format `provider:value` (e.g., `imdb:tt1234567`).
+     */
     id: string;
+    /** Parent ID for episodes (series external ID) */
     parent?: string;
+    /** Playback progress in milliseconds */
     progress: number;
 }
+/**
+ * Query parameters for GET /users/me/history.
+ *
+ * @example
+ * ```typescript
+ * // Get recent movie history
+ * const history = await serverApi.getHistory({
+ *     types: ['movie'],
+ *     order: SqlOrder.DESC,
+ *     after: Date.now() - 86400000 * 30  // Last 30 days
+ * });
+ *
+ * // Check if specific content was watched
+ * const watched = await serverApi.getHistory({
+ *     id: 'imdb:tt0111161'
+ * });
+ * ```
+ */
 export interface HistoryQuery {
+    /** Sort field */
     sort?: RsSort;
+    /** Sort direction */
     order?: SqlOrder;
+    /** Filter entries watched before this timestamp (unix ms) */
     before?: number;
+    /** Filter entries watched after this timestamp (unix ms) */
     after?: number;
+    /** Filter by content types */
     types?: MediaType[];
+    /** Filter by specific external ID */
     id?: string;
+    /** Pagination key for next page */
     pageKey?: number;
 }
 export type MovieSort = 'modified' | 'added' | 'created' | 'name' | 'digitalairdate';

package/dist/sse-types.d.ts

@@ -1,4 +1,4 @@
-import { ILibrary, IFile, IEpisode, ISerie, IMovie, IPerson, ITag, IBackup } from './interfaces.js';
+import { ILibrary, IFile, IEpisode, ISerie, IMovie, IPerson, ITag, IBackup, IWatched, IUnwatched } from './interfaces.js';
 export type ElementAction = 'Added' | 'Updated' | 'Deleted';
 export type SSEConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 export interface SSEConnectionOptions {
@@ -134,6 +134,18 @@ export interface SSEPlayersListEvent {
     userRef: string;
     players: SSEPlayerEvent[];
 }
+/**
+ * SSE event emitted when content is marked as watched.
+ * This is a user-scoped event - not library-scoped.
+ * Uses external IDs (e.g., "imdb:tt0111161").
+ */
+export type SSEWatchedEvent = IWatched;
+/**
+ * SSE event emitted when content is removed from watch history.
+ * Contains all possible external IDs so clients can match against any cached ID.
+ * This is a user-scoped event - not library-scoped.
+ */
+export type SSEUnwatchedEvent = IUnwatched;
 export interface SSEEventMap {
     'library': SSELibraryEvent;
     'library-status': SSELibraryStatusEvent;
@@ -150,6 +162,8 @@ export interface SSEEventMap {
     'media_rating': SSEMediaRatingEvent;
     'media_progress': SSEMediaProgressEvent;
     'players-list': SSEPlayersListEvent;
+    'watched': SSEWatchedEvent;
+    'unwatched': SSEUnwatchedEvent;
 }
 export type SSEEventName = keyof SSEEventMap;
 export interface SSEEvent<T extends SSEEventName = SSEEventName> {