@jellyfin/sdk

jellyfin-sdk-typescript

Part of the Jellyfin Project

A TypeScript SDK for Jellyfin.

Warning: This project is under active development, so API changes may occur.

Install

npm i --save @jellyfin/sdk

yarn add @jellyfin/sdk

Supported Jellyfin Versions

SDK Version	Jellyfin Version
0.8.2 - 0.6.0	10.8.1 - 10.8.9
0.5.0	10.8.0
<0.5.0	10.7.x

Note: Versions prior to 0.7.0 were published as @thornbill/jellyfin-sdk.

The generated Axios client used in this library depends on URL and URLSearchParams to be available on the global scope. React Native only includes incomplete implementations for these classes, so a polyfill is required. React Native URL Polyfill seems like a good solution for this.

Usage

// Create a new instance of the SDK
const jellyfin = new Jellyfin({
    clientInfo: {
        name: 'My Client Application',
        version: '1.0.0'
    },
    deviceInfo: {
        name: 'Device Name',
        id: 'unique-device-id'
    }
});

// Find a valid server by trying to connect using common protocols and ports.
// Each server receives a score based on security, speed, and other criteria.
const servers = await jellyfin.discovery.getRecommendedServerCandidates('demo.jellyfin.org/stable');
// A utility function for finding the best result is available.
// If there is no "best" server, an error message should be displayed.
const best = jellyfin.discovery.findBestServer(servers);

// Create an API instance
const api = jellyfin.createApi(best.address);

// Each API endpoint is represented by a class in the generated client.
// Helper utility functions are provided under `/lib/utils/api/` to create an
// instance of a specific Jellyfin API using the shared Configuration and Axios
// instance from the `api` object created above.

// For example, the SystemApi can be generated using the `getSystemApi`
// function in `/lib/utils/api/system-api`.

// Fetch the public system info
const info = await getSystemApi(api).getPublicSystemInfo();
console.log('Info =>', info.data);

// Fetch the list of public users
const users = await getUserApi(api).getPublicUsers();
console.log('Users =>', users.data);

// A helper method for authentication has been added to the SDK because
// the default method exposed in the generated Axios client is rather
// cumbersome to use.
const auth = await api.authenticateUserByName('demo', '');
console.log('Auth =>', auth.data);

// Authentication state is stored internally in the Api class, so now
// requests that require authentication can be made normally
const libraries = await getLibraryApi(api).getMediaFolders();
console.log('Libraries =>', libraries.data);

// A helper method for logging out the current user has been added to the
// SDK so the internal state is updated correctly.
await api.logout();

Breaking Changes

v0.8.0

The library is now fully targeted to ES6/ES2015. #341
Axios received a major version upgrade. #300

v0.7.0

Renamed package to @jellyfin/sdk. #262

v0.6.0

Updated OpenAPI spec for Jellyfin 10.8.1. #208

v0.5.0

Build directory is now lib instead of dist. Any imports used that were previously in dist will need updated. #147
Duplicated exports were removed. Any imports may need updated if you referenced one of the duplicates. #148
API classes are no longer exposed via getters. Instead you need to call a function passing the Api instance as a parameter. For example: getSystemApi(api). While I do feel this is a slightly worse developer experience, it was a necessary change to support tree-shaking. #149
BaseItemKind is now included in the generated client. Imports will need updated. #187

Roadmap to 1.0

Use custom generator templates for API versions #231 (Currently uses sed to update the value could be improved.)
Automate OpenAPI spec updates using GitHub #351
Create branch tracking unstable Jellyfin builds with automated builds #354
Fix authentication header escaping
Add WebSocket API support
Add example projects for different ecosystems #186
Add utility function for getFile #164
More complete device profile generation utilities