@ctrl/sabnzbd 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Scott Cooper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# SABnzbd
+
+> TypeScript api wrapper for [SABnzbd](https://sabnzbd.org/) using [ofetch](https://github.com/unjs/ofetch)
+
+### Overview
+
+Includes the normalized usenet API shared with `@ctrl/nzbget`:
+
+- [`getAllData()`](#getalldata)
+- [`getQueue()`](#getqueue)
+- [`getHistory()`](#gethistory)
+- [`getQueueJob(id)`](#getqueuejobid)
+- [`getHistoryJob(id)`](#gethistoryjobid)
+- [`findJob(id)`](#findjobid)
+- [`addNzbFile(...)` / `addNzbUrl(...)`](#addnzbfile--addnzburl)
+- [`normalizedAddNzb(...)`](#normalizedaddnzb)
+- queue control methods return `boolean`
+- `addNzbFile` and `addNzbUrl` return the normalized queue id as a `string`
+
+Use the normalized methods by default. Drop to the native SABnzbd methods only when you need SAB-specific behavior such as script changes, post-process changes, rename operations, or raw queue/history responses.
+
+### Install
+
+```console
+npm install @ctrl/sabnzbd
+```
+
+### Use
+
+```ts
+import { Sabnzbd } from '@ctrl/sabnzbd';
+
+const client = new Sabnzbd({
+  baseUrl: 'http://localhost:8080/',
+  apiKey: 'api-key',
+});
+
+async function main() {
+  const data = await client.getAllData();
+  console.log(data.queue);
+}
+```
+
+### Normalized Example
+
+```ts
+import { Sabnzbd, UsenetNotFoundError, UsenetPriority } from '@ctrl/sabnzbd';
+
+const client = new Sabnzbd({
+  baseUrl: 'http://localhost:8080/',
+  apiKey: 'api-key',
+});
+
+async function main() {
+  const id = await client.addNzbUrl('https://example.test/release.nzb', {
+    category: 'movies',
+    priority: UsenetPriority.high,
+    startPaused: false,
+  });
+
+  try {
+    const job = await client.getQueueJob(id);
+    console.log(job.state, job.progress);
+  } catch (error) {
+    if (error instanceof UsenetNotFoundError) {
+      console.log('job missing', error.id);
+    }
+  }
+}
+```
+
+### API
+
+Docs: https://sabnzbd.ep.workers.dev  
+SABnzbd API Docs: https://sabnzbd.org/wiki/configuration/4.5/api
+
+### Normalized Methods
+
+##### `getAllData()`
+
+Returns queue, history, categories, scripts, and status in normalized form. This is the broadest normalized read and fits best when you want an overview in one call.
+
+##### `getQueue()`
+
+Returns normalized active queue items.
+
+##### `getHistory()`
+
+Returns normalized history items.
+
+##### `getQueueJob(id)`
+
+Returns one normalized active queue item. Missing ids throw `UsenetNotFoundError`.
+
+##### `getHistoryJob(id)`
+
+Returns one normalized history item. Missing ids throw `UsenetNotFoundError`.
+
+##### `findJob(id)`
+
+Searches queue first, then history, and returns `{ source, job }` or `null`. It is the convenient path when you do not know which side the id should be on.
+
+##### `addNzbFile(...)` / `addNzbUrl(...)`
+
+Add an NZB and return the normalized queue id as a `string`. These are the lighter add helpers when an id is enough.
+The normalized add option names are `category`, `priority`, `postProcess`, `postProcessScript`, `name`, `password`, and `startPaused`.
+
+##### `normalizedAddNzb(...)`
+
+Add an NZB from either a URL or file content and return the created normalized queue item. This is the higher-level add helper when you want the normalized job back immediately.
+
+##### Normalized state labels
+
+`stateMessage` uses the shared `UsenetStateMessage` vocabulary:
+`Grabbing`, `Queued`, `Downloading`, `Paused`, `Post-processing`, `Completed`, `Failed`, `Warning`, `Deleted`, and `Unknown`.
+
+### Native API
+
+SABnzbd-specific methods are still available when you need the raw client surface.
+
+Connection and discovery:
+
+- `auth()`
+- `getVersion()`
+- `getFullStatus()`
+- `getWarnings()`
+- `clearWarnings()`
+- `getServerStats()`
+- `listQueue(query?)`
+- `listHistory(query?)`
+- `getCategories()`
+- `getScripts()`
+- `getFiles(id)`
+
+Queue and job mutation:
+
+- `deleteJob(id, deleteFiles?)`
+- `shutdown()`
+- `restart()`
+- `restartRepair()`
+- `pausePostProcessing()`
+- `resumePostProcessing()`
+- `fetchRss()`
+- `scanWatchedFolder()`
+- `resetQuota()`
+- `changeCategory(id, category)`
+- `changeScript(id, script)`
+- `changePriority(id, priority)`
+- `changePostProcess(id, postProcess)`
+- `renameJob(id, name, password?)`
+- `setSpeedLimit(limit)`
+
+Raw add methods:
+
+- `addUrl(url, options?)`
+- `addFile(nzb, options?)`
+
+##### export and create from state
+
+```ts
+const state = client.exportState();
+const restored = Sabnzbd.createFromState(config, state);
+```
+
+### Local Integration Testing
+
+Use a disposable SABnzbd instance on `localhost:8080` with its config mounted at `/tmp/sabnzbd-local-test`.
+
+```console
+docker run -d --name sabnzbd-local-test \
+  -p 8080:8080 \
+  -v /tmp/sabnzbd-local-test:/config \
+  lscr.io/linuxserver/sabnzbd:latest
+```
+
+Wait for first-run setup to create `sabnzbd.ini`:
+
+```console
+ls -l /tmp/sabnzbd-local-test/sabnzbd.ini
+```
+
+Read the generated API key:
+
+```console
+docker exec sabnzbd-local-test sed -n 's/^api_key = //p' /config/sabnzbd.ini
+```
+
+Run only the integration spec:
+
+```console
+TEST_SABNZBD_URL=http://127.0.0.1:8080 \
+TEST_SABNZBD_API_KEY=$(docker exec sabnzbd-local-test sed -n 's/^api_key = //p' /config/sabnzbd.ini) \
+pnpm test test/integration.spec.ts
+```
+
+Run the full test suite:
+
+```console
+TEST_SABNZBD_URL=http://127.0.0.1:8080 \
+TEST_SABNZBD_API_KEY=$(docker exec sabnzbd-local-test sed -n 's/^api_key = //p' /config/sabnzbd.ini) \
+pnpm test
+```
+
+The integration spec in [`test/integration.spec.ts`](/Users/scooper/gh/sabnzbd/test/integration.spec.ts) defaults to this exact setup:
+
+- `baseUrl` defaults to `http://127.0.0.1:8080`
+- `apiKey` is read from `/tmp/sabnzbd-local-test/sabnzbd.ini` if `TEST_SABNZBD_API_KEY` is unset

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from '@ctrl/shared-usenet';
+export * from './types.js';
+export * from './normalizeUsenetData.js';
+export * from './sabnzbd.js';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from '@ctrl/shared-usenet';
+export * from './types.js';
+export * from './normalizeUsenetData.js';
+export * from './sabnzbd.js';

package/dist/src/normalizeUsenetData.d.ts

@@ -0,0 +1,7 @@
+import { type NormalizedUsenetHistoryItem, type NormalizedUsenetJob, type NormalizedUsenetStatus, UsenetPriority } from '@ctrl/shared-usenet';
+import type { SabFullStatus, SabHistorySlot, SabPriorityValue, SabRawPriorityValue, SabQueue, SabQueueSlot } from './types.js';
+export declare function sabPriorityToNormalized(priority: SabRawPriorityValue | undefined): UsenetPriority;
+export declare function normalizedPriorityToSab(priority: UsenetPriority | undefined): SabPriorityValue;
+export declare function normalizeSabJob(slot: SabQueueSlot): NormalizedUsenetJob;
+export declare function normalizeSabHistoryItem(item: SabHistorySlot): NormalizedUsenetHistoryItem;
+export declare function normalizeSabStatus(queue: SabQueue, fullStatus: SabFullStatus): NormalizedUsenetStatus;

package/dist/src/normalizeUsenetData.js

@@ -0,0 +1,231 @@
+import { UsenetJobState, UsenetPriority, UsenetStateMessage, } from '@ctrl/shared-usenet';
+const BYTES_PER_MEGABYTE = 1024 * 1024;
+function toNumber(value) {
+    const parsed = Number.parseFloat(String(value ?? '0').replaceAll(',', ''));
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function megabytesToBytes(value) {
+    return Math.round(toNumber(value) * BYTES_PER_MEGABYTE);
+}
+function parseSabDuration(value) {
+    if (!value) {
+        return 0;
+    }
+    const parts = value.split(':').map(part => Number.parseInt(part, 10));
+    if (parts.some(part => Number.isNaN(part))) {
+        return 0;
+    }
+    if (parts.length === 3) {
+        const [hours = 0, minutes = 0, seconds = 0] = parts;
+        return hours * 3600 + minutes * 60 + seconds;
+    }
+    if (parts.length === 2) {
+        const [minutes = 0, seconds = 0] = parts;
+        return minutes * 60 + seconds;
+    }
+    return parts[0] ?? 0;
+}
+function normalizeIsoDate(value) {
+    if (typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value))) {
+        const numericValue = Number(value);
+        if (numericValue > 0) {
+            const timestamp = numericValue > 1_000_000_000_000 ? numericValue : numericValue * 1000;
+            return new Date(timestamp).toISOString();
+        }
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.valueOf())) {
+            return parsed.toISOString();
+        }
+    }
+    return undefined;
+}
+export function sabPriorityToNormalized(priority) {
+    const normalized = Number.parseInt(String(priority ?? UsenetPriority.default), 10);
+    switch (normalized) {
+        case -4: {
+            return UsenetPriority.stopped;
+        }
+        case -3: {
+            return UsenetPriority.duplicate;
+        }
+        case -2: {
+            return UsenetPriority.paused;
+        }
+        case -1: {
+            return UsenetPriority.low;
+        }
+        case 0: {
+            return UsenetPriority.normal;
+        }
+        case 1: {
+            return UsenetPriority.high;
+        }
+        case 2: {
+            return UsenetPriority.force;
+        }
+        case -100: {
+            return UsenetPriority.default;
+        }
+        default: {
+            return UsenetPriority.default;
+        }
+    }
+}
+export function normalizedPriorityToSab(priority) {
+    switch (priority) {
+        case UsenetPriority.stopped: {
+            return -4;
+        }
+        case UsenetPriority.duplicate: {
+            return -3;
+        }
+        case UsenetPriority.paused: {
+            return -2;
+        }
+        case UsenetPriority.veryLow: {
+            return -1;
+        }
+        case UsenetPriority.low: {
+            return -1;
+        }
+        case UsenetPriority.normal: {
+            return 0;
+        }
+        case UsenetPriority.high: {
+            return 1;
+        }
+        case UsenetPriority.veryHigh: {
+            return 1;
+        }
+        case UsenetPriority.force: {
+            return 2;
+        }
+        case UsenetPriority.default:
+        default: {
+            return -100;
+        }
+    }
+}
+function mapSabStatus(status, failMessage = '') {
+    switch (status) {
+        case 'Grabbing': {
+            return { state: UsenetJobState.grabbing, stateMessage: UsenetStateMessage.grabbing };
+        }
+        case 'Queued': {
+            return { state: UsenetJobState.queued, stateMessage: UsenetStateMessage.queued };
+        }
+        case 'Paused': {
+            return { state: UsenetJobState.paused, stateMessage: UsenetStateMessage.paused };
+        }
+        case 'Downloading': {
+            return {
+                state: UsenetJobState.downloading,
+                stateMessage: UsenetStateMessage.downloading,
+            };
+        }
+        case 'Fetching': {
+            return {
+                state: UsenetJobState.downloading,
+                stateMessage: UsenetStateMessage.downloading,
+            };
+        }
+        case 'Propagating': {
+            return {
+                state: UsenetJobState.downloading,
+                stateMessage: UsenetStateMessage.downloading,
+            };
+        }
+        case 'Checking':
+        case 'QuickCheck':
+        case 'Verifying':
+        case 'Repairing':
+        case 'Extracting':
+        case 'Moving':
+        case 'Running': {
+            return {
+                state: UsenetJobState.postProcessing,
+                stateMessage: UsenetStateMessage.postProcessing,
+            };
+        }
+        case 'Completed': {
+            return { state: UsenetJobState.completed, stateMessage: UsenetStateMessage.completed };
+        }
+        case 'Failed': {
+            return {
+                state: failMessage ? UsenetJobState.error : UsenetJobState.warning,
+                stateMessage: failMessage ? UsenetStateMessage.failed : UsenetStateMessage.warning,
+            };
+        }
+        case 'Deleted': {
+            return { state: UsenetJobState.deleted, stateMessage: UsenetStateMessage.deleted };
+        }
+        default: {
+            return { state: UsenetJobState.unknown, stateMessage: UsenetStateMessage.unknown };
+        }
+    }
+}
+export function normalizeSabJob(slot) {
+    const { state, stateMessage } = mapSabStatus(slot.status);
+    const totalSize = megabytesToBytes(slot.mb);
+    const remainingSize = megabytesToBytes(slot.mbleft);
+    const progress = toNumber(slot.percentage);
+    return {
+        id: slot.nzo_id,
+        name: slot.filename,
+        progress,
+        isCompleted: progress >= 100,
+        category: slot.cat || '',
+        priority: sabPriorityToNormalized(slot.priority),
+        state,
+        stateMessage,
+        downloadSpeed: 0,
+        eta: parseSabDuration(slot.timeleft),
+        queuePosition: slot.index,
+        totalSize,
+        remainingSize,
+        savePath: undefined,
+        postProcessScript: slot.script,
+        raw: slot,
+    };
+}
+export function normalizeSabHistoryItem(item) {
+    const { state, stateMessage } = mapSabStatus(item.status, item.fail_message);
+    const totalSize = toNumber(item.bytes);
+    const succeeded = state === UsenetJobState.completed;
+    return {
+        id: item.nzo_id,
+        name: item.name || item.nzb_name || item.nzo_id,
+        progress: succeeded ? 100 : 0,
+        isCompleted: succeeded,
+        category: item.category || '',
+        priority: undefined,
+        state,
+        stateMessage,
+        downloadSpeed: 0,
+        eta: 0,
+        queuePosition: -1,
+        totalSize,
+        remainingSize: 0,
+        savePath: item.storage,
+        dateCompleted: normalizeIsoDate(item.completed),
+        postProcessScript: item.script,
+        failureMessage: item.fail_message,
+        storagePath: item.storage,
+        succeeded,
+        raw: item,
+    };
+}
+export function normalizeSabStatus(queue, fullStatus) {
+    return {
+        isDownloadPaused: Boolean(queue.paused),
+        speedBytesPerSecond: Math.round(toNumber(queue.kbpersec) * 1024),
+        totalRemainingSize: megabytesToBytes(queue.mbleft),
+        completeDir: fullStatus.completedir,
+        raw: {
+            queue,
+            fullStatus,
+        },
+    };
+}