TypeScript SDK for Jellyfin
Go to file
Bill Thornton 2e06c867db
Some checks are pending
Code quality / Lint (push) Waiting to run
Code quality / TypeScript Build (push) Waiting to run
CodeQL / Analyze (typescript) (push) Waiting to run
SDK Documentation Publish / Build Documentation (push) Waiting to run
SDK Documentation Publish / Deploy to GitHub Pages (push) Blocked by required conditions
SDK Unstable Branch / update (push) Waiting to run
Test / Test (push) Waiting to run
Merge pull request #845 from 3flex/linters-minus-eslint-vitest
2024-12-04 00:45:57 -05:00
.github Update github/codeql-action action to v3.27.6 2024-12-03 14:06:38 +00:00
.vscode Update VS Code config 2024-06-03 10:23:28 -04:00
openapi-templates Add MPL license header to generated client 2022-08-22 15:13:30 -04:00
scripts Fix modify-schema crash on null allOf value 2024-09-23 16:11:53 -04:00
src Remove ItemSortBy enum 2024-12-03 20:28:23 +11:00
.eslintignore Move eslint config to cjs file 2023-03-15 09:55:12 -04:00
.eslintrc.cjs Remove vitest globals per best practice 2024-03-17 03:28:35 -04:00
.gitattributes Initial commit 2021-08-29 01:00:52 -04:00
.gitignore Add api models to docs 2022-09-15 13:36:48 -04:00
.npmignore Add v8 for coverage 2024-03-17 03:27:38 -04:00
.npmrc Disable npm version creating a git tag 2023-03-30 12:53:54 -04:00
codecov.yml Add codecov configuration 2021-09-20 15:58:00 -04:00
LICENSE Update license 2021-09-14 01:10:15 -04:00
openapi.json Update generated sources to 10.10.3 2024-11-19 04:08:27 +00:00
openapitools.json Update openapi generator version 2024-08-06 11:39:13 -04:00
package-lock.json Merge pull request #845 from 3flex/linters-minus-eslint-vitest 2024-12-04 00:45:57 -05:00
package.json Merge pull request #845 from 3flex/linters-minus-eslint-vitest 2024-12-04 00:45:57 -05:00
README.md Prepare for v0.11.0 release 2024-10-28 16:37:55 -04:00
rollup.config.js Drop compare-versions dependency 2023-04-27 14:52:32 +02:00
sonar-project.properties Revert "Use default coverage report location" 2023-10-11 12:16:14 -04:00
tsconfig.json Update build target to es2018 2024-06-03 10:33:11 -04:00
vitest.config.ts Fix missing lcov test reporter 2024-03-19 02:13:06 -04:00

jellyfin-sdk-typescript

Part of the Jellyfin Project


Logo Banner

MPL-2.0 license Current Release npm Sonar Coverage

A TypeScript SDK for Jellyfin.

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

Install

npm i --save @jellyfin/sdk

or

yarn add @jellyfin/sdk

Supported Jellyfin Versions

SDK Version Jellyfin Version
0.11.0 10.10.x
0.10.0 10.9.x
0.9.0 10.9.x
0.8.2 - 0.6.0 10.8.1 - 10.8.13
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.

React Native

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.11.0

  • Updated OpenAPI spec for Jellyfin 10.10.0. #816

v0.10.0

  • Updated build target to ES2018. #712

v0.9.0

  • Updated OpenAPI spec for Jellyfin 10.9.1. #694

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 #564
  • Add WebSocket API support
  • Add example projects for different ecosystems #186
  • Add utility function for getFile #164
  • More complete device profile generation utilities