Class Sabnzbd

constructor

• new Sabnzbd(options?: Partial<UsenetClientConfig>): Sabnzbd

  Parameters

  • options: Partial<UsenetClientConfig> = {}

  Returns Sabnzbd

config

state

addFile

• addFile(
      nzb: string | Uint8Array<ArrayBufferLike>,
      options?: SabAddOptions,
  ): Promise<SabAddResponse>

  Adds an NZB to the queue by file upload.

  Calls SABnzbd mode=addfile.

  Parameters

  • nzb: string | Uint8Array<ArrayBufferLike>

    NZB XML content as text or bytes.

  • options: SabAddOptions = {}

    Optional SAB add fields; defaults include category="*", script="Default", priority=-100, and postProcess=-1.

  Returns Promise<SabAddResponse>

  The raw SAB add response containing status and optional nzo_ids.

addNzbFile

• addNzbFile(
      nzb: string | Uint8Array<ArrayBufferLike>,
      options?: Partial<AddNzbOptions>,
  ): Promise<string>

  Parameters

  • nzb: string | Uint8Array<ArrayBufferLike>
  • options: Partial<AddNzbOptions> = {}

  Returns Promise<string>

addNzbUrl

• addNzbUrl(url: string, options?: Partial<AddNzbOptions>): Promise<string>

  Parameters

  • url: string
  • options: Partial<AddNzbOptions> = {}

  Returns Promise<string>

addUrl

• addUrl(url: string, options?: SabAddOptions): Promise<SabAddResponse>

  Adds an NZB to the queue from a URL.

  Calls SABnzbd mode=addurl.

  Parameters

  • url: string

    Remote NZB URL.

  • options: SabAddOptions = {}

    Optional SAB add fields; defaults include category="*", script="Default", priority=-100, and postProcess=-1.

  Returns Promise<SabAddResponse>

  The raw SAB add response containing status and optional nzo_ids.

auth

• auth(): Promise<SabAuthResponse>

  Verifies configured credentials against the SABnzbd API.

  Calls SABnzbd mode=auth.

  Returns Promise<SabAuthResponse>

  The raw SABnzbd authentication response.

cancelPostProcessing

• cancelPostProcessing(id: string): Promise<boolean>

  Cancels post-processing of a job.

  Calls SABnzbd mode=cancel_pp.

  Parameters

  • id: string

    SAB job identifier (nzo_id) currently in post-processing.

  Returns Promise<boolean>

  true when SABnzbd cancels post-processing.

changeCategory

• changeCategory(id: string, category: string): Promise<boolean>

  Changes a queue job category.

  Calls SABnzbd mode=change_cat.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • category: string

    SAB category name.

  Returns Promise<boolean>

  true when SABnzbd accepts the category change.

changePostProcess

• changePostProcess(id: string, postProcess: UsenetPostProcess): Promise<boolean>

  Changes queue job post-processing options.

  Calls SABnzbd mode=change_opts. SAB only accepts explicit modes here, so UsenetPostProcess.default throws instead of being sent; there is no API to reset a job back to its category default.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • postProcess: UsenetPostProcess

    Normalized post-processing mode to apply.

  Returns Promise<boolean>

  true when SABnzbd accepts the option change.

  See

  https://github.com/sabnzbd/sabnzbd/blob/develop/sabnzbd/api.py (_api_change_opts)

changePriority

• changePriority(
      id: string,
      priority: UsenetPriority,
  ): Promise<number | undefined>

  Changes queue job priority.

  Calls SABnzbd mode=queue with name=priority.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • priority: UsenetPriority

    Shared normalized priority value.

  Returns Promise<number | undefined>

  The new queue position when reported by SABnzbd, otherwise undefined.

changeScript

• changeScript(id: string, script: string): Promise<boolean>

  Changes a queue job post-processing script.

  Calls SABnzbd mode=change_script.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • script: string

    SAB configured script name.

  Returns Promise<boolean>

  true when SABnzbd accepts the script change.

clearWarnings

• clearWarnings(): Promise<boolean>

  Clears currently active warnings.

  Calls SABnzbd mode=warnings with name=clear.

  Returns Promise<boolean>

  true when SABnzbd accepts the warning clear command.

