arr-sdk

Unified TypeScript SDK for Sonarr, Radarr, Lidarr, Readarr, and Prowlarr APIs.

Features

- Full TypeScript support with types generated from official OpenAPI specs
- Native fetch API (no dependencies)
- Subpath exports for tree-shaking
- Async pagination helpers
- Comprehensive error handling
- Request/response hooks

Installation

``bash
npm install arr-sdk
`

Quick Start

$3

`typescript
import { SonarrClient } from 'arr-sdk/sonarr'

const sonarr = new SonarrClient({
baseUrl: 'http://localhost:8989',
apiKey: 'your-api-key'
})

// Get all series
const series = await sonarr.series.getAll()

// Search for a series
const results = await sonarr.series.lookup('Breaking Bad')

// Add a series
const newSeries = await sonarr.series.create({
tvdbId: 81189,
title: 'Breaking Bad',
qualityProfileId: 1,
rootFolderPath: '/tv'
})
`

$3

`typescript
import { RadarrClient } from 'arr-sdk/radarr'

const radarr = new RadarrClient({
baseUrl: 'http://localhost:7878',
apiKey: 'your-api-key'
})

// Get all movies
const movies = await radarr.movie.getAll()

// Search for a movie
const results = await radarr.movie.lookup('The Matrix')

// Add a movie
const newMovie = await radarr.movie.create({
tmdbId: 603,
title: 'The Matrix',
qualityProfileId: 1,
rootFolderPath: '/movies'
})
`

$3

`typescript
import { LidarrClient } from 'arr-sdk/lidarr'

const lidarr = new LidarrClient({
baseUrl: 'http://localhost:8686',
apiKey: 'your-api-key'
})

// Get all artists
const artists = await lidarr.artist.getAll()

// Search for an artist
const results = await lidarr.artist.lookup('The Beatles')

// Add an artist
const newArtist = await lidarr.artist.create({
foreignArtistId: 'b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d',
artistName: 'The Beatles',
qualityProfileId: 1,
metadataProfileId: 1,
rootFolderPath: '/music'
})

// Get all albums
const albums = await lidarr.album.getAll()

// Get tracks for an album
const tracks = await lidarr.track.getByAlbumId(1)
`

$3

`typescript
import { ReadarrClient } from 'arr-sdk/readarr'

const readarr = new ReadarrClient({
baseUrl: 'http://localhost:8787',
apiKey: 'your-api-key'
})

// Get all authors
const authors = await readarr.author.getAll()

// Search for an author
const results = await readarr.author.lookup('Stephen King')

// Add an author
const newAuthor = await readarr.author.create({
foreignAuthorId: '12345-67890-abcdef',
authorName: 'Stephen King',
qualityProfileId: 1,
metadataProfileId: 1,
rootFolderPath: '/books'
})

// Get all books
const books = await readarr.book.getAll()

// Get books by author
const authorBooks = await readarr.book.getByAuthorId(1)
`

$3

`typescript
import { ProwlarrClient } from 'arr-sdk/prowlarr'

const prowlarr = new ProwlarrClient({
baseUrl: 'http://localhost:9696',
apiKey: 'your-api-key'
})

// Get all indexers
const indexers = await prowlarr.indexer.getAll()

// Search across indexers
const results = await prowlarr.search.query({
query: 'ubuntu',
type: 'search'
})
`

Configuration

`typescript
import { SonarrClient } from 'arr-sdk/sonarr'

const client = new SonarrClient({
baseUrl: 'http://localhost:8989',
apiKey: 'your-api-key',

// Optional: custom timeout (default: 30000ms)
timeout: 60000,

// Optional: custom headers
headers: {
'X-Custom-Header': 'value'
},

// Optional: request/response hooks
onRequest: (config) => {
console.log('Request:', config.method, config.url.href)
},
onResponse: (response) => {
console.log('Response:', response.status)
},
onError: (error) => {
console.error('Error:', error.message)
}
})
`

Pagination

For endpoints that return paginated results:

`typescript
// Async generator for memory-efficient iteration
for await (const item of client.queue.getAll()) {
console.log(item)
}

// Or get all results at once
const allItems = await client.queue.getAllArray()
`

Error Handling

`typescript
import {
ArrError,
NotFoundError,
UnauthorizedError,
ValidationError
} from 'arr-sdk'

