@redseat/api 0.2.7 → 0.2.8

package/client.md

@@ -310,6 +310,302 @@ The following methods are used internally and should not be called directly:
 - `detectLocalUrl()` - Detects local development server
 - `getRegularServerUrl()` - Gets production server URL
 
+---
+
+## Server-Sent Events (SSE)
+
+The `RedseatClient` provides real-time event streaming using Server-Sent Events (SSE). Events are delivered as RxJS Observables for easy integration with reactive programming patterns.
+
+### Connection Management
+
+#### `connectSSE(options?: SSEConnectionOptions): Promise<void>`
+
+Connects to the server's SSE endpoint for real-time updates.
+
+**Parameters:**
+- `options`: Optional connection configuration:
+  - `libraries?`: Array of library IDs to filter events to specific libraries
+  - `autoReconnect?`: Enable auto-reconnect on disconnect (default: `true`)
+  - `maxReconnectAttempts?`: Maximum reconnect attempts (default: unlimited)
+  - `initialReconnectDelay?`: Initial reconnect delay in ms (default: `1000`)
+  - `maxReconnectDelay?`: Maximum reconnect delay in ms (default: `30000`)
+
+**Example:**
+```typescript
+// Connect with default options
+await client.connectSSE();
+
+// Connect with library filter
+await client.connectSSE({
+    libraries: ['library-123', 'library-456']
+});
+
+// Connect with custom reconnection settings
+await client.connectSSE({
+    autoReconnect: true,
+    maxReconnectAttempts: 10,
+    initialReconnectDelay: 2000,
+    maxReconnectDelay: 60000
+});
+```
+
+#### `disconnectSSE(): void`
+
+Disconnects from the SSE endpoint and cleans up resources.
+
+**Example:**
+```typescript
+client.disconnectSSE();
+```
+
+#### `dispose(): void`
+
+Disposes of all SSE resources and completes all observables. Call this when the client is no longer needed.
+
+**Example:**
+```typescript
+client.dispose();
+```
+
+#### `sseConnectionState: SSEConnectionState`
+
+Gets the current SSE connection state. Possible values:
+- `'disconnected'` - Not connected
+- `'connecting'` - Connection in progress
+- `'connected'` - Successfully connected
+- `'reconnecting'` - Attempting to reconnect after disconnect
+- `'error'` - Connection error occurred
+
+**Example:**
+```typescript
+if (client.sseConnectionState === 'connected') {
+    console.log('SSE is connected');
+}
+```
+
+### Connection State Observables
+
+#### `sseConnectionState$: Observable<SSEConnectionState>`
+
+Observable that emits connection state changes.
+
+**Example:**
+```typescript
+client.sseConnectionState$.subscribe(state => {
+    console.log('SSE connection state:', state);
+});
+```
+
+#### `sseConnected$: Observable<boolean>`
+
+Observable that emits `true` when connected, `false` otherwise.
+
+**Example:**
+```typescript
+client.sseConnected$.subscribe(connected => {
+    if (connected) {
+        console.log('SSE connected');
+    } else {
+        console.log('SSE disconnected');
+    }
+});
+```
+
+#### `sseError$: Observable<SSEConnectionError>`
+
+Observable that emits connection errors.
+
+**Example:**
+```typescript
+client.sseError$.subscribe(error => {
+    console.error(`SSE error (${error.type}): ${error.message}`);
+});
+```
+
+### Event Streams
+
+All event streams are typed RxJS Observables. Subscribe to receive real-time updates from the server.
+
+#### `library$: Observable<SSELibraryEvent>`
+
+Emits when libraries are added, updated, or deleted.
+
+```typescript
+client.library$.subscribe(event => {
+    console.log(`Library ${event.action}: ${event.library.name}`);
+});
+```
+
+#### `libraryStatus$: Observable<SSELibraryStatusEvent>`
+
+Emits library status updates (e.g., scanning progress).
+
+```typescript
+client.libraryStatus$.subscribe(event => {
+    console.log(`Library ${event.library}: ${event.message} (${event.progress}%)`);
+});
+```
+
+#### `medias$: Observable<SSEMediasEvent>`
+
+Emits when media files are added, updated, or deleted.
+
+```typescript
+client.medias$.subscribe(event => {
+    for (const { action, media } of event.medias) {
+        console.log(`Media ${action}: ${media.name}`);
+    }
+});
+```
+
+#### `mediasProgress$: Observable<SSEMediasProgressEvent>`
+
+Emits media processing progress updates.
+
+```typescript
+client.mediasProgress$.subscribe(event => {
+    console.log(`Media ${event.mediaId}: ${event.progress}%`);
+});
+```
+
+#### `convertProgress$: Observable<SSEConvertProgressEvent>`
+
+Emits video conversion progress updates.
+
+```typescript
+client.convertProgress$.subscribe(event => {
+    console.log(`Converting ${event.mediaId}: ${event.progress}% - ${event.status}`);
+});
+```
+
+#### `episodes$: Observable<SSEEpisodesEvent>`
+
+Emits when episodes are added, updated, or deleted.
+
+```typescript
+client.episodes$.subscribe(event => {
+    for (const { action, episode } of event.episodes) {
+        console.log(`Episode ${action}: ${episode.name}`);
+    }
+});
+```
+
+#### `series$: Observable<SSESeriesEvent>`
+
+Emits when series are added, updated, or deleted.
+
+```typescript
+client.series$.subscribe(event => {
+    for (const { action, serie } of event.series) {
+        console.log(`Series ${action}: ${serie.name}`);
+    }
+});
+```
+
+#### `movies$: Observable<SSEMoviesEvent>`
+
+Emits when movies are added, updated, or deleted.
+
+```typescript
+client.movies$.subscribe(event => {
+    for (const { action, movie } of event.movies) {
+        console.log(`Movie ${action}: ${movie.name}`);
+    }
+});
+```
+
+#### `people$: Observable<SSEPeopleEvent>`
+
+Emits when people are added, updated, or deleted.
+
+```typescript
+client.people$.subscribe(event => {
+    for (const { action, person } of event.people) {
+        console.log(`Person ${action}: ${person.name}`);
+    }
+});
+```
+
+#### `tags$: Observable<SSETagsEvent>`
+
+Emits when tags are added, updated, or deleted.
+
+```typescript
+client.tags$.subscribe(event => {
+    for (const { action, tag } of event.tags) {
+        console.log(`Tag ${action}: ${tag.name}`);
+    }
+});
+```
+
+#### `backups$: Observable<SSEBackupsEvent>`
+
+Emits backup status updates.
+
+```typescript
+client.backups$.subscribe(event => {
+    console.log(`Backup ${event.backup.name}: ${event.backup.status}`);
+});
+```
+
+#### `backupFiles$: Observable<SSEBackupFilesEvent>`
+
+Emits backup file progress updates.
+
+```typescript
+client.backupFiles$.subscribe(event => {
+    console.log(`Backing up ${event.file}: ${event.progress}%`);
+});
+```
+
+### Complete SSE Example
+
+```typescript
+import { RedseatClient } from '@redseat/api';
+import { Subscription } from 'rxjs';
+
+const client = new RedseatClient({
+    server: { id: 'server-123', url: 'example.com' },
+    getIdToken: async () => await getFirebaseToken()
+});
+
+// Track subscriptions for cleanup
+const subscriptions: Subscription[] = [];
+
+// Monitor connection state
+subscriptions.push(
+    client.sseConnectionState$.subscribe(state => {
+        console.log('SSE state:', state);
+    })
+);
+
+// Handle errors
+subscriptions.push(
+    client.sseError$.subscribe(error => {
+        console.error('SSE error:', error.message);
+    })
+);
+
+// Subscribe to events
+subscriptions.push(
+    client.medias$.subscribe(event => {
+        for (const { action, media } of event.medias) {
+            console.log(`Media ${action}: ${media.name}`);
+        }
+    })
+);
+
+// Connect to SSE
+await client.connectSSE();
+
+// ... later, cleanup
+subscriptions.forEach(sub => sub.unsubscribe());
+client.disconnectSSE();
+
+// Or dispose completely when client is no longer needed
+client.dispose();
+```
+
 ## See Also
 
 - [ServerApi Documentation](server.md) - Uses RedseatClient for server operations

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/library.d.ts