deleteHistory

• deleteHistory(
      id: string,
      deleteFiles?: boolean,
      archive?: boolean,
  ): Promise<boolean>

  Deletes a history job by its SAB nzo_id.

  Calls SABnzbd mode=history with name=delete. SAB archives the job by default instead of deleting it permanently, and del_files only removes the incomplete download folder of failed jobs.

  Parameters

  • id: string

    SAB history job identifier (nzo_id).

  • deleteFiles: boolean = false

    When true, also remove leftover files of failed jobs; defaults to false.

  • Optionalarchive: boolean

    When false, permanently delete instead of archiving; defaults to SAB's setting.

  Returns Promise<boolean>

  true when SABnzbd accepts the delete command.

  See

  https://github.com/sabnzbd/sabnzbd/blob/develop/sabnzbd/api.py (_api_history_delete)

deleteJob

• deleteJob(id: string, deleteFiles?: boolean): Promise<boolean>

  Deletes a queue job by its SAB nzo_id.

  Calls SABnzbd mode=queue with name=delete.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • deleteFiles: boolean = false

    When true, also remove downloaded data files; defaults to false.

  Returns Promise<boolean>

  true when SABnzbd accepts the delete command.

exportState

• exportState(): Jsonify<SabnzbdState>

  Export the current state of the client. Can be restored with createFromState.

  Returns Jsonify<SabnzbdState>

fetchRss

• fetchRss(): Promise<boolean>

  Triggers immediate RSS processing.

  Calls SABnzbd mode=rss_now.

  Returns Promise<boolean>

  true when SABnzbd accepts the RSS trigger command.

findJob

• findJob(id: string): Promise<FoundUsenetJob | null>

  Parameters

  • id: string

  Returns Promise<FoundUsenetJob | null>

getAllData

• getAllData(): Promise<AllClientData>

  Returns queue, history, categories, scripts, and status in normalized form.

  Returns Promise<AllClientData>

getCategories

• getCategories(): Promise<Category[]>

  Retrieves configured SABnzbd categories.

  Calls SABnzbd mode=get_cats.

  Returns Promise<Category[]>

  Categories normalized to shared Category objects.

getFiles

• getFiles(id: string): Promise<SabFilesResponse>

  Lists files for a queue job.

  Calls SABnzbd mode=get_files.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  Returns Promise<SabFilesResponse>

  The raw file listing payload.

getFullStatus

• getFullStatus(): Promise<SabFullStatus>

  Loads full server and queue status details from SABnzbd.

  Calls SABnzbd mode=fullstatus with skip_dashboard=1.

  Returns Promise<SabFullStatus>

  The full status payload.

getHistory

• getHistory(): Promise<NormalizedUsenetHistoryItem[]>

  Returns Promise<NormalizedUsenetHistoryItem[]>

getHistoryJob

• getHistoryJob(id: string): Promise<NormalizedUsenetHistoryItem>

  Parameters

  • id: string

  Returns Promise<NormalizedUsenetHistoryItem>

getQueue

• getQueue(): Promise<NormalizedUsenetJob[]>

  Returns Promise<NormalizedUsenetJob[]>

getQueueJob

• getQueueJob(id: string): Promise<NormalizedUsenetJob>

  Parameters

  • id: string

  Returns Promise<NormalizedUsenetJob>

getScripts

• getScripts(): Promise<Script[]>

  Retrieves configured SABnzbd post-processing scripts.

  Calls SABnzbd mode=get_scripts.

  Returns Promise<Script[]>

  Scripts normalized to shared Script objects.

getServerStats

• getServerStats(): Promise<SabServerStats>

  Retrieves per-server traffic totals from SABnzbd.

  Calls SABnzbd mode=server_stats.

  Returns Promise<SabServerStats>

  Aggregate and per-server transfer statistics.

getVersion

• getVersion(): Promise<string>

  Reads the SABnzbd version string.

  Calls SABnzbd mode=version.

  Returns Promise<string>

  The SABnzbd version.

getWarnings

