node-sabnzbd

Node API client for SABnzbd.

TL;DR

const SABnzbd = require('sabnzbd');
const sabnzbd = new SABnzbd('http://localhost:8080/', API_KEY);

console.log('Queue + History:');
sabnzbd.entries().each(function(entry) {
  console.log('-', entry.name, ',', entry.size / 1000 / 1000, 'MB');
});

Installation

$ npm install sabnzbd

You'll also need the API key for your SABnzbd installation:

• open the SABnzbd web interface in your browser
• go to Config > General
• in the SABnzbd Web Server settings, find the API key (or generate one)
• note down the API key

Client basics

This client consists of three parts:

• common commands
• commands related to the SABnzbd queue (the list of currently active downloads)
• commands related to the SABnzbd history (the list of completed downloads)

For the most part, the client implements the commands found on the SABnzbd API page, and returns their results pretty much as-is.

However, because the SABnzbd API is horribly inconsistent at times, I've added some normalization (see the status and entries commands) to make interfacing with it a bit easier. Another thing is that the SABnzbd API is not terribly informative on the status of some commands; for instance, the remove commands will always return a true status, even if you're using an nonexistent NZB id.

sabnzbd is Promise based, so all commands return a promise.

Commands

Common commands

new SABnzbd(URL, API_KEY)

• Connects to SABnzbd.

  Arguments:

  • URL
    • url to web interface of the SABnzbd
  • API_KEY
    • API key (required for most operations, see Install on how to get it)

  Returns:

  • a SABnzbd instance

instance.status()

• The results of queue.status() and history.status() (see below), merged (NB: for now, only the slots and entries are actually merged, the rest of the object returned is based on the object returned by the queue.status() method).

instance.entries()

• Both the history and queue entries, merged.

instance.delete(ID[, ID, ...])

• Delete an NZB from both queue and history.

  Arguments:

  • ID
    • id of NZB (the nzbid property of queue/history entries)

  Accepts multiple ID arguments, or one argument containing the string all to remove everything from both queue and history (so be careful!).

instance.version()

• Query the SABnzbd version.

  Returns:

  • the SABnzbd version as reported by the server

instance.cmd(CMD[, ARGS])

• Send a command to SABnzbd.

  Arguments:

  • CMD
    • command to send
  • ARGS
    • optional object of key/value parameters

  (for all commands and their arguments, check the the SABnzbd API page)

  For example, the version() method is implemented like this:

  return this.cmd('version');

Queue-related commands

instance.queue.status()

• Get status of the SABnzbd queue.

  Returns:

  • the output of the advanced queue command, with an extra property entries containing a normalized version of the slots property

  A normalized queue entry contains the following properties:

    age         : age of NZB posting, in seconds
    size        : size of download in bytes
    size_left   : number of bytes still to download before completion
    nzbid       : internal SABnzbd id for this NZB
    category    : categories
    eta         : ETA for download, as Date object
    name        : NZB filename
    nzbname     : NZB filename
    percentage  : percentage downloaded
    index       : index into queue
    missing     : ?
    priority    : ?
    status      : download status ('Completed', 'Paused', 'Queued,
                  'Failed', 'Verifying', 'Downloading', 'Extracting')
    time_left   : time left before download should be complete, in seconds
    _queue_slot : boolean (always true) to identify this as a queue entry

instance.queue.delete(ID)

• Delete an NZB from the queue. See instance.delete() for arguments.

instance.queue.addurl(URL[, ARGS)

• Add an NZB to the queue by URL, with optional arguments.

  Arguments:

  • URL
    • url pointing to an NZB file
  • ARGS Sab API Docs
    • Optional object any of the following options pp=Post Process Level, script=Post Process Script, cat=Category, priority=Priority

instance.queue.pause([ID])

• Pause downloading. Without arguments, pauses the entire queue. Otherwise, just pauses downloading of a single NZB.

  Arguments:

  • ID
    • id of NZB (the nzbid property of queue/history entries)

instance.queue.resume([ID])

• Resume downloading. Without arguments, resumes the entire queue. Otherwise, just resumes downloading of a single NZB.

  Arguments:

  • ID
    • id of NZB (the nzbid property of queue/history entries)

History-related commands

instance.history.status()

• Get status of the SABnzbd history.

  Returns:

  • the output of the history command, with, again, an extra entries property

  A normalized history entry contains the following properties:

    action_line    : ?
    size           : size in bytes
    category       : categories
    completed      : completed timestamp, as Date object
    completeness   : ?
    download_time  : download time in seconds
    downloaded     : number of downloaded bytes
    fail_message   : message why download failed
    id             : internal id (not the same as `nzbid`)
    loaded         : ?
    meta           : ?
    name           : name of download
    nzbname        : NZB filename
    nzbid          : internal SABnzbd id for this NZB
    incomplete_path: path where SABnzbd stored incomplete download
    postproc_time  : time in seconds it took to postprocess this NZB
    pp             : ?
    report         : ?
    retry          : ?
    script         : ?
    script_line    : ?
    script_log     : ?
    show_details   : ?
    stage_log      : list of actions taken by SABnzbd to download/process
                     this NZB
    status         : status (see queue entry)
    downloaded_to  : file/directory this NZB was downloaded to
    url            : ?
    url_info       : ?
    _history_slot  : boolean (always true) to identify this as a history entry

instance.history.delete(ID)

• Delete an NZB from the history. See instance.delete() for arguments.

Changelog

• 2.0.0
  • Complete rewrite, using native Promise's.
• 1.2.0
  • allow passing of parameters with addurl() (thanks to @OverFlow636)
• 1.0.0
  • dropped Q in favor of Bluebird, tightened up code
• 0.2.0
  • pretty much a rewrite of the API
• 0.1.1
  • removed some left-over debugging code
• 0.1.0
  • initial release

TODO

• README:
  • documentation formatting sucks
• Queue:
  • Add by upload/file path/newzbin ID
  • Scripts/actions/priority
  • Shutdown
  • Move
  • Change item name
• History:
  • Retry
• Configuration:
  • Everything