@ctrl/sabnzbd 0.0.1

package/dist/src/sabnzbd.d.ts

@@ -0,0 +1,328 @@
+import { type AddNzbOptions as NormalizedAddNzbOptions, type AllClientData, type Category, type FoundUsenetJob, type NormalizedUsenetHistoryItem, type NormalizedUsenetJob, type NzbInput, type Script, type UsenetClient, type UsenetClientConfig, type UsenetClientState, UsenetPriority } from '@ctrl/shared-usenet';
+import type { Jsonify } from 'type-fest';
+import type { SabAddOptions, SabAddResponse, SabAuthResponse, SabFilesResponse, SabFullStatus, SabHistory, SabHistoryQuery, SabQueue, SabQueueQuery, SabServerStats, SabWarning } from './types.js';
+interface SabnzbdState extends UsenetClientState {
+    auth?: {
+        apiKey?: string;
+        nzbKey?: string;
+    };
+    version?: {
+        version: string;
+    };
+}
+export declare class Sabnzbd implements UsenetClient {
+    static createFromState(config: Readonly<UsenetClientConfig>, state: Readonly<Jsonify<SabnzbdState>>): Sabnzbd;
+    config: UsenetClientConfig;
+    state: SabnzbdState;
+    constructor(options?: Partial<UsenetClientConfig>);
+    exportState(): Jsonify<SabnzbdState>;
+    /**
+     * Verifies configured credentials against the SABnzbd API.
+     *
+     * Calls SABnzbd `mode=auth`.
+     *
+     * @returns The raw SABnzbd authentication response.
+     */
+    auth(): Promise<SabAuthResponse>;
+    /**
+     * Reads the SABnzbd version string.
+     *
+     * Calls SABnzbd `mode=version`.
+     *
+     * @returns The SABnzbd version.
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Loads full server and queue status details from SABnzbd.
+     *
+     * Calls SABnzbd `mode=fullstatus` with `skip_dashboard=1`.
+     *
+     * @returns The full status payload.
+     */
+    getFullStatus(): Promise<SabFullStatus>;
+    /**
+     * Retrieves the current SABnzbd warning list.
+     *
+     * Calls SABnzbd `mode=warnings`.
+     *
+     * @returns All active warnings.
+     */
+    getWarnings(): Promise<SabWarning[]>;
+    /**
+     * Retrieves per-server traffic totals from SABnzbd.
+     *
+     * Calls SABnzbd `mode=server_stats`.
+     *
+     * @returns Aggregate and per-server transfer statistics.
+     */
+    getServerStats(): Promise<SabServerStats>;
+    /**
+     * 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`.
+     */
+    listQueue(query?: SabQueueQuery): Promise<SabQueue>;
+    /**
+     * 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`.
+     */
+    listHistory(query?: SabHistoryQuery): Promise<SabHistory>;
+    /**
+     * Retrieves configured SABnzbd categories.
+     *
+     * Calls SABnzbd `mode=get_cats`.
+     *
+     * @returns Categories normalized to shared `Category` objects.
+     */
+    getCategories(): Promise<Category[]>;
+    /**
+     * Retrieves configured SABnzbd post-processing scripts.
+     *
+     * Calls SABnzbd `mode=get_scripts`.
+     *
+     * @returns Scripts normalized to shared `Script` objects.
+     */
+    getScripts(): Promise<Script[]>;
+    /**
+     * Pauses the global download queue.
+     *
+     * Calls SABnzbd `mode=pause`.
+     *
+     * @returns `true` when SABnzbd accepts the pause command.
+     */
+    pauseQueue(): Promise<boolean>;
+    /**
+     * Resumes the global download queue.
+     *
+     * Calls SABnzbd `mode=resume`.
+     *
+     * @returns `true` when SABnzbd accepts the resume command.
+     */
+    resumeQueue(): Promise<boolean>;
+    /**
+     * Requests SABnzbd shutdown.
+     *
+     * Calls SABnzbd `mode=shutdown`.
+     *
+     * @returns `true` when SABnzbd accepts the shutdown command.
+     */
+    shutdown(): Promise<boolean>;
+    /**
+     * Requests a standard SABnzbd restart.
+     *
+     * Calls SABnzbd `mode=restart`.
+     *
+     * @returns `true` when SABnzbd accepts the restart command.
+     */
+    restart(): Promise<boolean>;
+    /**
+     * Requests SABnzbd restart with queue repair.
+     *
+     * Calls SABnzbd `mode=restart_repair`.
+     *
+     * @returns `true` when SABnzbd accepts the repair restart command.
+     */
+    restartRepair(): Promise<boolean>;
+    /**
+     * Pauses post-processing tasks.
+     *
+     * Calls SABnzbd `mode=pause_pp`.
+     *
+     * @returns `true` when SABnzbd accepts the post-processing pause command.
+     */
+    pausePostProcessing(): Promise<boolean>;
+    /**
+     * Resumes post-processing tasks.
+     *
+     * Calls SABnzbd `mode=resume_pp`.
+     *
+     * @returns `true` when SABnzbd accepts the post-processing resume command.
+     */
+    resumePostProcessing(): Promise<boolean>;
+    /**
+     * Triggers immediate RSS processing.
+     *
+     * Calls SABnzbd `mode=rss_now`.
+     *
+     * @returns `true` when SABnzbd accepts the RSS trigger command.
+     */
+    fetchRss(): Promise<boolean>;
+    /**
+     * Triggers an immediate scan of the watched folder.
+     *
+     * Calls SABnzbd `mode=watched_now`.
+     *
+     * @returns `true` when SABnzbd accepts the watched-folder scan command.
+     */
+    scanWatchedFolder(): Promise<boolean>;
+    /**
+     * Resets SABnzbd quota counters.
+     *
+     * Calls SABnzbd `mode=reset_quota`.
+     *
+     * @returns `true` when SABnzbd accepts the quota reset command.
+     */
+    resetQuota(): Promise<boolean>;
+    /**
+     * Clears currently active warnings.
+     *
+     * Calls SABnzbd `mode=warnings` with `name=clear`.
+     *
+     * @returns `true` when SABnzbd accepts the warning clear command.
+     */
+    clearWarnings(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    pauseJob(id: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    resumeJob(id: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    deleteJob(id: string, deleteFiles?: boolean): Promise<boolean>;
+    /**
+     * 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.
+     */
+    moveJob(id: string, position: number): Promise<boolean>;
+    /**
+     * 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.
+     */
+    changeCategory(id: string, category: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    changeScript(id: string, script: string): Promise<boolean>;
+    /**
+     * 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`.
+     */
+    changePriority(id: string, priority: UsenetPriority): Promise<number | undefined>;
+    /**
+     * 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.
+     */
+    changePostProcess(id: string, postProcess: NormalizedAddNzbOptions['postProcess']): Promise<boolean>;
+    /**
+     * 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.
+     */
+    renameJob(id: string, name: string, password?: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getFiles(id: string): Promise<SabFilesResponse>;
+    /**
+     * 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.
+     */
+    setSpeedLimit(limit: string | number): Promise<boolean>;
+    /**
+     * 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`.
+     */
+    addUrl(url: string, options?: SabAddOptions): Promise<SabAddResponse>;
+    /**
+     * 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`.
+     */
+    addFile(nzb: string | Uint8Array, options?: SabAddOptions): Promise<SabAddResponse>;
+    getQueue(): Promise<NormalizedUsenetJob[]>;
+    getHistory(): Promise<NormalizedUsenetHistoryItem[]>;
+    getQueueJob(id: string): Promise<NormalizedUsenetJob>;
+    getHistoryJob(id: string): Promise<NormalizedUsenetHistoryItem>;
+    findJob(id: string): Promise<FoundUsenetJob | null>;
+    getAllData(): Promise<AllClientData>;
+    removeJob(id: string, removeData?: boolean): Promise<boolean>;
+    setCategory(id: string, category: string): Promise<boolean>;
+    setPriority(id: string, priority: UsenetPriority): Promise<boolean>;
+    addNzbFile(nzb: string | Uint8Array, options?: Partial<NormalizedAddNzbOptions>): Promise<string>;
+    addNzbUrl(url: string, options?: Partial<NormalizedAddNzbOptions>): Promise<string>;
+    normalizedAddNzb(input: NzbInput, options?: Partial<NormalizedAddNzbOptions>): Promise<NormalizedUsenetJob>;
+    private waitForQueueJob;
+    private normalizeAddOptions;
+    private request;
+    private getAuthQuery;
+    private assertSabResponse;
+}
+export {};