@redseat/api 0.2.6 → 0.2.8

package/dist/client.d.ts

@@ -1,6 +1,8 @@
 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, SSEMediasProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSEBackupsEvent, SSEBackupFilesEvent } from './sse-types.js';
 export interface ClientOptions {
     server: IServer;
     getIdToken: () => Promise<string>;
@@ -18,6 +20,32 @@ export declare class RedseatClient {
     private localServerUrl?;
     private tokenData?;
     private tokenRefreshPromise?;
+    private sseAbortController?;
+    private sseReconnectTimeout?;
+    private sseReconnectAttempts;
+    private sseOptions?;
+    private readonly _sseConnectionState;
+    private readonly _sseError;
+    private readonly _sseEvents;
+    readonly sseConnectionState$: Observable<SSEConnectionState>;
+    readonly sseError$: Observable<SSEConnectionError>;
+    readonly sseConnected$: Observable<boolean>;
+    readonly library$: Observable<SSELibraryEvent>;
+    readonly libraryStatus$: Observable<SSELibraryStatusEvent>;
+    readonly medias$: Observable<SSEMediasEvent>;
+    readonly mediasProgress$: Observable<SSEMediasProgressEvent>;
+    readonly convertProgress$: Observable<SSEConvertProgressEvent>;
+    readonly episodes$: Observable<SSEEpisodesEvent>;
+    readonly series$: Observable<SSESeriesEvent>;
+    readonly movies$: Observable<SSEMoviesEvent>;
+    readonly people$: Observable<SSEPeopleEvent>;
+    readonly tags$: Observable<SSETagsEvent>;
+    readonly backups$: Observable<SSEBackupsEvent>;
+    readonly backupFiles$: Observable<SSEBackupFilesEvent>;
+    /**
+     * Creates a typed observable for a specific SSE event type
+     */
+    private createEventStream;
     constructor(options: ClientOptions);
     private getRegularServerUrl;
     private detectLocalUrl;
@@ -57,4 +85,47 @@ export declare class RedseatClient {
      * Returns public server info (IServer).
      */
     getServer(serverId: string): Promise<IServer>;
+    /**
+     * Connects to the server's SSE endpoint for real-time updates.
+     * Automatically manages authentication and reconnection.
+     * @param options - Connection options including library filters and reconnection settings
+     */
+    connectSSE(options?: SSEConnectionOptions): Promise<void>;
+    /**
+     * Disconnects from the SSE endpoint and cleans up resources.
+     */
+    disconnectSSE(): void;
+    /**
+     * Disposes of all SSE resources and completes observables.
+     * Call this when the client is no longer needed.
+     */
+    dispose(): void;
+    /**
+     * Gets the current SSE connection state
+     */
+    get sseConnectionState(): SSEConnectionState;
+    /**
+     * Internal method to establish SSE connection
+     */
+    private _connectSSE;
+    /**
+     * Builds the SSE endpoint URL with optional library filters
+     */
+    private buildSSEUrl;
+    /**
+     * Processes the SSE stream and emits events
+     */
+    private processSSEStream;
+    /**
+     * Parses the SSE buffer and extracts complete events
+     */
+    private parseSSEBuffer;
+    /**
+     * Handles SSE errors and triggers reconnection if appropriate
+     */
+    private handleSSEError;
+    /**
+     * Schedules a reconnection attempt with exponential backoff
+     */
+    private scheduleReconnect;
 }

package/dist/client.js

@@ -1,7 +1,36 @@
 import axios from 'axios';
+import { BehaviorSubject, Subject, filter, map } from 'rxjs';
 import { fetchServerToken } from './auth.js';
 export class RedseatClient {
+    /**
+     * Creates a typed observable for a specific SSE event type
+     */
+    createEventStream(eventName) {
+        return this._sseEvents.pipe(filter((event) => event.event === eventName), map(event => event.data));
+    }
     constructor(options) {
+        this.sseReconnectAttempts = 0;
+        // RxJS subjects for SSE
+        this._sseConnectionState = new BehaviorSubject('disconnected');
+        this._sseError = new Subject();
+        this._sseEvents = new Subject();
+        // Public observables for SSE connection state
+        this.sseConnectionState$ = this._sseConnectionState.asObservable();
+        this.sseError$ = this._sseError.asObservable();
+        this.sseConnected$ = this._sseConnectionState.pipe(map(state => state === 'connected'));
+        // Typed event streams
+        this.library$ = this.createEventStream('library');
+        this.libraryStatus$ = this.createEventStream('library-status');
+        this.medias$ = this.createEventStream('medias');
+        this.mediasProgress$ = this.createEventStream('medias_progress');
+        this.convertProgress$ = this.createEventStream('convert_progress');
+        this.episodes$ = this.createEventStream('episodes');
+        this.series$ = this.createEventStream('series');
+        this.movies$ = this.createEventStream('movies');
+        this.people$ = this.createEventStream('people');
+        this.tags$ = this.createEventStream('tags');
+        this.backups$ = this.createEventStream('backups');
+        this.backupFiles$ = this.createEventStream('backups-files');
         this.server = options.server;
         this.redseatUrl = options.redseatUrl;
         this.getIdToken = options.getIdToken;
@@ -213,4 +242,260 @@ export class RedseatClient {
         });
         return response.data;
     }
+    // ==================== SSE Methods ====================
+    /**
+     * Connects to the server's SSE endpoint for real-time updates.
+     * Automatically manages authentication and reconnection.
+     * @param options - Connection options including library filters and reconnection settings
+     */
+    async connectSSE(options) {
+        // Disconnect any existing connection
+        this.disconnectSSE();
+        this.sseOptions = {
+            autoReconnect: true,
+            initialReconnectDelay: 1000,
+            maxReconnectDelay: 30000,
+            ...options
+        };
+        this.sseReconnectAttempts = 0;
+        await this._connectSSE();
+    }
+    /**
+     * Disconnects from the SSE endpoint and cleans up resources.
+     */
+    disconnectSSE() {
+        if (this.sseReconnectTimeout) {
+            clearTimeout(this.sseReconnectTimeout);
+            this.sseReconnectTimeout = undefined;
+        }
+        if (this.sseAbortController) {
+            this.sseAbortController.abort();
+            this.sseAbortController = undefined;
+        }
+        this._sseConnectionState.next('disconnected');
+    }
+    /**
+     * Disposes of all SSE resources and completes observables.
+     * Call this when the client is no longer needed.
+     */
+    dispose() {
+        this.disconnectSSE();
+        this._sseConnectionState.complete();
+        this._sseError.complete();
+        this._sseEvents.complete();
+    }
+    /**
+     * Gets the current SSE connection state
+     */
+    get sseConnectionState() {
+        return this._sseConnectionState.value;
+    }
+    /**
+     * Internal method to establish SSE connection
+     */
+    async _connectSSE() {
+        this._sseConnectionState.next('connecting');
+        try {
+            // Ensure we have a valid token
+            await this.ensureValidToken();
+            if (!this.tokenData) {
+                throw new Error('No authentication token available');
+            }
+            const url = this.buildSSEUrl();
+            this.sseAbortController = new AbortController();
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.tokenData.token}`,
+                    'Accept': 'text/event-stream',
+                    'Cache-Control': 'no-cache'
+                },
+                signal: this.sseAbortController.signal
+            });
+            if (!response.ok) {
+                if (response.status === 401) {
+                    throw Object.assign(new Error('Authentication failed'), { type: 'auth' });
+                }
+                throw Object.assign(new Error(`Server returned ${response.status}`), { type: 'server' });
+            }
+            if (!response.body) {
+                throw Object.assign(new Error('No response body'), { type: 'server' });
+            }
+            this._sseConnectionState.next('connected');
+            this.sseReconnectAttempts = 0;
+            // Process the stream
+            await this.processSSEStream(response.body);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                // Intentionally disconnected
+                return;
+            }
+            this.handleSSEError(error);
+        }
+    }
+    /**
+     * Builds the SSE endpoint URL with optional library filters
+     */
+    buildSSEUrl() {
+        let url = `${this.baseUrl}/sse`;
+        if (this.sseOptions?.libraries && this.sseOptions.libraries.length > 0) {
+            const params = new URLSearchParams();
+            this.sseOptions.libraries.forEach(lib => params.append('library', lib));
+            url = `${url}?${params.toString()}`;
+        }
+        return url;
+    }
+    /**
+     * Processes the SSE stream and emits events
+     */
+    async processSSEStream(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    // Stream ended - server closed connection
+                    this._sseConnectionState.next('disconnected');
+                    this.scheduleReconnect();
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const { events, remainingBuffer } = this.parseSSEBuffer(buffer);
+                buffer = remainingBuffer;
+                for (const event of events) {
+                    this._sseEvents.next(event);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                return;
+            }
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Parses the SSE buffer and extracts complete events
+     */
+    parseSSEBuffer(buffer) {
+        const events = [];
+        const lines = buffer.split('\n');
+        let currentEvent = {};
+        let processedUpTo = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Check if this is an incomplete line (last line without newline)
+            if (i === lines.length - 1 && !buffer.endsWith('\n')) {
+                break;
+            }
+            processedUpTo += line.length + 1; // +1 for the newline
+            if (line === '') {
+                // Empty line marks end of event
+                if (currentEvent.event && currentEvent.data !== undefined) {
+                    events.push(currentEvent);
+                }
+                currentEvent = {};
+                continue;
+            }
+            if (line.startsWith(':')) {
+                // Comment, ignore
+                continue;
+            }
+            const colonIndex = line.indexOf(':');
+            if (colonIndex === -1) {
+                continue;
+            }
+            const field = line.slice(0, colonIndex);
+            // Value starts after colon, skip optional space after colon
+            let value = line.slice(colonIndex + 1);
+            if (value.startsWith(' ')) {
+                value = value.slice(1);
+            }
+            switch (field) {
+                case 'event':
+                    currentEvent.event = value;
+                    break;
+                case 'data':
+                    try {
+                        currentEvent.data = JSON.parse(value);
+                    }
+                    catch {
+                        this._sseError.next({
+                            type: 'parse',
+                            message: `Failed to parse SSE data: ${value}`,
+                            timestamp: Date.now()
+                        });
+                    }
+                    break;
+                case 'id':
+                    currentEvent.id = value;
+                    break;
+                case 'retry':
+                    currentEvent.retry = parseInt(value, 10);
+                    break;
+            }
+        }
+        return {
+            events,
+            remainingBuffer: buffer.slice(processedUpTo)
+        };
+    }
+    /**
+     * Handles SSE errors and triggers reconnection if appropriate
+     */
+    handleSSEError(error) {
+        const sseError = {
+            type: 'network',
+            message: error instanceof Error ? error.message : 'Unknown error',
+            originalError: error instanceof Error ? error : undefined,
+            timestamp: Date.now()
+        };
+        // Determine error type
+        if (error && typeof error === 'object' && 'type' in error) {
+            sseError.type = error.type;
+        }
+        this._sseConnectionState.next('error');
+        this._sseError.next(sseError);
+        // Don't reconnect on auth errors
+        if (sseError.type === 'auth') {
+            return;
+        }
+        this.scheduleReconnect();
+    }
+    /**
+     * Schedules a reconnection attempt with exponential backoff
+     */
+    scheduleReconnect() {
+        if (!this.sseOptions?.autoReconnect) {
+            return;
+        }
+        if (this.sseOptions.maxReconnectAttempts !== undefined &&
+            this.sseReconnectAttempts >= this.sseOptions.maxReconnectAttempts) {
+            return;
+        }
+        const initialDelay = this.sseOptions.initialReconnectDelay ?? 1000;
+        const maxDelay = this.sseOptions.maxReconnectDelay ?? 30000;
+        // Exponential backoff with jitter
+        const exponentialDelay = initialDelay * Math.pow(2, this.sseReconnectAttempts);
+        const jitter = Math.random() * 1000;
+        const delay = Math.min(exponentialDelay + jitter, maxDelay);
+        this._sseConnectionState.next('reconnecting');
+        this.sseReconnectAttempts++;
+        this.sseReconnectTimeout = setTimeout(async () => {
+            // Refresh token before reconnecting
+            try {
+                await this.refreshToken();
+            }
+            catch {
+                // Token refresh failed, will try again on next reconnect
+            }
+            this._connectSSE();
+        }, delay);
+    }
 }

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './server.js';
 export * from './crypto.js';
 export * from './encryption.js';
 export * from './upload.js';
+export * from './sse-types.js';

package/dist/index.js

@@ -6,3 +6,4 @@ export * from './server.js';
 export * from './crypto.js';
 export * from './encryption.js';
 export * from './upload.js';
+export * from './sse-types.js';

package/dist/interfaces.d.ts

@@ -519,40 +519,18 @@ export interface RsRequest {
     audio?: string[];
     quality?: number;
     ignoreOriginDuplicate: boolean;
-}
-export interface MediaDownloadUrl {
-    url: string;
-    parse: boolean;
-    uploadId?: string;
-    ignoreOriginDuplicate?: boolean;
-    kind?: FileTypes;
-    filename?: string;
-    mime?: string;
-    description?: string;
-    length?: number;
-    thumbnailUrl?: string;
-    peopleLookup?: string[];
-    seriesLookup?: string[];
     tagsLookup?: string[];
-    season?: number;
-    episode?: number;
+    peopleLookup?: string[];
+    albumsLookup?: string[];
+    thumbnailUrl?: string;
+    originUrl?: string;
+    title?: string;
+    kind?: FileTypes;
 }
-export interface GroupMediaDownload<T> {
-    group?: boolean;
+export interface RsGroupDownload {
+    group: boolean;
     groupThumbnailUrl?: string;
     groupFilename?: string;
     groupMime?: string;
-    files: T[];
-    referer?: string;
-    headers?: string[];
-    cookies?: string[];
-    originUrl?: string;
-    title?: string;
-    ignoreOriginDuplicate?: boolean;
-    description?: string;
-    peopleLookup?: string[];
-    seriesLookup?: string[];
-    tagsLookup?: string[];
-    season?: number;
-    episode?: number;
+    requests: RsRequest[];
 }

package/dist/library.d.ts

@@ -1,4 +1,6 @@
-import { IFile, ITag, IPerson, ISerie, IMovie, MediaRequest, IEpisode, ExternalImage, IBackupFile, ILibrary, SerieInMedia, DeletedQuery, RsDeleted, MovieSort, RsSort, SqlOrder, RsRequest, DetectedFaceResult, UnassignFaceResponse, MediaDownloadUrl, GroupMediaDownload } from './interfaces.js';
+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 { SSEMediasEvent, SSEMediasProgressEvent, SSEConvertProgressEvent, SSEEpisodesEvent, SSESeriesEvent, SSEMoviesEvent, SSEPeopleEvent, SSETagsEvent, SSELibraryStatusEvent } from './sse-types.js';
 import { EncryptFileOptions, EncryptedFile } from './encryption.js';
 export interface MediaForUpdate {
     name?: string;
@@ -74,6 +76,15 @@ export interface LibraryHttpClient {
     }>;
     getFullUrl(path: string, params?: Record<string, string>): string;
     getAuthToken(): string;
+    readonly medias$?: Observable<SSEMediasEvent>;
+    readonly mediasProgress$?: Observable<SSEMediasProgressEvent>;
+    readonly convertProgress$?: Observable<SSEConvertProgressEvent>;
+    readonly episodes$?: Observable<SSEEpisodesEvent>;
+    readonly series$?: Observable<SSESeriesEvent>;
+    readonly movies$?: Observable<SSEMoviesEvent>;
+    readonly people$?: Observable<SSEPeopleEvent>;
+    readonly tags$?: Observable<SSETagsEvent>;
+    readonly libraryStatus$?: Observable<SSELibraryStatusEvent>;
 }
 export declare class LibraryApi {
     private client;
@@ -81,7 +92,27 @@ export declare class LibraryApi {
     private library;
     private key?;
     private keyText?;
+    private disposed;
+    readonly medias$: Observable<SSEMediasEvent>;
+    readonly mediasProgress$: Observable<SSEMediasProgressEvent>;
+    readonly convertProgress$: Observable<SSEConvertProgressEvent>;
+    readonly episodes$: Observable<SSEEpisodesEvent>;
+    readonly series$: Observable<SSESeriesEvent>;
+    readonly movies$: Observable<SSEMoviesEvent>;
+    readonly people$: Observable<SSEPeopleEvent>;
+    readonly tags$: Observable<SSETagsEvent>;
+    readonly libraryStatus$: Observable<SSELibraryStatusEvent>;
     constructor(client: LibraryHttpClient, libraryId: string, library: ILibrary);
+    /**
+     * Creates a library-filtered stream from a client stream.
+     * Returns EMPTY if the client doesn't have SSE support.
+     */
+    private createLibraryFilteredStream;
+    /**
+     * Marks this LibraryApi as disposed.
+     * After calling dispose(), the filtered streams will stop emitting events.
+     */
+    dispose(): void;
     setKey(passPhrase: string): Promise<void>;
     private getUrl;
     getTags(query?: {
@@ -331,19 +362,13 @@ export declare class LibraryApi {
         thumbMime?: string;
         progressCallback?: (loaded: number, total: number) => void;
     }): Promise<IFile>;
-    /**
-     * Upload a media from a request (URL-based download)
-     * @param request - The request containing URL and metadata for the media to download
-     * @returns The created media file entry
-     */
-    uploadRequest(request: RsRequest): Promise<IFile>;
     /**
      * Upload a group of media files from URLs
-     * @param download - The group download request containing multiple URLs and shared metadata
+     * @param download - The group download request containing requests array
      * @param options - Optional settings (spawn: true to run in background)
      * @returns Array of created media files when spawn=false, or { downloading: true } when spawn=true
      */
-    uploadGroup(download: GroupMediaDownload<MediaDownloadUrl>, options?: {
+    uploadGroup(download: RsGroupDownload, options?: {
         spawn?: boolean;
     }): Promise<IFile[] | {
         downloading: boolean;

package/dist/library.js

@@ -1,10 +1,39 @@
+import { filter, EMPTY } from 'rxjs';
 import { deriveKey, encryptText as encryptTextUtil, decryptText as decryptTextUtil, encryptBuffer, decryptBuffer, encryptFile as encryptFileUtil, decryptFile as decryptFileUtil, decryptFileThumb, encryptFilename as encryptFilenameUtil, getRandomIV as getRandomIVUtil } from './encryption.js';
 import { uint8ArrayFromBase64 } from './crypto.js';
 export class LibraryApi {
     constructor(client, libraryId, library) {
         this.client = client;
         this.libraryId = libraryId;
+        this.disposed = false;
         this.library = library;
+        // Create library-filtered streams
+        this.medias$ = this.createLibraryFilteredStream(client.medias$);
+        this.mediasProgress$ = this.createLibraryFilteredStream(client.mediasProgress$);
+        this.convertProgress$ = this.createLibraryFilteredStream(client.convertProgress$);
+        this.episodes$ = this.createLibraryFilteredStream(client.episodes$);
+        this.series$ = this.createLibraryFilteredStream(client.series$);
+        this.movies$ = this.createLibraryFilteredStream(client.movies$);
+        this.people$ = this.createLibraryFilteredStream(client.people$);
+        this.tags$ = this.createLibraryFilteredStream(client.tags$);
+        this.libraryStatus$ = this.createLibraryFilteredStream(client.libraryStatus$);
+    }
+    /**
+     * Creates a library-filtered stream from a client stream.
+     * Returns EMPTY if the client doesn't have SSE support.
+     */
+    createLibraryFilteredStream(source$) {
+        if (!source$) {
+            return EMPTY;
+        }
+        return source$.pipe(filter(event => !this.disposed && event.library === this.libraryId));
+    }
+    /**
+     * Marks this LibraryApi as disposed.
+     * After calling dispose(), the filtered streams will stop emitting events.
+     */
+    dispose() {
+        this.disposed = true;
     }
     async setKey(passPhrase) {
         // Derive keys
@@ -824,18 +853,9 @@ export class LibraryApi {
         const res = await this.client.postForm(this.getUrl('/medias'), formData, config);
         return res.data;
     }
-    /**
-     * Upload a media from a request (URL-based download)
-     * @param request - The request containing URL and metadata for the media to download
-     * @returns The created media file entry
-     */
-    async uploadRequest(request) {
-        const res = await this.client.post(this.getUrl('/medias/request'), request);
-        return res.data;
-    }
     /**
      * Upload a group of media files from URLs
-     * @param download - The group download request containing multiple URLs and shared metadata
+     * @param download - The group download request containing requests array
      * @param options - Optional settings (spawn: true to run in background)
      * @returns Array of created media files when spawn=false, or { downloading: true } when spawn=true
      */