@redseat/api 0.3.6 → 0.3.11

package/libraries.md

@@ -899,12 +899,19 @@ const results = await libraryApi.searchSeries('Breaking');
 
 Marks an episode as watched.
 
+**How it works:** This method uses the local series/episode IDs from the library. The server automatically resolves these to external IDs (IMDb, Trakt, etc.) and stores the watch entry in the **global history** system. This means:
+- Watch status syncs across different servers
+- Watch status is accessible via `ServerApi.getHistory()`
+- External services can sync with your watch history
+
+See [server.md - Watch History API](server.md#watch-history-api) for details on the global history system.
+
 **Parameters:**
 
-- `serieId`: The ID of the series
+- `serieId`: The ID of the series (local library ID)
 - `season`: Season number
 - `number`: Episode number
-- `date`: Timestamp of when it was watched
+- `date`: Timestamp of when it was watched (unix milliseconds)
 
 **Example:**
 
@@ -918,48 +925,59 @@ Gets the watched status for an episode.
 
 **Parameters:**
 
-- `serieId`: The ID of the series
+- `serieId`: The ID of the series (local library ID)
 - `season`: Season number
 - `episode`: Episode number
 
-**Returns:** Promise resolving to an `IWatched` object containing watched date and metadata
+**Returns:** Promise resolving to an `IWatched` object containing:
+- `type`: Always `'episode'`
+- `id`: External ID in format `provider:value` (e.g., `imdb:tt0959621`)
+- `date`: Timestamp when watched
+- `modified`: Timestamp when entry was modified
 
 **Example:**
 
 ```typescript
 const watched = await libraryApi.getEpisodeWatched('serie-id', 1, 1);
 console.log(`Watched on: ${new Date(watched.date).toLocaleDateString()}`);
+console.log(`External ID: ${watched.id}`); // e.g., "imdb:tt0959621"
 ```
 
 ### `getEpisodeProgress(serieId: string, season: number, episode: number): Promise<IViewProgress>`
 
-Gets the view progress for an episode.
+Gets the view progress for an episode. Progress is stored in the global history system.
 
 **Parameters:**
 
-- `serieId`: The ID of the series
+- `serieId`: The ID of the series (local library ID)
 - `season`: Season number
 - `episode`: Episode number
 
-**Returns:** Promise resolving to an `IViewProgress` object containing progress value
+**Returns:** Promise resolving to an `IViewProgress` object containing:
+- `type`: Always `'episode'`
+- `id`: External ID in format `provider:value`
+- `progress`: Playback position in milliseconds
+- `parent`: Series external ID (if available)
+- `modified`: Timestamp when progress was last updated
 
 **Example:**
 
 ```typescript
 const progress = await libraryApi.getEpisodeProgress('serie-id', 1, 1);
 console.log(`Progress: ${progress.progress}ms`);
+console.log(`Episode ID: ${progress.id}`);
 ```
 
 ### `setEpisodeProgress(serieId: string, season: number, episode: number, progress: number): Promise<void>`
 
-Sets the view progress for an episode.
+Sets the view progress for an episode. Progress is stored in the global history system using external IDs.
 
 **Parameters:**
 
-- `serieId`: The ID of the series
+- `serieId`: The ID of the series (local library ID)
 - `season`: Season number
 - `episode`: Episode number
-- `progress`: Progress value (typically in milliseconds for video playback position)
+- `progress`: Progress value in milliseconds (video playback position)
 
 **Example:**
 
@@ -1079,10 +1097,17 @@ const images = await libraryApi.getMovieImages('movie-id');
 
 Marks a movie as watched.
 
+**How it works:** This method uses the local movie ID from the library. The server automatically resolves this to an external ID (IMDb, Trakt, TMDb, etc.) and stores the watch entry in the **global history** system. This means:
+- Watch status syncs across different servers
+- Watch status is accessible via `ServerApi.getHistory()`
+- External services can sync with your watch history
+
+See [server.md - Watch History API](server.md#watch-history-api) for details on the global history system.
+
 **Parameters:**
 
-- `movieId`: The ID of the movie
-- `date`: Timestamp of when it was watched
+- `movieId`: The ID of the movie (local library ID)
+- `date`: Timestamp of when it was watched (unix milliseconds)
 
 **Example:**
 
@@ -1096,42 +1121,52 @@ Gets the watched status for a movie.
 
 **Parameters:**
 
-- `movieId`: The ID of the movie
+- `movieId`: The ID of the movie (local library ID)
 
-**Returns:** Promise resolving to an `IWatched` object containing watched date and metadata
+**Returns:** Promise resolving to an `IWatched` object containing:
+- `type`: Always `'movie'`
+- `id`: External ID in format `provider:value` (e.g., `imdb:tt0111161`)
+- `date`: Timestamp when watched
+- `modified`: Timestamp when entry was modified
 
 **Example:**
 
 ```typescript
 const watched = await libraryApi.getMovieWatched('movie-id');
 console.log(`Watched on: ${new Date(watched.date).toLocaleDateString()}`);
+console.log(`External ID: ${watched.id}`); // e.g., "imdb:tt0111161"
 ```
 
 ### `getMovieProgress(movieId: string): Promise<IViewProgress>`
 
-Gets the view progress for a movie.
+Gets the view progress for a movie. Progress is stored in the global history system.
 
 **Parameters:**
 
-- `movieId`: The ID of the movie
+- `movieId`: The ID of the movie (local library ID)
 
-**Returns:** Promise resolving to an `IViewProgress` object containing progress value
+**Returns:** Promise resolving to an `IViewProgress` object containing:
+- `type`: Always `'movie'`
+- `id`: External ID in format `provider:value`
+- `progress`: Playback position in milliseconds
+- `modified`: Timestamp when progress was last updated
 
 **Example:**
 
 ```typescript
 const progress = await libraryApi.getMovieProgress('movie-id');
 console.log(`Progress: ${progress.progress}ms`);
+console.log(`External ID: ${progress.id}`);
 ```
 
 ### `setMovieProgress(movieId: string, progress: number): Promise<void>`
 
-Sets the view progress for a movie.
+Sets the view progress for a movie. Progress is stored in the global history system using external IDs.
 
 **Parameters:**
 
-- `movieId`: The ID of the movie
-- `progress`: Progress value (typically in milliseconds for video playback position)
+- `movieId`: The ID of the movie (local library ID)
+- `progress`: Progress value in milliseconds (video playback position)
 
 **Example:**
 
@@ -1934,6 +1969,158 @@ await libraryApi.clusterFaces('person-id');
 
 ---
 
+## Request Processing
+
+### `processRequest(request: RsRequest): Promise<RsRequest>`
+
+Process an unprocessed RsRequest and return the processed result.
+Takes a raw request and runs it through the server's plugin processing pipeline.
+
+**Parameters:**
+
+- `request`: The unprocessed request to process
+
+**Returns:** Promise resolving to the processed request with updated status and metadata
+
+**Example:**
+
+```typescript
+import { RsRequestStatus, RsRequestMethod } from '@redseat/api';
+
+const unprocessedRequest: RsRequest = {
+	url: 'https://example.com/video.mp4',
+	method: RsRequestMethod.Get,
+	status: RsRequestStatus.Unprocessed,
+	permanent: false,
+	ignoreOriginDuplicate: false
+};
+const processed = await libraryApi.processRequest(unprocessedRequest);
+console.log(processed.status); // RsRequestStatus.Processed
+```
+
+### `processRequestStream(request: RsRequest): Promise<AxiosResponse>`
+
+Process a request and return the raw HTTP stream response for direct streaming.
+
+**Parameters:**
+
+- `request`: The request to process and stream
+
+**Returns:** Raw axios response - use `response.data` for the stream
+
+**Example:**
+
+```typescript
+const request: RsRequest = {
+	url: 'https://example.com/video.mp4',
+	method: RsRequestMethod.Get,
+	status: RsRequestStatus.Processed,
+	permanent: false,
+	ignoreOriginDuplicate: false
+};
+const response = await libraryApi.processRequestStream(request);
+// response.data is the stream that can be piped directly
+```
+
+### `addRequest(request: RsRequest, mediaRef?: string): Promise<IRsRequestProcessing>`
+
+Add a request to the processing queue for background download/processing.
+
+**Parameters:**
+
+- `request`: The request to add for processing
+- `mediaRef`: Optional media reference to associate with the processing
+
+**Returns:** Promise resolving to the created `IRsRequestProcessing` entry
+
+**Example:**
+
+```typescript
+import { RsRequestStatus, RsRequestMethod } from '@redseat/api';
+
+const request: RsRequest = {
+	url: 'https://example.com/large-video.mp4',
+	method: RsRequestMethod.Get,
+	status: RsRequestStatus.Unprocessed,
+	permanent: false,
+	ignoreOriginDuplicate: false
+};
+
+// Add to processing queue
+const processing = await libraryApi.addRequest(request);
+console.log(processing.id); // Processing ID
+console.log(processing.status); // "pending" | "processing" | "paused" | "finished" | "error"
+console.log(processing.progress); // 0-100
+
+// Associate with existing media
+const processingWithMedia = await libraryApi.addRequest(request, 'media-id');
+```
+
+### `listRequestProcessing(): Promise<IRsRequestProcessing[]>`
+
+List all active request processings for this library.
+
+**Returns:** Promise resolving to an array of `IRsRequestProcessing` entries
+
+**Example:**
+
+```typescript
+const processings = await libraryApi.listRequestProcessing();
+for (const p of processings) {
+	console.log(`${p.id}: ${p.status} (${p.progress}%)`);
+	if (p.error) {
+		console.log(`  Error: ${p.error}`);
+	}
+	if (p.mediaRef) {
+		console.log(`  Media: ${p.mediaRef}`);
+	}
+}
+```
+
+### `pauseRequestProcessing(processingId: string): Promise<IRsRequestProcessing>`
+
+Pause a request processing task. This stops the download/processing temporarily.
+
+**Parameters:**
+
+- `processingId`: The ID of the processing task to pause
+
+**Returns:** Promise resolving to the updated `IRsRequestProcessing` entry with status "paused"
+
+**Example:**
+
+```typescript
+const processings = await libraryApi.listRequestProcessing();
+const activeProcessing = processings.find(p => p.status === 'processing');
+
+if (activeProcessing) {
+	const paused = await libraryApi.pauseRequestProcessing(activeProcessing.id);
+	console.log(`Paused: ${paused.id}, status: ${paused.status}`); // status: "paused"
+}
+```
+
+### `deleteRequestProcessing(processingId: string): Promise<void>`
+
+Delete/remove a request processing task from the queue. This cancels and removes the processing entry.
+
+**Parameters:**
+
+- `processingId`: The ID of the processing task to delete
+
+**Example:**
+
+```typescript
+const processings = await libraryApi.listRequestProcessing();
+const processingToRemove = processings.find(p => p.status === 'error');
+
+if (processingToRemove) {
+	await libraryApi.deleteRequestProcessing(processingToRemove.id);
+	console.log(`Removed processing: ${processingToRemove.id}`);
+}
+```
+
+---
+
 ## Encryption
 
 These methods are convenience wrappers around the encryption module. For detailed encryption documentation, see [encryption.md](encryption.md).

package/package.json

@@ -1,50 +1,50 @@
-{
-    "name": "@redseat/api",
-    "version": "0.3.6",
-    "description": "TypeScript API client library for interacting with Redseat servers",
-    "type": "module",
-    "main": "./dist/index.js",
-    "module": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "files": [
-        "dist/**/*",
-        "README.md",
-        "*.md"
-    ],
-    "keywords": [
-        "redseat",
-        "api",
-        "client",
-        "typescript"
-    ],
-    "author": "Arnaud JEZEQUEL <arnaud.jezequel@gmail.com>",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/yourusername/redseat-svelte.git",
-        "directory": "packages/api"
-    },
-    "scripts": {
-        "build": "tsc",
-        "test": "vitest run",
-        "test:watch": "vitest"
-    },
-    "dependencies": {
-        "axios": "^1.11.0",
-        "rxjs": "^7.8.2"
-    },
-    "devDependencies": {
-        "typescript": "^5.8.3",
-        "vite": "^7.3.0",
-        "vitest": "^4.0.16"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
+{
+    "name": "@redseat/api",
+    "version": "0.3.11",
+    "description": "TypeScript API client library for interacting with Redseat servers",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "*.md"
+    ],
+    "keywords": [
+        "redseat",
+        "api",
+        "client",
+        "typescript"
+    ],
+    "author": "Arnaud JEZEQUEL <arnaud.jezequel@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/yourusername/redseat-svelte.git",
+        "directory": "packages/api"
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "axios": "^1.11.0",
+        "rxjs": "^7.8.2"
+    },
+    "devDependencies": {
+        "typescript": "^5.8.3",
+        "vite": "^7.3.0",
+        "vitest": "^4.0.16"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }