@ctrl/sabnzbd 0.0.1

package/dist/src/sabnzbd.js

@@ -0,0 +1,774 @@
+import { UsenetNotFoundError, UsenetPostProcess, UsenetPriority, } from '@ctrl/shared-usenet';
+import { FormData } from 'node-fetch-native';
+import { ofetch } from 'ofetch';
+import { joinURL } from 'ufo';
+import { normalizeSabHistoryItem, normalizeSabJob, normalizeSabStatus, normalizedPriorityToSab, } from './normalizeUsenetData.js';
+const defaults = {
+    baseUrl: 'http://localhost:8080/',
+    path: '/api',
+    username: '',
+    password: '',
+    timeout: 5000,
+};
+const addQueuePollAttempts = 40;
+const addQueuePollIntervalMs = 250;
+function toQueryStringValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    return `${value}`;
+}
+function toCommaList(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return Array.isArray(value) ? value.join(',') : `${value}`;
+}
+function normalizePostProcess(value) {
+    switch (value) {
+        case undefined:
+        case UsenetPostProcess.default: {
+            return -1;
+        }
+        case UsenetPostProcess.none: {
+            return 0;
+        }
+        case UsenetPostProcess.repair: {
+            return 1;
+        }
+        case UsenetPostProcess.repairUnpack: {
+            return 2;
+        }
+        case UsenetPostProcess.repairUnpackDelete: {
+            return 3;
+        }
+        default: {
+            if (!Number.isInteger(value)) {
+                throw new TypeError(`SAB post-process value must be an integer, received: ${value}`);
+            }
+            if (value < -1 || value > 3) {
+                throw new RangeError(`Unsupported SAB post-process value: ${value}`);
+            }
+            return value;
+        }
+    }
+}
+function encodeNzbFile(file) {
+    if (typeof file === 'string') {
+        return new TextEncoder().encode(file);
+    }
+    return file;
+}
+async function sleep(milliseconds) {
+    await new Promise(resolve => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+function getAddedJobId(response) {
+    const [id] = response.nzo_ids;
+    if (!response.status || !id) {
+        throw new Error(response.error ?? 'SABnzbd did not return a queue id');
+    }
+    return id;
+}
+function coercePriority(priority) {
+    if (priority === undefined) {
+        return UsenetPriority.default;
+    }
+    if (typeof priority !== 'number') {
+        return priority;
+    }
+    if (!Number.isInteger(priority)) {
+        throw new TypeError(`SAB priority must be an integer, received: ${priority}`);
+    }
+    switch (priority) {
+        case -100: {
+            return UsenetPriority.default;
+        }
+        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;
+        }
+        default: {
+            throw new RangeError(`Unsupported SAB priority value: ${priority}`);
+        }
+    }
+}
+function isUsenetNotFoundError(error) {
+    return error instanceof UsenetNotFoundError;
+}
+export class Sabnzbd {
+    static createFromState(config, state) {
+        const client = new Sabnzbd(config);
+        client.state = { ...state };
+        return client;
+    }
+    config;
+    state = {};
+    constructor(options = {}) {
+        this.config = { ...defaults, ...options };
+    }
+    exportState() {
+        return JSON.parse(JSON.stringify(this.state));
+    }
+    /**
+     * Verifies configured credentials against the SABnzbd API.
+     *
+     * Calls SABnzbd `mode=auth`.
+     *
+     * @returns The raw SABnzbd authentication response.
+     */
+    async auth() {
+        const response = await this.request({ mode: 'auth' });
+        this.state.auth = {
+            apiKey: this.config.apiKey,
+            nzbKey: this.config.nzbKey,
+        };
+        return response;
+    }
+    /**
+     * Reads the SABnzbd version string.
+     *
+     * Calls SABnzbd `mode=version`.
+     *
+     * @returns The SABnzbd version.
+     */
+    async getVersion() {
+        const response = await this.request({ mode: 'version' });
+        this.state.version = { version: response.version };
+        return response.version;
+    }
+    /**
+     * Loads full server and queue status details from SABnzbd.
+     *
+     * Calls SABnzbd `mode=fullstatus` with `skip_dashboard=1`.
+     *
+     * @returns The full status payload.
+     */
+    async getFullStatus() {
+        return this.request({ mode: 'fullstatus', skip_dashboard: '1' });
+    }
+    /**
+     * Retrieves the current SABnzbd warning list.
+     *
+     * Calls SABnzbd `mode=warnings`.
+     *
+     * @returns All active warnings.
+     */
+    async getWarnings() {
+        const response = await this.request({ mode: 'warnings' });
+        return response.warnings;
+    }
+    /**
+     * Retrieves per-server traffic totals from SABnzbd.
+     *
+     * Calls SABnzbd `mode=server_stats`.
+     *
+     * @returns Aggregate and per-server transfer statistics.
+     */
+    async getServerStats() {
+        return this.request({ mode: 'server_stats' });
+    }
+    /**
+     * Lists queue entries, optionally filtered and paged.
+     *
+     * Calls SABnzbd `mode=queue`.
+     *
+     * @param query Optional queue filters and pagination controls.
+     * @returns The raw queue payload including `slots`.
+     */
+    async listQueue(query = {}) {
+        const response = await this.request({
+            mode: 'queue',
+            start: toQueryStringValue(query.start),
+            limit: toQueryStringValue(query.limit),
+            search: query.search,
+            category: toCommaList(query.category),
+            priority: toCommaList(query.priority),
+            status: toCommaList(query.status),
+            nzo_ids: toCommaList(query.nzoIds),
+        });
+        return response.queue;
+    }
+    /**
+     * Lists history entries, optionally filtered and paged.
+     *
+     * Calls SABnzbd `mode=history`.
+     *
+     * @param query Optional history filters, pagination, and archive controls.
+     * @returns The raw history payload including `slots`.
+     */
+    async listHistory(query = {}) {
+        const response = await this.request({
+            mode: 'history',
+            start: toQueryStringValue(query.start),
+            limit: toQueryStringValue(query.limit),
+            search: query.search,
+            category: toCommaList(query.category),
+            status: toCommaList(query.status),
+            nzo_ids: toCommaList(query.nzoIds),
+            failed_only: toQueryStringValue(query.failedOnly),
+            archive: toQueryStringValue(query.archived),
+            last_history_update: toQueryStringValue(query.lastHistoryUpdate),
+        });
+        return response.history;
+    }
+    /**
+     * Retrieves configured SABnzbd categories.
+     *
+     * Calls SABnzbd `mode=get_cats`.
+     *
+     * @returns Categories normalized to shared `Category` objects.
+     */
+    async getCategories() {
+        const response = await this.request({ mode: 'get_cats' });
+        return response.categories.map(category => ({
+            id: category,
+            name: category,
+        }));
+    }
+    /**
+     * Retrieves configured SABnzbd post-processing scripts.
+     *
+     * Calls SABnzbd `mode=get_scripts`.
+     *
+     * @returns Scripts normalized to shared `Script` objects.
+     */
+    async getScripts() {
+        const response = await this.request({ mode: 'get_scripts' });
+        return response.scripts.map(script => ({
+            id: script,
+            name: script,
+        }));
+    }
+    /**
+     * Pauses the global download queue.
+     *
+     * Calls SABnzbd `mode=pause`.
+     *
+     * @returns `true` when SABnzbd accepts the pause command.
+     */
+    async pauseQueue() {
+        await this.request({ mode: 'pause' });
+        return true;
+    }
+    /**
+     * Resumes the global download queue.
+     *
+     * Calls SABnzbd `mode=resume`.
+     *
+     * @returns `true` when SABnzbd accepts the resume command.
+     */
+    async resumeQueue() {
+        await this.request({ mode: 'resume' });
+        return true;
+    }
+    /**
+     * Requests SABnzbd shutdown.
+     *
+     * Calls SABnzbd `mode=shutdown`.
+     *
+     * @returns `true` when SABnzbd accepts the shutdown command.
+     */
+    async shutdown() {
+        await this.request({ mode: 'shutdown' });
+        return true;
+    }
+    /**
+     * Requests a standard SABnzbd restart.
+     *
+     * Calls SABnzbd `mode=restart`.
+     *
+     * @returns `true` when SABnzbd accepts the restart command.
+     */
+    async restart() {
+        await this.request({ mode: 'restart' });
+        return true;
+    }
+    /**
+     * Requests SABnzbd restart with queue repair.
+     *
+     * Calls SABnzbd `mode=restart_repair`.
+     *
+     * @returns `true` when SABnzbd accepts the repair restart command.
+     */
+    async restartRepair() {
+        await this.request({ mode: 'restart_repair' });
+        return true;
+    }
+    /**
+     * Pauses post-processing tasks.
+     *
+     * Calls SABnzbd `mode=pause_pp`.
+     *
+     * @returns `true` when SABnzbd accepts the post-processing pause command.
+     */
+    async pausePostProcessing() {
+        await this.request({ mode: 'pause_pp' });
+        return true;
+    }
+    /**
+     * Resumes post-processing tasks.
+     *
+     * Calls SABnzbd `mode=resume_pp`.
+     *
+     * @returns `true` when SABnzbd accepts the post-processing resume command.
+     */
+    async resumePostProcessing() {
+        await this.request({ mode: 'resume_pp' });
+        return true;
+    }
+    /**
+     * Triggers immediate RSS processing.
+     *
+     * Calls SABnzbd `mode=rss_now`.
+     *
+     * @returns `true` when SABnzbd accepts the RSS trigger command.
+     */
+    async fetchRss() {
+        await this.request({ mode: 'rss_now' });
+        return true;
+    }
+    /**
+     * Triggers an immediate scan of the watched folder.
+     *
+     * Calls SABnzbd `mode=watched_now`.
+     *
+     * @returns `true` when SABnzbd accepts the watched-folder scan command.
+     */
+    async scanWatchedFolder() {
+        await this.request({ mode: 'watched_now' });
+        return true;
+    }
+    /**
+     * Resets SABnzbd quota counters.
+     *
+     * Calls SABnzbd `mode=reset_quota`.
+     *
+     * @returns `true` when SABnzbd accepts the quota reset command.
+     */
+    async resetQuota() {
+        await this.request({ mode: 'reset_quota' });
+        return true;
+    }
+    /**
+     * Clears currently active warnings.
+     *
+     * Calls SABnzbd `mode=warnings` with `name=clear`.
+     *
+     * @returns `true` when SABnzbd accepts the warning clear command.
+     */
+    async clearWarnings() {
+        await this.request({ mode: 'warnings', name: 'clear' });
+        return true;
+    }
+    /**
+     * Pauses a queue job by its SAB `nzo_id`.
+     *
+     * Calls SABnzbd `mode=queue` with `name=pause`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @returns `true` when SABnzbd accepts the job pause command.
+     */
+    async pauseJob(id) {
+        await this.request({ mode: 'queue', name: 'pause', value: id });
+        return true;
+    }
+    /**
+     * Resumes a queue job by its SAB `nzo_id`.
+     *
+     * Calls SABnzbd `mode=queue` with `name=resume`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @returns `true` when SABnzbd accepts the job resume command.
+     */
+    async resumeJob(id) {
+        await this.request({ mode: 'queue', name: 'resume', value: id });
+        return true;
+    }
+    /**
+     * Deletes a queue job by its SAB `nzo_id`.
+     *
+     * Calls SABnzbd `mode=queue` with `name=delete`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param deleteFiles When `true`, also remove downloaded data files; defaults to `false`.
+     * @returns `true` when SABnzbd accepts the delete command.
+     */
+    async deleteJob(id, deleteFiles = false) {
+        await this.request({
+            mode: 'queue',
+            name: 'delete',
+            value: id,
+            del_files: deleteFiles ? '1' : '0',
+        });
+        return true;
+    }
+    /**
+     * Moves a queue job to a target position.
+     *
+     * Calls SABnzbd `mode=switch`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param position Target zero-based queue position.
+     * @returns `true` when SABnzbd accepts the move command.
+     */
+    async moveJob(id, position) {
+        await this.request({
+            mode: 'switch',
+            value: id,
+            value2: `${position}`,
+        });
+        return true;
+    }
+    /**
+     * Changes a queue job category.
+     *
+     * Calls SABnzbd `mode=change_cat`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param category SAB category name.
+     * @returns `true` when SABnzbd accepts the category change.
+     */
+    async changeCategory(id, category) {
+        await this.request({
+            mode: 'change_cat',
+            value: id,
+            value2: category,
+        });
+        return true;
+    }
+    /**
+     * Changes a queue job post-processing script.
+     *
+     * Calls SABnzbd `mode=change_script`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param script SAB configured script name.
+     * @returns `true` when SABnzbd accepts the script change.
+     */
+    async changeScript(id, script) {
+        await this.request({
+            mode: 'change_script',
+            value: id,
+            value2: script,
+        });
+        return true;
+    }
+    /**
+     * Changes queue job priority.
+     *
+     * Calls SABnzbd `mode=queue` with `name=priority`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param priority Shared normalized priority value.
+     * @returns The new queue position when reported by SABnzbd, otherwise `undefined`.
+     */
+    async changePriority(id, priority) {
+        const response = await this.request({
+            mode: 'queue',
+            name: 'priority',
+            value: id,
+            value2: `${normalizedPriorityToSab(priority)}`,
+        });
+        return response.position;
+    }
+    /**
+     * Changes queue job post-processing options.
+     *
+     * Calls SABnzbd `mode=change_opts`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param postProcess Normalized post-processing mode to apply.
+     * @returns `true` when SABnzbd accepts the option change.
+     */
+    async changePostProcess(id, postProcess) {
+        await this.request({
+            mode: 'change_opts',
+            value: id,
+            value2: `${normalizePostProcess(postProcess)}`,
+        });
+        return true;
+    }
+    /**
+     * Renames a queue job and optionally sets an archive password.
+     *
+     * Calls SABnzbd `mode=rename`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @param name New queue job name.
+     * @param password Optional archive password; defaults to an empty string.
+     * @returns `true` when SABnzbd accepts the rename command.
+     */
+    async renameJob(id, name, password = '') {
+        await this.request({
+            mode: 'rename',
+            value: id,
+            value2: name,
+            password,
+        });
+        return true;
+    }
+    /**
+     * Lists files for a queue job.
+     *
+     * Calls SABnzbd `mode=get_files`.
+     *
+     * @param id SAB queue job identifier (`nzo_id`).
+     * @returns The raw file listing payload.
+     */
+    async getFiles(id) {
+        return this.request({ mode: 'get_files', value: id });
+    }
+    /**
+     * Sets the global download speed limit.
+     *
+     * Calls SABnzbd `mode=config` with `name=speedlimit`.
+     *
+     * @param limit Speed limit value passed directly to SABnzbd.
+     * @returns `true` when SABnzbd accepts the speed limit update.
+     */
+    async setSpeedLimit(limit) {
+        await this.request({
+            mode: 'config',
+            name: 'speedlimit',
+            value: `${limit}`,
+        });
+        return true;
+    }
+    /**
+     * Adds an NZB to the queue from a URL.
+     *
+     * Calls SABnzbd `mode=addurl`.
+     *
+     * @param url Remote NZB URL.
+     * @param options Optional SAB add fields; defaults include `category="*"`, `script="Default"`,
+     * `priority=-100`, and `postProcess=-1`.
+     * @returns The raw SAB add response containing status and optional `nzo_ids`.
+     */
+    async addUrl(url, options = {}) {
+        const response = await this.request({
+            mode: 'addurl',
+            name: url,
+            nzbname: options.name ?? '',
+            password: options.password ?? '',
+            cat: options.category ?? '*',
+            script: options.script ?? 'Default',
+            priority: `${options.priority ?? -100}`,
+            pp: `${options.postProcess ?? -1}`,
+        });
+        return response;
+    }
+    /**
+     * Adds an NZB to the queue by file upload.
+     *
+     * Calls SABnzbd `mode=addfile`.
+     *
+     * @param nzb NZB XML content as text or bytes.
+     * @param options Optional SAB add fields; defaults include `category="*"`, `script="Default"`,
+     * `priority=-100`, and `postProcess=-1`.
+     * @returns The raw SAB add response containing status and optional `nzo_ids`.
+     */
+    async addFile(nzb, options = {}) {
+        const form = new FormData();
+        form.append('mode', 'addfile');
+        form.append('output', 'json');
+        form.append('nzbname', options.name ?? '');
+        form.append('password', options.password ?? '');
+        form.append('cat', options.category ?? '*');
+        form.append('script', options.script ?? 'Default');
+        form.append('priority', `${options.priority ?? -100}`);
+        form.append('pp', `${options.postProcess ?? -1}`);
+        if (this.config.apiKey) {
+            form.append('apikey', this.config.apiKey);
+        }
+        else if (this.config.nzbKey) {
+            form.append('nzbkey', this.config.nzbKey);
+        }
+        else {
+            form.append('ma_username', this.config.username ?? '');
+            form.append('ma_password', this.config.password ?? '');
+        }
+        const filename = options.name?.endsWith('.nzb')
+            ? options.name
+            : `${options.name ?? 'upload'}.nzb`;
+        form.append('name', new Blob([Buffer.from(encodeNzbFile(nzb))], { type: 'application/x-nzb+xml' }), filename);
+        return this.request({}, { method: 'POST', body: form });
+    }
+    async getQueue() {
+        const queue = await this.listQueue();
+        return queue.slots.map(normalizeSabJob);
+    }
+    async getHistory() {
+        const history = await this.listHistory();
+        return history.slots.map(normalizeSabHistoryItem);
+    }
+    async getQueueJob(id) {
+        const queue = await this.listQueue({ nzoIds: id });
+        const job = queue.slots.find(slot => slot.nzo_id === id);
+        if (!job) {
+            throw new UsenetNotFoundError('sabnzbd', 'queueJob', id);
+        }
+        return normalizeSabJob(job);
+    }
+    async getHistoryJob(id) {
+        const history = await this.listHistory({ nzoIds: id });
+        const historyItem = history.slots.find(item => item.nzo_id === id);
+        if (!historyItem) {
+            throw new UsenetNotFoundError('sabnzbd', 'historyJob', id);
+        }
+        return normalizeSabHistoryItem(historyItem);
+    }
+    async findJob(id) {
+        const queue = await this.listQueue({ nzoIds: id });
+        const queueJob = queue.slots.find(slot => slot.nzo_id === id);
+        if (queueJob) {
+            return {
+                source: 'queue',
+                job: normalizeSabJob(queueJob),
+            };
+        }
+        const history = await this.listHistory({ nzoIds: id });
+        const historyJob = history.slots.find(item => item.nzo_id === id);
+        if (historyJob) {
+            return {
+                source: 'history',
+                job: normalizeSabHistoryItem(historyJob),
+            };
+        }
+        return null;
+    }
+    async getAllData() {
+        const [queue, history, fullStatus, categories, scripts] = await Promise.all([
+            this.listQueue(),
+            this.listHistory(),
+            this.getFullStatus(),
+            this.getCategories(),
+            this.getScripts(),
+        ]);
+        return {
+            categories,
+            scripts,
+            queue: queue.slots.map(normalizeSabJob),
+            history: history.slots.map(normalizeSabHistoryItem),
+            status: normalizeSabStatus(queue, fullStatus),
+            raw: {
+                queue,
+                history,
+                fullStatus,
+            },
+        };
+    }
+    async removeJob(id, removeData = false) {
+        return this.deleteJob(id, removeData);
+    }
+    async setCategory(id, category) {
+        return this.changeCategory(id, category);
+    }
+    async setPriority(id, priority) {
+        await this.changePriority(id, priority);
+        return true;
+    }
+    async addNzbFile(nzb, options = {}) {
+        const response = await this.addFile(nzb, this.normalizeAddOptions(options));
+        return getAddedJobId(response);
+    }
+    async addNzbUrl(url, options = {}) {
+        const response = await this.addUrl(url, this.normalizeAddOptions(options));
+        return getAddedJobId(response);
+    }
+    async normalizedAddNzb(input, options = {}) {
+        const id = 'url' in input
+            ? await this.addNzbUrl(input.url, options)
+            : await this.addNzbFile(input.file, options);
+        return this.waitForQueueJob(id);
+    }
+    async waitForQueueJob(id) {
+        for (let attempt = 0; attempt < addQueuePollAttempts; attempt++) {
+            try {
+                return await this.getQueueJob(id);
+            }
+            catch (error) {
+                if (!isUsenetNotFoundError(error)) {
+                    throw error;
+                }
+            }
+            if (attempt < addQueuePollAttempts - 1) {
+                await sleep(addQueuePollIntervalMs);
+            }
+        }
+        throw new UsenetNotFoundError('sabnzbd', 'queueJob', id);
+    }
+    normalizeAddOptions(options) {
+        return {
+            category: options.category ?? '*',
+            script: options.postProcessScript ?? 'Default',
+            priority: normalizedPriorityToSab(options.startPaused ? UsenetPriority.paused : coercePriority(options.priority)),
+            postProcess: normalizePostProcess(options.postProcess),
+            name: options.name,
+            password: options.password,
+        };
+    }
+    async request(params, options = {}) {
+        const url = joinURL(this.config.baseUrl, this.config.path ?? '/api');
+        const query = options.method === 'POST'
+            ? undefined
+            : {
+                output: 'json',
+                ...this.getAuthQuery(),
+                ...params,
+            };
+        const response = await ofetch(url, {
+            method: options.method ?? 'GET',
+            body: options.body,
+            query,
+            dispatcher: this.config.dispatcher,
+            timeout: this.config.timeout,
+        });
+        this.assertSabResponse(response);
+        return response;
+    }
+    getAuthQuery() {
+        if (this.config.apiKey) {
+            return { apikey: this.config.apiKey };
+        }
+        if (this.config.nzbKey) {
+            return { nzbkey: this.config.nzbKey };
+        }
+        return {
+            ma_username: this.config.username ?? '',
+            ma_password: this.config.password ?? '',
+        };
+    }
+    assertSabResponse(response) {
+        if (!response || typeof response !== 'object') {
+            return;
+        }
+        if ('status' in response && response.status === false) {
+            const error = 'error' in response && typeof response.error === 'string'
+                ? response.error
+                : 'SABnzbd returned status=false';
+            throw new Error(error);
+        }
+    }
+}