• getWarnings(): Promise<SabWarning[]>

  Retrieves the current SABnzbd warning list.

  Calls SABnzbd mode=warnings.

  Returns Promise<SabWarning[]>

  All active warnings.

listHistory

• listHistory(
      query?: Omit<SabHistoryQuery, "lastHistoryUpdate">,
  ): Promise<SabHistory>

  Lists history entries, optionally filtered and paged.

  Calls SABnzbd mode=history.

  Parameters

  • Optionalquery: Omit<SabHistoryQuery, "lastHistoryUpdate">

    Optional history filters, pagination, and archive controls.

  Returns Promise<SabHistory>

  The raw history payload including slots, or false when lastHistoryUpdate matches SAB's current last_history_update and nothing changed.

• listHistory(query: SabHistoryQuery): Promise<false | SabHistory>

  Lists history entries, optionally filtered and paged.

  Calls SABnzbd mode=history.

  Parameters

  • query: SabHistoryQuery

    Optional history filters, pagination, and archive controls.

  Returns Promise<false | SabHistory>

  The raw history payload including slots, or false when lastHistoryUpdate matches SAB's current last_history_update and nothing changed.

listQueue

• listQueue(query?: SabQueueQuery): Promise<SabQueue>

  Lists queue entries, optionally filtered and paged.

  Calls SABnzbd mode=queue.

  Parameters

  • query: SabQueueQuery = {}

    Optional queue filters and pagination controls.

  Returns Promise<SabQueue>

  The raw queue payload including slots.

moveJob

• moveJob(id: string, position: number): Promise<boolean>

  Moves a queue job to a target position.

  Calls SABnzbd mode=switch.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • position: number

    Target zero-based queue position.

  Returns Promise<boolean>

  true when SABnzbd accepts the move command.

normalizedAddNzb

• normalizedAddNzb(
      input: NzbInput,
      options?: Partial<AddNzbOptions>,
  ): Promise<NormalizedUsenetJob>

  Parameters

  • input: NzbInput
  • options: Partial<AddNzbOptions> = {}

  Returns Promise<NormalizedUsenetJob>

pauseJob

• pauseJob(id: string): Promise<boolean>

  Pauses a queue job by its SAB nzo_id.

  Calls SABnzbd mode=queue with name=pause.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  Returns Promise<boolean>

  true when SABnzbd accepts the job pause command.

pausePostProcessing

• pausePostProcessing(): Promise<boolean>

  Pauses post-processing tasks.

  Calls SABnzbd mode=pause_pp.

  Returns Promise<boolean>

  true when SABnzbd accepts the post-processing pause command.

pauseQueue

• pauseQueue(): Promise<boolean>

  Pauses the global download queue.

  Calls SABnzbd mode=pause.

  Returns Promise<boolean>

  true when SABnzbd accepts the pause command.

pauseQueueFor

• pauseQueueFor(minutes: number): Promise<boolean>

  Pauses the queue and resumes it automatically after minutes.

  Calls SABnzbd mode=config with name=set_pause.

  Parameters

  • minutes: number

    Minutes to pause for.

  Returns Promise<boolean>

  true when SABnzbd accepts the timed pause.

purgeQueue

• purgeQueue(search?: string): Promise<string[]>

  Removes all queue jobs, optionally only those whose name contains search. Downloaded files are deleted too.

  Calls SABnzbd mode=queue with name=purge.

  Parameters

  • Optionalsearch: string

    Optional case-insensitive name filter.

  Returns Promise<string[]>

  The removed queue ids.

removeJob

• removeJob(id: string, removeData?: boolean): Promise<boolean>

  Removes a job from the queue, falling back to history when the id is not queued.

  Parameters

  • id: string
  • removeData: boolean = false

  Returns Promise<boolean>

renameJob

• renameJob(id: string, name: string, password?: string): Promise<boolean>

  Renames a queue job and optionally sets an archive password.

  Calls SABnzbd mode=queue with name=rename.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  • name: string

    New queue job name.

  • Optionalpassword: string

    Optional archive password; left unchanged when omitted.

  Returns Promise<boolean>

  true when SABnzbd accepts the rename command.

