NZBGet

TypeScript api wrapper for NZBGet using JSON-RPC

Overview

Includes the normalized usenet API shared with @ctrl/sabnzbd:

• getAllData()
• getQueue()
• getHistory()
• getQueueJob(id)
• getHistoryJob(id)
• findJob(id)
• addNzbFile(...) / addNzbUrl(...)
• 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 NZBGet methods only when you need JSON-RPC specific behavior such as raw config access, raw editQueue commands, or direct append usage.

Install

npm install @ctrl/nzbget

Use

import { Nzbget } from '@ctrl/nzbget';

const client = new Nzbget({
  baseUrl: 'http://localhost:6789/',
  username: 'nzbget',
  password: 'tegbzn6789',
});

async function main() {
  const data = await client.getAllData();
  console.log(data.queue);
}

Normalized Example

import { Nzbget, UsenetNotFoundError, UsenetPriority } from '@ctrl/nzbget';

const client = new Nzbget({
  baseUrl: 'http://localhost:6789/',
  username: 'nzbget',
  password: 'tegbzn6789',
});

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://nzbget.ep.workers.dev
NZBGet API Docs: https://nzbget.net/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

NZBGet-specific methods are still available when you need the raw JSON-RPC surface.

Connection and discovery:

• getVersion() - wraps version
• status() - wraps status
• listGroups() - wraps listgroups
• history(hidden?) - wraps history
• getConfig() - wraps config
• configTemplates(loadFromDisk?) - wraps configtemplates
• listFiles(id) - wraps listfiles
• getCategories() - derived from config
• getScripts() - derived from configtemplates

Queue and rate control:

• pauseDownload() - wraps pausedownload
• resumeDownload() - wraps resumedownload
• setRate(limitBytesPerSecond) - wraps rate
• append(name, contentOrUrl, options?) - wraps append
• editQueue(command, parameter, ids) - wraps editqueue

State Export

const state = client.exportState();
const restored = Nzbget.createFromState(config, state);

Local Testing

Start a disposable NZBGet container on localhost:6789 with the same credentials used by the client defaults:

docker run -d --name nzbget-local-test \
  -p 6789:6789 \
  -e NZBGET_USER=nzbget \
  -e NZBGET_PASS=tegbzn6789 \
  lscr.io/linuxserver/nzbget:latest

Run the full local test suite against that container:

TEST_NZBGET_URL=http://127.0.0.1:6789 TEST_NZBGET_USERNAME=nzbget TEST_NZBGET_PASSWORD=tegbzn6789 pnpm test

If you only want the container-backed integration spec:

TEST_NZBGET_URL=http://127.0.0.1:6789 TEST_NZBGET_USERNAME=nzbget TEST_NZBGET_PASSWORD=tegbzn6789 pnpm test test/integration.spec.ts

Remove the disposable container when you are done:

docker rm -f nzbget-local-test