@redseat/api 0.3.6 → 0.3.11

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, SSERequestProcessingEvent } from './sse-types.js';
 export interface ClientOptions {
     server: IServer;
     getIdToken: () => Promise<string>;
@@ -45,6 +45,9 @@ export declare class RedseatClient {
     readonly mediaRating$: Observable<SSEMediaRatingEvent>;
     readonly mediaProgress$: Observable<SSEMediaProgressEvent>;
     readonly playersList$: Observable<SSEPlayersListEvent>;
+    readonly watched$: Observable<SSEWatchedEvent>;
+    readonly unwatched$: Observable<SSEUnwatchedEvent>;
+    readonly requestProcessing$: Observable<SSERequestProcessingEvent>;
     /**
      * 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

@@ -17,6 +17,12 @@ export class RedseatClient {
             'library-status': 'libraryStatus',
             'backups-files': 'backupsFiles',
             'players-list': 'Players',
+            'episodes': 'episodes',
+            'series': 'series',
+            'movies': 'movies',
+            'people': 'people',
+            'tags': 'tags',
+            'request_processing': 'requestProcessing',
         };
         const wrapperKey = wrapperMap[eventName];
         return this._sseEvents.pipe(filter((event) => event.event === eventName), map(event => {
@@ -55,6 +61,9 @@ 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.requestProcessing$ = this.createEventStream('request_processing');
         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';
@@ -580,6 +731,8 @@ export interface RsRequest {
     size?: number;
     filename?: string;
     status: RsRequestStatus;
+    pluginName?: string;
+    pluginId?: string;
     permanent: boolean;
     instant?: boolean;
     jsonBody?: any;
@@ -617,3 +770,31 @@ export interface RsGroupDownload {
     groupMime?: string;
     requests: RsRequest[];
 }
+/**
+ * Request processing status from plugin-based download/processing.
+ * Tracks progress of downloads, file processing, etc.
+ */
+export interface IRsRequestProcessing {
+    /** Internal nanoid */
+    id: string;
+    /** Plugin's processing ID */
+    processingId: string;
+    /** Plugin handling the request */
+    pluginId: string;
+    /** Progress 0-100 */
+    progress: number;
+    /** Status: "pending" | "processing" | "paused" | "finished" | "error" */
+    status: string;
+    /** Error message if status is "error" */
+    error?: string;
+    /** UTC timestamp (ms) for estimated completion */
+    eta?: number;
+    /** Reference to media being processed */
+    mediaRef?: string;
+    /** The original request */
+    originalRequest?: RsRequest;
+    /** Last modified timestamp */
+    modified: number;
+    /** Creation timestamp */
+    added: number;
+}

package/dist/library.d.ts

@@ -1,6 +1,7 @@
 import { Observable } from 'rxjs';
-import { IFile, ITag, IPerson, ISerie, IMovie, MediaRequest, IEpisode, ExternalImage, IBackupFile, ILibrary, SerieInMedia, DeletedQuery, RsDeleted, MovieSort, RsSort, SqlOrder, RsRequest, DetectedFaceResult, UnassignFaceResponse, RsGroupDownload, IViewProgress, IWatched } from './interfaces.js';
-import { SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSELibraryStatusEvent, SSEMediaRatingEvent, SSEMediaProgressEvent } from './sse-types.js';
+import type { AxiosResponse } from 'axios';
+import { IFile, ITag, IPerson, ISerie, IMovie, MediaRequest, IEpisode, ExternalImage, IBackupFile, ILibrary, SerieInMedia, DeletedQuery, RsDeleted, MovieSort, RsSort, SqlOrder, RsRequest, DetectedFaceResult, UnassignFaceResponse, RsGroupDownload, IViewProgress, IWatched, IRsRequestProcessing } from './interfaces.js';
+import { SSEMediasEvent, SSEUploadProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSELibraryStatusEvent, SSEMediaRatingEvent, SSEMediaProgressEvent, SSERequestProcessingEvent } from './sse-types.js';
 import { EncryptFileOptions, EncryptedFile } from './encryption.js';
 export interface MediaForUpdate {
     name?: string;
@@ -87,6 +88,7 @@ export interface LibraryHttpClient {
     readonly libraryStatus$?: Observable<SSELibraryStatusEvent>;
     readonly mediaRating$?: Observable<SSEMediaRatingEvent>;
     readonly mediaProgress$?: Observable<SSEMediaProgressEvent>;
+    readonly requestProcessing$?: Observable<SSERequestProcessingEvent>;
 }
 export declare class LibraryApi {
     private client;
@@ -106,6 +108,7 @@ export declare class LibraryApi {
     readonly libraryStatus$: Observable<SSELibraryStatusEvent>;
     readonly mediaRating$: Observable<SSEMediaRatingEvent>;
     readonly mediaProgress$: Observable<SSEMediaProgressEvent>;
+    readonly requestProcessing$: Observable<SSERequestProcessingEvent>;
     constructor(client: LibraryHttpClient, libraryId: string, library: ILibrary);
     /**
      * Creates a library-filtered stream from a client stream.
@@ -253,6 +256,43 @@ export declare class LibraryApi {
     checkRequestInstant(request: RsRequest): Promise<{
         instant: boolean;
     }>;
+    /**
+     * Process an unprocessed RsRequest and return the processed result.
+     * Takes a raw request and runs it through the server's plugin processing pipeline.
+     * @param request - The unprocessed request to process
+     * @returns The processed request with updated status and metadata
+     */
+    processRequest(request: RsRequest): Promise<RsRequest>;
+    /**
+     * Process a request and return the raw HTTP stream response.
+     * Use this to stream content directly without processing the full response.
+     * @param request - The request to process and stream
+     * @returns Raw axios response with stream data - use response.data for the stream
+     */
+    processRequestStream(request: RsRequest): Promise<AxiosResponse>;
+    /**
+     * Add a request to the processing queue.
+     * @param request - The request to add for processing
+     * @param mediaRef - Optional media reference to associate with the processing
+     * @returns The created request processing entry
+     */
+    addRequest(request: RsRequest, mediaRef?: string): Promise<IRsRequestProcessing>;
+    /**
+     * List all active request processings for this library.
+     * @returns Array of request processing entries
+     */
+    listRequestProcessing(): Promise<IRsRequestProcessing[]>;
+    /**
+     * Pause a request processing task.
+     * @param processingId - The ID of the processing task to pause
+     * @returns The updated request processing entry with status "paused"
+     */
+    pauseRequestProcessing(processingId: string): Promise<IRsRequestProcessing>;
+    /**
+     * Delete/remove a request processing task.
+     * @param processingId - The ID of the processing task to delete
+     */
+    deleteRequestProcessing(processingId: string): Promise<void>;
     /**
      * Get a share token for a request URL.
      * The token can be used to stream/download the resource without authentication.

package/dist/library.js

@@ -19,6 +19,7 @@ export class LibraryApi {
         this.libraryStatus$ = this.createLibraryFilteredStream(client.libraryStatus$);
         this.mediaRating$ = this.createLibraryFilteredStream(client.mediaRating$);
         this.mediaProgress$ = this.createLibraryFilteredStream(client.mediaProgress$);
+        this.requestProcessing$ = this.createLibraryFilteredStream(client.requestProcessing$);
     }
     /**
      * Creates a library-filtered stream from a client stream.
@@ -525,6 +526,59 @@ export class LibraryApi {
         const res = await this.client.post(this.getUrl('/plugins/requests/check-instant'), request);
         return res.data;
     }
+    /**
+     * Process an unprocessed RsRequest and return the processed result.
+     * Takes a raw request and runs it through the server's plugin processing pipeline.
+     * @param request - The unprocessed request to process
+     * @returns The processed request with updated status and metadata
+     */
+    async processRequest(request) {
+        const res = await this.client.post(this.getUrl('/plugins/requests/process'), request);
+        return res.data;
+    }
+    /**
+     * Process a request and return the raw HTTP stream response.
+     * Use this to stream content directly without processing the full response.
+     * @param request - The request to process and stream
+     * @returns Raw axios response with stream data - use response.data for the stream
+     */
+    async processRequestStream(request) {
+        return this.client.post(this.getUrl('/plugins/requests/process/stream'), request, { responseType: 'stream' });
+    }
+    /**
+     * Add a request to the processing queue.
+     * @param request - The request to add for processing
+     * @param mediaRef - Optional media reference to associate with the processing
+     * @returns The created request processing entry
+     */
+    async addRequest(request, mediaRef) {
+        const res = await this.client.post(this.getUrl('/plugins/requests/add'), { request, mediaRef });
+        return res.data;
+    }
+    /**
+     * List all active request processings for this library.
+     * @returns Array of request processing entries
+     */
+    async listRequestProcessing() {
+        const res = await this.client.get(this.getUrl('/plugins/requests/processing'));
+        return res.data;
+    }
+    /**
+     * Pause a request processing task.
+     * @param processingId - The ID of the processing task to pause
+     * @returns The updated request processing entry with status "paused"
+     */
+    async pauseRequestProcessing(processingId) {
+        const res = await this.client.post(this.getUrl(`/plugins/requests/processing/${processingId}/pause`));
+        return res.data;
+    }
+    /**
+     * Delete/remove a request processing task.
+     * @param processingId - The ID of the processing task to delete
+     */
+    async deleteRequestProcessing(processingId) {
+        await this.client.delete(this.getUrl(`/plugins/requests/processing/${processingId}`));
+    }
     /**
      * Get a share token for a request URL.
      * The token can be used to stream/download the resource without authentication.

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, IRsRequestProcessing } from './interfaces.js';
 export type ElementAction = 'Added' | 'Updated' | 'Deleted';
 export type SSEConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 export interface SSEConnectionOptions {
@@ -134,6 +134,30 @@ 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;
+/**
+ * SSE event for request processing status updates.
+ * Tracks plugin-based request processing (downloads, file processing, etc.).
+ * This is a library-scoped event.
+ */
+export interface SSERequestProcessingEvent {
+    library: string;
+    processings: {
+        action: ElementAction;
+        processing: IRsRequestProcessing;
+    }[];
+}
 export interface SSEEventMap {
     'library': SSELibraryEvent;
     'library-status': SSELibraryStatusEvent;
@@ -150,6 +174,9 @@ export interface SSEEventMap {
     'media_rating': SSEMediaRatingEvent;
     'media_progress': SSEMediaProgressEvent;
     'players-list': SSEPlayersListEvent;
+    'watched': SSEWatchedEvent;
+    'unwatched': SSEUnwatchedEvent;
+    'request_processing': SSERequestProcessingEvent;
 }
 export type SSEEventName = keyof SSEEventMap;
 export interface SSEEvent<T extends SSEEventName = SSEEventName> {