resetQuota

• resetQuota(): Promise<boolean>

  Resets SABnzbd quota counters.

  Calls SABnzbd mode=reset_quota.

  Returns Promise<boolean>

  true when SABnzbd accepts the quota reset command.

restart

• restart(): Promise<boolean>

  Requests a standard SABnzbd restart.

  Calls SABnzbd mode=restart.

  Returns Promise<boolean>

  true when SABnzbd accepts the restart command.

restartRepair

• restartRepair(): Promise<boolean>

  Requests SABnzbd restart with queue repair.

  Calls SABnzbd mode=restart_repair.

  Returns Promise<boolean>

  true when SABnzbd accepts the repair restart command.

resumeJob

• resumeJob(id: string): Promise<boolean>

  Resumes a queue job by its SAB nzo_id.

  Calls SABnzbd mode=queue with name=resume.

  Parameters

  • id: string

    SAB queue job identifier (nzo_id).

  Returns Promise<boolean>

  true when SABnzbd accepts the job resume command.

resumePostProcessing

• resumePostProcessing(): Promise<boolean>

  Resumes post-processing tasks.

  Calls SABnzbd mode=resume_pp.

  Returns Promise<boolean>

  true when SABnzbd accepts the post-processing resume command.

resumeQueue

• resumeQueue(): Promise<boolean>

  Resumes the global download queue.

  Calls SABnzbd mode=resume.

  Returns Promise<boolean>

  true when SABnzbd accepts the resume command.

retryAll

• retryAll(): Promise<string[]>

  Re-queues every retryable failed history job.

  Calls SABnzbd mode=retry_all.

  Returns Promise<string[]>

  The new queue ids.

retryJob

• retryJob(id: string, password?: string): Promise<string>

  Re-queues a failed history job.

  Calls SABnzbd mode=retry.

  Parameters

  • id: string

    SAB history job identifier (nzo_id).

  • Optionalpassword: string

    Optional archive password for the retried job.

  Returns Promise<string>

  The new queue id. SAB removes the history entry.

scanWatchedFolder

• scanWatchedFolder(): Promise<boolean>

  Triggers an immediate scan of the watched folder.

  Calls SABnzbd mode=watched_now.

  Returns Promise<boolean>

  true when SABnzbd accepts the watched-folder scan command.

setCategory

• setCategory(id: string, category: string): Promise<boolean>

  Parameters

  • id: string
  • category: string

  Returns Promise<boolean>

setPriority

• setPriority(id: string, priority: UsenetPriority): Promise<boolean>

  Parameters

  • id: string
  • priority: UsenetPriority

  Returns Promise<boolean>

setSpeedLimit

• setSpeedLimit(limit: string | number): Promise<boolean>

  Sets the global download speed limit.

  Calls SABnzbd mode=config with name=speedlimit.

  Parameters

  • limit: string | number

    Speed limit value passed directly to SABnzbd.

  Returns Promise<boolean>

  true when SABnzbd accepts the speed limit update.

shutdown

• shutdown(): Promise<boolean>

  Requests SABnzbd shutdown.

  Calls SABnzbd mode=shutdown.

  Returns Promise<boolean>

  true when SABnzbd accepts the shutdown command.

sortQueue

• sortQueue(
      sort: SabQueueSortField,
      direction?: SabSortDirection,
  ): Promise<boolean>

  Sorts the queue. SAB keeps priority ordering, sorting only within each priority.

  Calls SABnzbd mode=queue with name=sort.

  Parameters

  • sort: SabQueueSortField

    Field to sort by.

  • direction: SabSortDirection = 'asc'

    Sort direction; defaults to ascending.

  Returns Promise<boolean>

  true when SABnzbd accepts the sort command.

StaticcreateFromState

• createFromState(
      config: Readonly<UsenetClientConfig>,
      state: Readonly<Jsonify<SabnzbdState>>,
  ): Sabnzbd

  Parameters

  • config: Readonly<UsenetClientConfig>
  • state: Readonly<Jsonify<SabnzbdState>>

  Returns Sabnzbd