@@ -1,4 +1,6 @@
+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?: {

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

package/dist/sse-types.d.ts

@@ -0,0 +1,121 @@
+import { ILibrary, IFile, IEpisode, ISerie, IMovie, IPerson, ITag, IBackup } from './interfaces.js';
+export type ElementAction = 'Added' | 'Updated' | 'Deleted';
+export type SSEConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+export interface SSEConnectionOptions {
+    /** Filter to specific library IDs */
+    libraries?: string[];
+    /** Enable auto-reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Maximum reconnect attempts (default: unlimited) */
+    maxReconnectAttempts?: number;
+    /** Initial reconnect delay in ms (default: 1000) */
+    initialReconnectDelay?: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+}
+export interface SSEConnectionError {
+    type: 'network' | 'auth' | 'server' | 'parse';
+    message: string;
+    originalError?: Error;
+    timestamp: number;
+}
+export interface SSELibraryEvent {
+    action: ElementAction;
+    library: ILibrary;
+}
+export interface SSELibraryStatusEvent {
+    message: string;
+    library: string;
+    progress?: number;
+}
+export interface SSEMediasEvent {
+    library: string;
+    medias: {
+        action: ElementAction;
+        media: IFile;
+    }[];
+}
+export interface SSEMediasProgressEvent {
+    library: string;
+    mediaId: string;
+    progress: number;
+    status?: string;
+}
+export interface SSEConvertProgressEvent {
+    library: string;
+    mediaId: string;
+    progress: number;
+    status: string;
+    message?: string;
+}
+export interface SSEEpisodesEvent {
+    library: string;
+    episodes: {
+        action: ElementAction;
+        episode: IEpisode;
+    }[];
+}
+export interface SSESeriesEvent {
+    library: string;
+    series: {
+        action: ElementAction;
+        serie: ISerie;
+    }[];
+}
+export interface SSEMoviesEvent {
+    library: string;
+    movies: {
+        action: ElementAction;
+        movie: IMovie;
+    }[];
+}
+export interface SSEPeopleEvent {
+    library: string;
+    people: {
+        action: ElementAction;
+        person: IPerson;
+    }[];
+}
+export interface SSETagsEvent {
+    library: string;
+    tags: {
+        action: ElementAction;
+        tag: ITag;
+    }[];
+}
+export interface IBackupWithStatus extends IBackup {
+    status?: 'running' | 'completed' | 'failed';
+    progress?: number;
+    message?: string;
+}
+export interface SSEBackupsEvent {
+    backup: IBackupWithStatus;
+}
+export interface SSEBackupFilesEvent {
+    library?: string;
+    file: string;
+    progress: number;
+    status?: string;
+    message?: string;
+}
+export interface SSEEventMap {
+    'library': SSELibraryEvent;
+    'library-status': SSELibraryStatusEvent;
+    'medias': SSEMediasEvent;
+    'medias_progress': SSEMediasProgressEvent;
+    'convert_progress': SSEConvertProgressEvent;
+    'episodes': SSEEpisodesEvent;
+    'series': SSESeriesEvent;
+    'movies': SSEMoviesEvent;
+    'people': SSEPeopleEvent;
+    'tags': SSETagsEvent;
+    'backups': SSEBackupsEvent;
+    'backups-files': SSEBackupFilesEvent;
+}
+export type SSEEventName = keyof SSEEventMap;
+export interface SSEEvent<T extends SSEEventName = SSEEventName> {
+    id?: string;
+    event: T;
+    data: SSEEventMap[T];
+    retry?: number;
+}

package/dist/sse-types.js

@@ -0,0 +1 @@
+export {};

package/libraries.md

@@ -66,6 +66,172 @@ if (library.crypt) {
 
 **Note:** This method verifies the key by attempting to decrypt a media thumbnail. If decryption fails, it throws an error.
 
+### `dispose(): void`
+
+Marks the LibraryApi as disposed. After calling dispose(), the filtered event streams will stop emitting events.
+
+**Example:**
+
+```typescript
+libraryApi.dispose();
+```
+
+---
+
+## Real-Time Events (SSE)
+
+`LibraryApi` provides library-filtered event streams that automatically filter events to only include those relevant to the library. These streams require the `RedseatClient` to be connected to SSE.
+
+### Event Streams
+
+All event streams are RxJS Observables that emit events only for this library.
+
+#### `medias$: Observable<SSEMediasEvent>`
+
+Emits when media files in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.medias$.subscribe(event => {
+    for (const { action, media } of event.medias) {
+        console.log(`Media ${action}: ${media.name}`);
+    }
+});
+```
+
+#### `mediasProgress$: Observable<SSEMediasProgressEvent>`
+
+Emits media processing progress updates for this library.
+
+```typescript
+libraryApi.mediasProgress$.subscribe(event => {
+    console.log(`Media ${event.mediaId}: ${event.progress}%`);
+});
+```
+
+#### `convertProgress$: Observable<SSEConvertProgressEvent>`
+
+Emits video conversion progress updates for this library.
+
+```typescript
+libraryApi.convertProgress$.subscribe(event => {
+    console.log(`Converting ${event.mediaId}: ${event.progress}% - ${event.status}`);
+});
+```
+
+#### `episodes$: Observable<SSEEpisodesEvent>`
+
+Emits when episodes in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.episodes$.subscribe(event => {
+    for (const { action, episode } of event.episodes) {
+        console.log(`Episode ${action}: ${episode.name}`);
+    }
+});
+```
+
+#### `series$: Observable<SSESeriesEvent>`
+
+Emits when series in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.series$.subscribe(event => {
+    for (const { action, serie } of event.series) {
+        console.log(`Series ${action}: ${serie.name}`);
+    }
+});
+```
+
+#### `movies$: Observable<SSEMoviesEvent>`
+
+Emits when movies in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.movies$.subscribe(event => {
+    for (const { action, movie } of event.movies) {
+        console.log(`Movie ${action}: ${movie.name}`);
+    }
+});
+```
+
+#### `people$: Observable<SSEPeopleEvent>`
+
+Emits when people in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.people$.subscribe(event => {
+    for (const { action, person } of event.people) {
+        console.log(`Person ${action}: ${person.name}`);
+    }
+});
+```
+
+#### `tags$: Observable<SSETagsEvent>`
+
+Emits when tags in this library are added, updated, or deleted.
+
+```typescript
+libraryApi.tags$.subscribe(event => {
+    for (const { action, tag } of event.tags) {
+        console.log(`Tag ${action}: ${tag.name}`);
+    }
+});
+```
+
+#### `libraryStatus$: Observable<SSELibraryStatusEvent>`
+
+Emits status updates for this library (e.g., scanning progress).
+
+```typescript
+libraryApi.libraryStatus$.subscribe(event => {
+    console.log(`Status: ${event.message} (${event.progress}%)`);
+});
+```
+
+### Complete SSE Example with LibraryApi
+
+```typescript
+import { RedseatClient, LibraryApi, ServerApi } from '@redseat/api';
+import { Subscription } from 'rxjs';
+
+const client = new RedseatClient({
+    server: { id: 'server-123', url: 'example.com' },
+    getIdToken: async () => await getFirebaseToken()
+});
+
+// Connect to SSE first
+await client.connectSSE();
+
+// Get library and create LibraryApi
+const serverApi = new ServerApi(client);
+const libraries = await serverApi.getLibraries();
+const library = libraries[0];
+const libraryApi = new LibraryApi(client, library.id!, library);
+
+// Track subscriptions
+const subscriptions: Subscription[] = [];
+
+// Subscribe to library-specific events
+subscriptions.push(
+    libraryApi.medias$.subscribe(event => {
+        for (const { action, media } of event.medias) {
+            console.log(`[${library.name}] Media ${action}: ${media.name}`);
+        }
+    })
+);
+
+subscriptions.push(
+    libraryApi.libraryStatus$.subscribe(event => {
+        console.log(`[${library.name}] ${event.message}`);
+    })
+);
+
+// ... later, cleanup
+subscriptions.forEach(sub => sub.unsubscribe());
+libraryApi.dispose();
+client.disconnectSSE();
+```
+
 ---
 
 ## Tags

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseat/api",
-    "version": "0.2.7",
+    "version": "0.2.8",
     "description": "TypeScript API client library for interacting with Redseat servers",
     "type": "module",
     "main": "./dist/index.js",