@redseat/api 0.3.5 → 0.3.7

package/client.md

@@ -1,670 +1,670 @@
-# RedseatClient
-
-The `RedseatClient` class is the low-level HTTP client that handles all communication with Redseat servers. It provides automatic token management, local server detection, and request/response interceptors.
-
-## Overview
-
-`RedseatClient` wraps Axios and adds:
-- Automatic token refresh before expiration
-- Local server detection (for development)
-- 401 error handling with automatic retry
-- Request/response interceptors for authentication
-
-## Constructor
-
-```typescript
-new RedseatClient(options: ClientOptions)
-```
-
-### ClientOptions Interface
-
-```typescript
-interface ClientOptions {
-    server: IServer;
-    getIdToken: () => Promise<string>;
-    refreshThreshold?: number; // milliseconds before expiration to refresh (default: 5 minutes)
-}
-```
-
-**Parameters:**
-- `server`: Server configuration object with `id`, `url`, and optional `port`
-- `getIdToken`: Async function that returns the current ID token from your auth provider
-- `refreshThreshold`: Optional. Milliseconds before token expiration to trigger refresh (default: 300000 = 5 minutes)
-
-**Example:**
-```typescript
-const client = new RedseatClient({
-    server: {
-        id: 'server-123',
-        url: 'example.com',
-        port: 443
-    },
-    getIdToken: async () => {
-        // Get ID token from your auth provider (Firebase, Auth0, etc.)
-        return await getCurrentUserToken();
-    },
-    refreshThreshold: 5 * 60 * 1000 // 5 minutes
-});
-```
-
-## Features
-
-### Automatic Token Refresh
-
-The client automatically refreshes tokens before they expire. The refresh happens:
-- Before each request if the token is expired or expiring soon
-- When a 401 error is received (with automatic retry)
-
-### Local Server Detection
-
-The client automatically detects if a local development server is available by checking `local.{server.url}`. If detected, it uses the local URL instead of the production URL.
-
-### Request Interceptor
-
-All requests are intercepted to:
-1. Check if token needs refresh
-2. Add `Authorization: Bearer {token}` header
-
-### Response Interceptor
-
-All responses are intercepted to:
-1. Handle 401 errors by refreshing token and retrying the request
-2. Prevent infinite retry loops with `_retry` flag
-
-## Methods
-
-### `get<T>(url: string, config?: AxiosRequestConfig)`
-
-Performs a GET request.
-
-**Parameters:**
-- `url`: The endpoint URL (relative to base URL)
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.get<IFile[]>('/libraries/123/medias');
-const medias = response.data;
-```
-
-### `post<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a POST request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.post<ITag>('/libraries/123/tags', {
-    name: 'Vacation'
-});
-const tag = response.data;
-```
-
-### `postForm<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a POST request with FormData. This method is specifically designed for multipart/form-data uploads and provides better compatibility with React Native environments compared to using `post` with FormData.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: FormData object or data to send as form data
-- `config`: Optional Axios request configuration (supports `onUploadProgress` for progress tracking)
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const formData = new FormData();
-formData.append('info', JSON.stringify({ name: 'photo.jpg', size: 1024 }));
-formData.append('file', fileBlob, 'photo.jpg');
-
-const response = await client.postForm<IFile>('/libraries/123/medias', formData, {
-    onUploadProgress: (progressEvent) => {
-        if (progressEvent.total) {
-            const percent = (progressEvent.loaded / progressEvent.total) * 100;
-            console.log(`Upload progress: ${percent}%`);
-        }
-    }
-});
-const uploadedFile = response.data;
-```
-
-**Note:** Use `postForm` instead of `post` when sending FormData, especially in React Native applications, as it properly handles multipart/form-data headers and encoding.
-
-### `put<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a PUT request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const formData = new FormData();
-formData.append('file', fileBlob);
-const response = await client.put('/libraries/123/medias/transfert', formData);
-```
-
-### `patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a PATCH request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.patch<ITag>('/libraries/123/tags/tag-id', {
-    rename: 'New Tag Name'
-});
-const updatedTag = response.data;
-```
-
-### `delete<T>(url: string, config?: AxiosRequestConfig)`
-
-Performs a DELETE request.
-
-**Parameters:**
-- `url`: The endpoint URL
-- `config`: Optional Axios request configuration (can include `data` for request body)
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-// Simple delete
-await client.delete('/libraries/123/tags/tag-id');
-
-// Delete with body
-await client.delete('/libraries/123/medias', {
-    data: { ids: ['media-1', 'media-2'] }
-});
-```
-
-### `request<T>(method: Method, url: string, data?: unknown, config?: AxiosRequestConfig)`
-
-Performs a custom HTTP request.
-
-**Parameters:**
-- `method`: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', etc.)
-- `url`: The endpoint URL
-- `data`: Request body data
-- `config`: Optional Axios request configuration
-
-**Returns:** `Promise<AxiosResponse<T>>`
-
-**Example:**
-```typescript
-const response = await client.request<IFile>(
-    'GET',
-    '/libraries/123/medias/media-id',
-    undefined,
-    { responseType: 'blob' }
-);
-```
-
-### `setToken(token: string | IToken)`
-
-Manually set the authentication token. Useful when you already have a valid token.
-
-**Parameters:**
-- `token`: Either a token string or an `IToken` object with `token` and `expires` properties
-
-**Example:**
-```typescript
-// Set as string (will be treated as expiring soon)
-client.setToken('your-token-string');
-
-// Set as IToken object with expiration
-client.setToken({
-    token: 'your-token-string',
-    expires: Date.now() + 3600000 // 1 hour from now
-});
-```
-
-## Error Handling
-
-The client automatically handles:
-- **401 Unauthorized**: Refreshes token and retries the request once
-- **Token expiration**: Refreshes token before making requests
-- **Network errors**: Passes through to caller
-
-**Example error handling:**
-```typescript
-try {
-    const response = await client.get('/libraries/123/medias');
-} catch (error) {
-    if (error.response?.status === 401) {
-        // Token refresh failed or invalid credentials
-        console.error('Authentication failed');
-    } else if (error.response?.status === 404) {
-        // Resource not found
-        console.error('Resource not found');
-    } else {
-        // Other error
-        console.error('Request failed:', error.message);
-    }
-}
-```
-
-## Usage with Response Types
-
-The client supports specifying response types for binary data:
-
-```typescript
-// Get as stream
-const stream = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'stream'
-});
-
-// Get as ArrayBuffer
-const buffer = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'arraybuffer'
-});
-
-// Get as Blob
-const blob = await client.get('/libraries/123/medias/media-id', {
-    responseType: 'blob'
-});
-```
-
-## Progress Tracking
-
-For file uploads, you can track progress. Use `postForm` for FormData uploads (recommended for React Native compatibility):
-
-```typescript
-const formData = new FormData();
-formData.append('file', fileBlob);
-
-await client.postForm('/libraries/123/medias', formData, {
-    onUploadProgress: (progressEvent) => {
-        if (progressEvent.total) {
-            const percent = (progressEvent.loaded / progressEvent.total) * 100;
-            console.log(`Upload progress: ${percent}%`);
-        }
-    }
-});
-```
-
-## Internal Methods (Private)
-
-The following methods are used internally and should not be called directly:
-- `refreshToken()` - Refreshes the authentication token
-- `ensureValidToken()` - Ensures token is valid before requests
-- `isTokenExpiredOrExpiringSoon()` - Checks if token needs refresh
-- `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}`);
-    }
-});
-```
-
-#### `uploadProgress$: Observable<SSEUploadProgressEvent>`
-
-Emits upload progress updates including download, transfer, and analysis stages.
-
-```typescript
-client.uploadProgress$.subscribe(event => {
-    const { progress } = event;
-    const percent = progress.total ? Math.round((progress.current ?? 0) / progress.total * 100) : 0;
-    console.log(`Upload ${progress.id} (${progress.type}): ${percent}% - ${progress.filename}`);
-});
-```
-
-#### `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}%`);
-});
-```
-
-#### `mediaRating$: Observable<SSEMediaRatingEvent>`
-
-Emits when a user rates a media item.
-
-```typescript
-client.mediaRating$.subscribe(event => {
-    console.log(`User ${event.rating.userRef} rated media ${event.rating.mediaRef}: ${event.rating.rating}`);
-});
-```
-
-**Event structure:**
-- `library`: Library ID where the media is located
-- `rating.userRef`: User who rated
-- `rating.mediaRef`: Media that was rated
-- `rating.rating`: Rating value (0-5)
-- `rating.modified`: Timestamp of the rating
-
-#### `mediaProgress$: Observable<SSEMediaProgressEvent>`
-
-Emits when a user's playback progress is updated.
-
-```typescript
-client.mediaProgress$.subscribe(event => {
-    console.log(`User ${event.progress.userRef} watched ${event.progress.mediaRef} to ${event.progress.progress}ms`);
-});
-```
-
-**Event structure:**
-- `library`: Library ID where the media is located
-- `progress.userRef`: User whose progress updated
-- `progress.mediaRef`: Media being tracked
-- `progress.progress`: Current playback position in milliseconds
-- `progress.modified`: Timestamp of the update
-
-#### `playersList$: Observable<SSEPlayersListEvent>`
-
-Emits the full list of available media players for the user when it changes.
-
-```typescript
-client.playersList$.subscribe(event => {
-    console.log(`Available players for ${event.userRef}:`);
-    for (const player of event.players) {
-        console.log(`  - ${player.name} (${player.player})`);
-    }
-});
-```
-
-**Event structure:**
-- `userRef`: User ID
-- `players`: Array of available players
-  - `id`: Player socket ID (for casting)
-  - `name`: Player display name
-  - `player`: Player type identifier
-
-### 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
-- [LibraryApi Documentation](libraries.md) - Uses RedseatClient for library operations
-- [README](README.md) - Package overview
-
+# RedseatClient
+
+The `RedseatClient` class is the low-level HTTP client that handles all communication with Redseat servers. It provides automatic token management, local server detection, and request/response interceptors.
+
+## Overview
+
+`RedseatClient` wraps Axios and adds:
+- Automatic token refresh before expiration
+- Local server detection (for development)
+- 401 error handling with automatic retry
+- Request/response interceptors for authentication
+
+## Constructor
+
+```typescript
+new RedseatClient(options: ClientOptions)
+```
+
+### ClientOptions Interface
+
+```typescript
+interface ClientOptions {
+    server: IServer;
+    getIdToken: () => Promise<string>;
+    refreshThreshold?: number; // milliseconds before expiration to refresh (default: 5 minutes)
+}
+```
+
+**Parameters:**
+- `server`: Server configuration object with `id`, `url`, and optional `port`
+- `getIdToken`: Async function that returns the current ID token from your auth provider
+- `refreshThreshold`: Optional. Milliseconds before token expiration to trigger refresh (default: 300000 = 5 minutes)
+
+**Example:**
+```typescript
+const client = new RedseatClient({
+    server: {
+        id: 'server-123',
+        url: 'example.com',
+        port: 443
+    },
+    getIdToken: async () => {
+        // Get ID token from your auth provider (Firebase, Auth0, etc.)
+        return await getCurrentUserToken();
+    },
+    refreshThreshold: 5 * 60 * 1000 // 5 minutes
+});
+```
+
+## Features
+
+### Automatic Token Refresh
+
+The client automatically refreshes tokens before they expire. The refresh happens:
+- Before each request if the token is expired or expiring soon
+- When a 401 error is received (with automatic retry)
+
+### Local Server Detection
+
+The client automatically detects if a local development server is available by checking `local.{server.url}`. If detected, it uses the local URL instead of the production URL.
+
+### Request Interceptor
+
+All requests are intercepted to:
+1. Check if token needs refresh
+2. Add `Authorization: Bearer {token}` header
+
+### Response Interceptor
+
+All responses are intercepted to:
+1. Handle 401 errors by refreshing token and retrying the request
+2. Prevent infinite retry loops with `_retry` flag
+
+## Methods
+
+### `get<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a GET request.
+
+**Parameters:**
+- `url`: The endpoint URL (relative to base URL)
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.get<IFile[]>('/libraries/123/medias');
+const medias = response.data;
+```
+
+### `post<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a POST request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.post<ITag>('/libraries/123/tags', {
+    name: 'Vacation'
+});
+const tag = response.data;
+```
+
+### `postForm<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a POST request with FormData. This method is specifically designed for multipart/form-data uploads and provides better compatibility with React Native environments compared to using `post` with FormData.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: FormData object or data to send as form data
+- `config`: Optional Axios request configuration (supports `onUploadProgress` for progress tracking)
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const formData = new FormData();
+formData.append('info', JSON.stringify({ name: 'photo.jpg', size: 1024 }));
+formData.append('file', fileBlob, 'photo.jpg');
+
+const response = await client.postForm<IFile>('/libraries/123/medias', formData, {
+    onUploadProgress: (progressEvent) => {
+        if (progressEvent.total) {
+            const percent = (progressEvent.loaded / progressEvent.total) * 100;
+            console.log(`Upload progress: ${percent}%`);
+        }
+    }
+});
+const uploadedFile = response.data;
+```
+
+**Note:** Use `postForm` instead of `post` when sending FormData, especially in React Native applications, as it properly handles multipart/form-data headers and encoding.
+
+### `put<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PUT request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+const response = await client.put('/libraries/123/medias/transfert', formData);
+```
+
+### `patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PATCH request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.patch<ITag>('/libraries/123/tags/tag-id', {
+    rename: 'New Tag Name'
+});
+const updatedTag = response.data;
+```
+
+### `delete<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a DELETE request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `config`: Optional Axios request configuration (can include `data` for request body)
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+// Simple delete
+await client.delete('/libraries/123/tags/tag-id');
+
+// Delete with body
+await client.delete('/libraries/123/medias', {
+    data: { ids: ['media-1', 'media-2'] }
+});
+```
+
+### `request<T>(method: Method, url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a custom HTTP request.
+
+**Parameters:**
+- `method`: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', etc.)
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.request<IFile>(
+    'GET',
+    '/libraries/123/medias/media-id',
+    undefined,
+    { responseType: 'blob' }
+);
+```
+
+### `setToken(token: string | IToken)`
+
+Manually set the authentication token. Useful when you already have a valid token.
+
+**Parameters:**
+- `token`: Either a token string or an `IToken` object with `token` and `expires` properties
+
+**Example:**
+```typescript
+// Set as string (will be treated as expiring soon)
+client.setToken('your-token-string');
+
+// Set as IToken object with expiration
+client.setToken({
+    token: 'your-token-string',
+    expires: Date.now() + 3600000 // 1 hour from now
+});
+```
+
+## Error Handling
+
+The client automatically handles:
+- **401 Unauthorized**: Refreshes token and retries the request once
+- **Token expiration**: Refreshes token before making requests
+- **Network errors**: Passes through to caller
+
+**Example error handling:**
+```typescript
+try {
+    const response = await client.get('/libraries/123/medias');
+} catch (error) {
+    if (error.response?.status === 401) {
+        // Token refresh failed or invalid credentials
+        console.error('Authentication failed');
+    } else if (error.response?.status === 404) {
+        // Resource not found
+        console.error('Resource not found');
+    } else {
+        // Other error
+        console.error('Request failed:', error.message);
+    }
+}
+```
+
+## Usage with Response Types
+
+The client supports specifying response types for binary data:
+
+```typescript
+// Get as stream
+const stream = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'stream'
+});
+
+// Get as ArrayBuffer
+const buffer = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'arraybuffer'
+});
+
+// Get as Blob
+const blob = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'blob'
+});
+```
+
+## Progress Tracking
+
+For file uploads, you can track progress. Use `postForm` for FormData uploads (recommended for React Native compatibility):
+
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+
+await client.postForm('/libraries/123/medias', formData, {
+    onUploadProgress: (progressEvent) => {
+        if (progressEvent.total) {
+            const percent = (progressEvent.loaded / progressEvent.total) * 100;
+            console.log(`Upload progress: ${percent}%`);
+        }
+    }
+});
+```
+
+## Internal Methods (Private)
+
+The following methods are used internally and should not be called directly:
+- `refreshToken()` - Refreshes the authentication token
+- `ensureValidToken()` - Ensures token is valid before requests
+- `isTokenExpiredOrExpiringSoon()` - Checks if token needs refresh
+- `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}`);
+    }
+});
+```
+
+#### `uploadProgress$: Observable<SSEUploadProgressEvent>`
+
+Emits upload progress updates including download, transfer, and analysis stages.
+
+```typescript
+client.uploadProgress$.subscribe(event => {
+    const { progress } = event;
+    const percent = progress.total ? Math.round((progress.current ?? 0) / progress.total * 100) : 0;
+    console.log(`Upload ${progress.id} (${progress.type}): ${percent}% - ${progress.filename}`);
+});
+```
+
+#### `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}%`);
+});
+```
+
+#### `mediaRating$: Observable<SSEMediaRatingEvent>`
+
+Emits when a user rates a media item.
+
+```typescript
+client.mediaRating$.subscribe(event => {
+    console.log(`User ${event.rating.userRef} rated media ${event.rating.mediaRef}: ${event.rating.rating}`);
+});
+```
+
+**Event structure:**
+- `library`: Library ID where the media is located
+- `rating.userRef`: User who rated
+- `rating.mediaRef`: Media that was rated
+- `rating.rating`: Rating value (0-5)
+- `rating.modified`: Timestamp of the rating
+
+#### `mediaProgress$: Observable<SSEMediaProgressEvent>`
+
+Emits when a user's playback progress is updated.
+
+```typescript
+client.mediaProgress$.subscribe(event => {
+    console.log(`User ${event.progress.userRef} watched ${event.progress.mediaRef} to ${event.progress.progress}ms`);
+});
+```
+
+**Event structure:**
+- `library`: Library ID where the media is located
+- `progress.userRef`: User whose progress updated
+- `progress.mediaRef`: Media being tracked
+- `progress.progress`: Current playback position in milliseconds
+- `progress.modified`: Timestamp of the update
+
+#### `playersList$: Observable<SSEPlayersListEvent>`
+
+Emits the full list of available media players for the user when it changes.
+
+```typescript
+client.playersList$.subscribe(event => {
+    console.log(`Available players for ${event.userRef}:`);
+    for (const player of event.players) {
+        console.log(`  - ${player.name} (${player.player})`);
+    }
+});
+```
+
+**Event structure:**
+- `userRef`: User ID
+- `players`: Array of available players
+  - `id`: Player socket ID (for casting)
+  - `name`: Player display name
+  - `player`: Player type identifier
+
+### 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
+- [LibraryApi Documentation](libraries.md) - Uses RedseatClient for library operations
+- [README](README.md) - Package overview
+