try {
await client.series.getById(99999)
} catch (error) {
if (error instanceof NotFoundError) {
console.log('Series not found')
} else if (error instanceof UnauthorizedError) {
console.log('Invalid API key')
} else if (error instanceof ValidationError) {
console.log('Validation errors:', error.errors)
} else if (error instanceof ArrError) {
console.log('API error:', error.statusCode, error.message)
}
}
`

Breaking Changes

See CHANGELOG.md for a complete list of breaking changes.

$3

The quality field in GetQueueOptions changed from number to number[]:

`typescript
// Before (v0.1.x)
await client.queue.get({ quality: 1 })

// After (v0.2.0+)
await client.queue.get({ quality: [1] })
`

Available Resources

$3

- series - Series management
- episode - Episode management
- episodeFile - Episode file management
- calendar - Calendar/upcoming episodes (includes iCal feed)
- queue - Download queue
- wanted - Missing and cutoff unmet episodes
- history - Activity history
- command - Commands (refresh, scan, manualImport, etc.)
- qualityProfile - Quality profiles
- qualityDefinition - Quality definitions
- rootFolder - Root folders
- tag - Tags
- indexer - Indexer configuration
- downloadClient - Download client configuration
- importList - Import lists
- notification - Notifications
- metadata - Metadata providers
- release - Release search/grab
- blocklist - Blocklisted releases
- system - System info, health, logs, ping
- filesystem - Browse filesystem paths
- mediaCover - Download series cover images
- config - Host/UI/naming configuration

$3

- movie - Movie management
- collection - Collection management
- calendar - Calendar/upcoming releases (includes iCal feed)
- queue - Download queue
- wanted - Missing and cutoff unmet movies
- history - Activity history
- command - Commands (refresh, scan, manualImport, etc.)
- qualityProfile - Quality profiles
- qualityDefinition - Quality definitions
- customFormat - Custom formats
- rootFolder - Root folders
- tag - Tags
- indexer - Indexer configuration
- downloadClient - Download client configuration
- importList - Import lists
- notification - Notifications
- metadata - Metadata providers
- release - Release search/grab
- blocklist - Blocklisted releases
- system - System info, health, logs, ping
- filesystem - Browse filesystem paths
- mediaCover - Download movie cover images
- config - Host/UI/naming configuration

$3

- artist - Artist management
- album - Album management
- track - Track management
- trackFile - Track file management
- calendar - Calendar/upcoming releases
- queue - Download queue
- wanted - Missing albums and cutoff unmet
- history - Activity history
- command - Commands (refresh, scan, etc.)
- qualityProfile - Quality profiles
- qualityDefinition - Quality definitions
- metadataProfile - Metadata profiles (Lidarr-specific)
- rootFolder - Root folders
- tag - Tags
- system - System info, health, logs, ping

$3

- author - Author management
- book - Book management
- edition - Edition access (different book versions)
- bookFile - Book file management
- calendar - Calendar/upcoming releases
- queue - Download queue
- wanted - Missing books and cutoff unmet
- history - Activity history
- command - Commands (refresh, scan, etc.)
- qualityProfile - Quality profiles
- qualityDefinition - Quality definitions
- metadataProfile - Metadata profiles
- rootFolder - Root folders
- tag - Tags
- system - System info, health, logs, ping

$3

- indexer - Indexer management
- indexerStats - Indexer statistics with filtering
- indexerProxy - Indexer proxies
- application - Application connections
- appProfile - App sync profiles
- search - Search across indexers
- newznab - Newznab/Torznab protocol (caps, search, download)
- command - Commands
- history - Search history
- tag - Tags
- downloadClient - Download clients
- notification - Notifications
- system - System info, health, logs, ping
- filesystem - Browse filesystem paths
- localization - Localization strings
- config - Configuration

Tree-Shaking

Import only what you need:

`typescript
// Import only Sonarr (smaller bundle)
import { SonarrClient } from 'arr-sdk/sonarr'

// Import only Radarr
import { RadarrClient } from 'arr-sdk/radarr'

// Import only Lidarr
import { LidarrClient } from 'arr-sdk/lidarr'

// Import only Readarr
import { ReadarrClient } from 'arr-sdk/readarr'

// Import only Prowlarr
import { ProwlarrClient } from 'arr-sdk/prowlarr'

// Or import everything
import { SonarrClient, RadarrClient, LidarrClient, ReadarrClient, ProwlarrClient } from 'arr-sdk'
`

Requirements

- Node.js >= 18.0.0 (uses native fetch`)

License

MIT