@redseat/api 0.3.5 → 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,6 +483,193 @@ 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';
 export interface DeletedQuery {
     after?: number;

package/dist/library.d.ts

@@ -1,5 +1,5 @@
 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 } from './interfaces.js';
+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 { EncryptFileOptions, EncryptedFile } from './encryption.js';
 export interface MediaForUpdate {
@@ -194,6 +194,9 @@ export declare class LibraryApi {
     updateMovie(movieId: string, updates: Partial<IMovie>): Promise<IMovie>;
     getMovieImages(movieId: string): Promise<ExternalImage[]>;
     setMovieWatched(movieId: string, date: number): Promise<void>;
+    getMovieWatched(movieId: string): Promise<IWatched>;
+    getMovieProgress(movieId: string): Promise<IViewProgress>;
+    setMovieProgress(movieId: string, progress: number): Promise<void>;
     searchMovies(name: string): Promise<IMovie[]>;
     movieRename(movieId: string, newName: string): Promise<IMovie>;
     updateMoviePoster(movieId: string, poster: FormData, type: string): Promise<void>;
@@ -214,6 +217,9 @@ export declare class LibraryApi {
     updatePersonPortrait(personId: string, portrait: FormData): Promise<void>;
     searchSeries(name: string): Promise<ISerie[]>;
     setEpisodeWatched(serieId: string, season: number, number: number, date: number): Promise<void>;
+    getEpisodeWatched(serieId: string, season: number, episode: number): Promise<IWatched>;
+    getEpisodeProgress(serieId: string, season: number, episode: number): Promise<IViewProgress>;
+    setEpisodeProgress(serieId: string, season: number, episode: number, progress: number): Promise<void>;
     /**
      * Searches for available media sources for a specific episode.
      * @param serieId - The series identifier

package/dist/library.js

@@ -368,6 +368,17 @@ export class LibraryApi {
     async setMovieWatched(movieId, date) {
         await this.client.post(this.getUrl(`/movies/${movieId}/watched`), { date });
     }
+    async getMovieWatched(movieId) {
+        const res = await this.client.get(this.getUrl(`/movies/${movieId}/watched`));
+        return res.data;
+    }
+    async getMovieProgress(movieId) {
+        const res = await this.client.get(this.getUrl(`/movies/${movieId}/progress`));
+        return res.data;
+    }
+    async setMovieProgress(movieId, progress) {
+        await this.client.post(this.getUrl(`/movies/${movieId}/progress`), { progress });
+    }
     async searchMovies(name) {
         const res = await this.client.get(this.getUrl(`/movies/search?name=${name}`));
         return res.data;
@@ -460,6 +471,17 @@ export class LibraryApi {
     async setEpisodeWatched(serieId, season, number, date) {
         await this.client.post(this.getUrl(`/series/${serieId}/seasons/${season}/episodes/${number}/watched`), { date });
     }
+    async getEpisodeWatched(serieId, season, episode) {
+        const res = await this.client.get(this.getUrl(`/series/${serieId}/seasons/${season}/episodes/${episode}/watched`));
+        return res.data;
+    }
+    async getEpisodeProgress(serieId, season, episode) {
+        const res = await this.client.get(this.getUrl(`/series/${serieId}/seasons/${season}/episodes/${episode}/progress`));
+        return res.data;
+    }
+    async setEpisodeProgress(serieId, season, episode, progress) {
+        await this.client.post(this.getUrl(`/series/${serieId}/seasons/${season}/episodes/${episode}/progress`), { progress });
+    }
     /**
      * Searches for available media sources for a specific episode.
      * @param serieId - The series identifier

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { RedseatClient } from './client.js';
-import { ILibrary, IPlugin, ICredential } from './interfaces.js';
+import { ILibrary, IPlugin, ICredential, IWatched, IWatchedForAdd, IViewProgress, IViewProgressForAdd, HistoryQuery } from './interfaces.js';
 export declare class ServerApi {
     private client;
     constructor(client: RedseatClient);
@@ -19,4 +19,10 @@ export declare class ServerApi {
     deleteCredential(id: string): Promise<void>;
     saveOAuthCredentials(pluginId: string, params: Record<string, string>): Promise<void>;
     addLibraryCredential(credential: any): Promise<ILibrary>;
+    getHistory(query?: HistoryQuery): Promise<IWatched[]>;
+    addToHistory(watched: IWatchedForAdd): Promise<void>;
+    getProgressById(id: string): Promise<IViewProgress | null>;
+    addProgress(progress: IViewProgressForAdd): Promise<void>;
+    getAdminHistory(): Promise<IWatched[]>;
+    importHistory(watcheds: IWatchedForAdd[]): Promise<void>;
 }

package/dist/server.js

@@ -48,4 +48,44 @@ export class ServerApi {
         const res = await this.client.post('/libraries/credential', credential);
         return res.data;
     }
+    // History methods
+    async getHistory(query) {
+        const params = {};
+        if (query) {
+            if (query.sort !== undefined)
+                params.sort = query.sort;
+            if (query.order !== undefined)
+                params.order = query.order;
+            if (query.before !== undefined)
+                params.before = query.before;
+            if (query.after !== undefined)
+                params.after = query.after;
+            if (query.types !== undefined && query.types.length > 0)
+                params.types = query.types;
+            if (query.id !== undefined)
+                params.id = query.id;
+            if (query.pageKey !== undefined)
+                params.pageKey = query.pageKey;
+        }
+        const res = await this.client.get('/users/me/history', { params });
+        return res.data;
+    }
+    async addToHistory(watched) {
+        await this.client.post('/users/me/history', watched);
+    }
+    async getProgressById(id) {
+        const res = await this.client.get(`/users/me/history/progress/${id}`);
+        return res.data;
+    }
+    async addProgress(progress) {
+        await this.client.post('/users/me/history/progress', progress);
+    }
+    // Admin history methods
+    async getAdminHistory() {
+        const res = await this.client.get('/users/admin/history');
+        return res.data;
+    }
+    async importHistory(watcheds) {
+        await this.client.post('/users/admin/history/import', watcheds);
+    }
 }

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> {