@jellyfin/sdk 0.12.0 → 1.0.0

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.openapi-generator-ignore

@@ -0,0 +1,2 @@
+# Disable documentation files
+docs/*

package/CHANGELOG.md

@@ -7,11 +7,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-09-11
+
+### Added
+
+* Added `getBackupApi` utility function ([#997](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/997)).
+* `getLibraryApi` now returns an augmented class with a `getDownloadUrl` method ([#967](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/967)).
+* The `Api` class now contains a `webSocket` field, of which `OutboundWebSocketMessageType`s can be subscribed to for handling WebSocket messages ([#966](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/968)).
+* Added support for sending `Accept-Language` header with requests by including `languages` in `DeviceInfo` ([#1076](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/1076)).
+* Added `compareVersions` and `getDisplayVersion` utility functions for comparing and formatting versions ([#1083](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/1083)).
+
+### Changed
+
+* Any usages of `AUTHORIZATION_HEADER` and `AUTHORIZATION_PARAMETER` constants must be updated to be imported from `/constants` ([#966](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/968)).
+* Update OpenAPI spec for Jellyfin 12.0 ([#1071](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/1071)).
+  Note that **A LOT** of the APIs were renamed or moved as part of this update.
+  Specific changes can be found in [#1072](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/1072).
+
+### Deprecated
+
+* `isVersionLess` is deprecated in favor of `compareVersions` ([#1083](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/1083)).
+
+## [0.13.0] - 2025-10-28
+
+### Changed
+
+* Ensure `Authorization` header is sent for all requests ([#948](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/948)).
+
+### Deprecated
+
+* Deprecate authentication helper methods in `Api` class ([#949](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/949)).
+  Updating the `accessToken` is now handled transparently in `getUserApi` and `getSessionApi`. If you need to handle
+  authentication manually, then you should manually create `UserApi` and `SessionApi` instances.
+
 ## [0.12.0] - 2025-10-21
 
 ### Security
 
-* Bumped axios peer dependency version ([#939](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/939)). Note that this axios vulnerability only affected applications running in node.js.
+* Bumped axios peer dependency version ([#939](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/939)).
+  Note that this axios vulnerability only affected applications running in node.js.
 
 ### Added
 
@@ -81,7 +115,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 * 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](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/149)).
+  While I do feel this is a slightly worse developer experience, it was a necessary change to support tree-shaking
+  ([#149](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/149)).
 * `BaseItemKind` is now included in the generated client.
   Imports will need updated ([#187](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/187)).
 
@@ -106,7 +141,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [0.1.0] - 2021-09-19
 
-[unreleased]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.12.0...HEAD
+[unreleased]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.13.0...v1.0.0
+[0.13.0]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/jellyfin/jellyfin-sdk-typescript/compare/v0.9.0...v0.10.0

package/README.md

@@ -17,8 +17,6 @@
 
 A TypeScript SDK for Jellyfin.
 
-> Warning: This project is under active development, so API changes may occur.
-
 ## Install
 
 ```sh
@@ -33,17 +31,15 @@ yarn add @jellyfin/sdk
 
 ### Supported Jellyfin Versions
 
-| SDK Version | Jellyfin Version |
-|:-:|:-:|
-| 0.12.0 | 10.11.x |
-| 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`.
+|  SDK Version  | Jellyfin Version |
+|:-------------:|:----------------:|
+|     1.0.0     |       12.x       |
+|    0.13.0     |     10.11.x      |
+|    0.12.0     |     10.11.x      |
+|    0.11.0     |     10.10.x      |
+|    0.10.0     |      10.9.x      |
+|     0.9.0     |      10.9.x      |
+| 0.8.2 - 0.7.0 | 10.8.1 - 10.8.13 |
 
 ### React Native
 
@@ -62,7 +58,8 @@ const jellyfin = new Jellyfin({
     },
     deviceInfo: {
         name: 'Device Name',
-        id: 'unique-device-id'
+        id: 'unique-device-id',
+        languages: ['en-US']
     }
 });
 
@@ -92,10 +89,8 @@ console.log('Info =>', info.data);
 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', '');
+// Login with a username and password.
+const auth = await getAuthenticationApi(this).authenticateUserByName({ authenticateUserByName: { Username: 'demo', Pw: '' } });
 console.log('Auth =>', auth.data);
 
 // Authentication state is stored internally in the Api class, so now
@@ -103,22 +98,50 @@ console.log('Auth =>', auth.data);
 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();
+// Logout the current user.
+await getSessionApi(api).reportSessionEnded();
 ```
 
-## Breaking Changes
+## Development
 
-[See the CHANGELOG](./CHANGELOG.md)
+If you want to build the SDK locally (for development, testing, or contributing), follow the steps below.
+
+### 1. Replace `openapi.json` file
+
+Obtain the correct `openapi.json` file from the Jellyfin server repository.
+
+- If working with merged changes, you can download it from the [Jellyfin API spec](https://api.jellyfin.org/openapi/jellyfin-openapi-unstable.json).
+- If working with unmerged branch changes, download the `openapi.json` artifact generated from that specific branch build.
+
+Once you have the correct file, replace the existing `openapi.json` in this repository with the new one.
+
+### 2. Build the project
+
+You can now build the project by executing the following commands
+
+```sh
+npm run fix-schema
+npm run build
+```
 
-## Roadmap to 1.0
+This should then generate a compiled output in the `lib` folder
 
-* [x] Use custom generator templates for API versions [#231](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/231) (Currently uses sed to update the value could be improved.)
-* [x] Automate OpenAPI spec updates using GitHub [#351](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/351)
-* [x] Create branch tracking unstable Jellyfin builds with automated builds [#354](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/354)
-* [x] Fix authentication header escaping [#564](https://github.com/jellyfin/jellyfin-sdk-typescript/pull/564)
-* [ ] Add WebSocket API support
-* [ ] Add example projects for different ecosystems [#186](https://github.com/jellyfin/jellyfin-sdk-typescript/issues/186)
-* [ ] Add utility function for `getFile` [#164](https://github.com/jellyfin/jellyfin-sdk-typescript/issues/164)
-* [ ] More complete device profile generation utilities
+### 3. Use the local build in another project
+
+You can reference your local build in another repository using `npm link`:
+
+```sh
+npm link
+```
+
+Then, in the consuming project:
+
+```sh
+npm link @jellyfin/sdk
+```
+
+This allows you to test changes to the SDK without publishing it to npm.
+
+## Significant Changes
+
+[See the CHANGELOG](./CHANGELOG.md)

package/eslint.config.mjs

@@ -0,0 +1,118 @@
+import eslint from '@eslint/js';
+import stylistic from '@stylistic/eslint-plugin';
+import vitest from '@vitest/eslint-plugin';
+import importPlugin from 'eslint-plugin-import';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+	// Global ignores
+	{
+		ignores: [
+			'dist/**',
+			'docs/**',
+			'src/generated-client/**',
+			'lib/**',
+			'node_modules/**'
+		]
+	},
+
+	// Base config for all files
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+
+	// Main source files config
+	{
+		files: ['**/*.ts', '**/*.mjs', '**/*.js'],
+		plugins: {
+			'@stylistic': stylistic,
+			'import': importPlugin
+		},
+		languageOptions: {
+			globals: {
+				...globals.node
+			}
+		},
+		settings: {
+			'import/resolver': {
+				typescript: true,
+				node: true
+			}
+		},
+		rules: {
+			'import/order': ['error', {
+				'alphabetize': { 'order': 'asc', 'caseInsensitive': true },
+				'newlines-between': 'always-and-inside-groups'
+			}],
+
+			'@stylistic/type-annotation-spacing': ['error'],
+
+			'@typescript-eslint/consistent-type-imports': ['error'],
+
+			'array-callback-return': ['error'],
+			'arrow-spacing': ['error'],
+			'block-spacing': ['error'],
+			'brace-style': ['error', '1tbs', { 'allowSingleLine': true }],
+			'comma-dangle': ['error', 'never'],
+			'comma-spacing': ['error'],
+			'curly': ['error', 'multi-line'],
+			'eol-last': ['error'],
+			'indent': ['error', 'tab', { 'SwitchCase': 1 }],
+			'jsx-quotes': ['error', 'prefer-single'],
+			'key-spacing': ['error'],
+			'keyword-spacing': ['error'],
+			'max-statements-per-line': ['error'],
+			'no-floating-decimal': ['error'],
+			'no-multi-spaces': ['error'],
+			'no-multiple-empty-lines': ['error', { 'max': 1 }],
+			'no-restricted-globals': ['error'],
+			'no-trailing-spaces': ['error'],
+			'no-unreachable': ['error'],
+			'no-unused-expressions': ['error', { 'allowShortCircuit': true, 'allowTernary': true, 'allowTaggedTemplates': true }],
+			'object-curly-spacing': ['error', 'always'],
+			'one-var': ['error', 'never'],
+			'padded-blocks': ['error', 'never'],
+			'prefer-const': ['error', { 'destructuring': 'all' }],
+			'quotes': ['error', 'single', { 'avoidEscape': true, 'allowTemplateLiterals': false }],
+			'semi': ['error'],
+			'no-var': ['error'],
+			'space-before-blocks': ['error'],
+			'space-before-function-paren': ['error', { 'anonymous': 'never', 'named': 'never', 'asyncArrow': 'always' }],
+			'space-infix-ops': 'error',
+			'yoda': 'error'
+		}
+	},
+
+	// Source files - browser environment
+	{
+		files: ['src/**/*.ts'],
+		languageOptions: {
+			globals: {
+				...globals.browser
+			}
+		}
+	},
+
+	// Test files config
+	{
+		files: ['**/*.test.ts'],
+		plugins: {
+			vitest
+		},
+		languageOptions: {
+			globals: {
+				...globals.node
+			}
+		},
+		rules: {
+			...vitest.configs.recommended.rules,
+			'vitest/consistent-test-it': ['error'],
+			'vitest/prefer-lowercase-title': ['error', { 'ignoreTopLevelDescribe': true }],
+			'vitest/require-top-level-describe': ['error'],
+			// Disable because we use custom `itIf` helper that the plugin doesn't recognize
+			'vitest/no-standalone-expect': 'off',
+			// Disable rules that require type information (would need parserOptions.project)
+			'vitest/valid-title': 'off'
+		}
+	}
+);

package/lib/api.d.ts

@@ -7,19 +7,24 @@ import type { AxiosInstance, AxiosResponse } from 'axios';
 import { Configuration } from './generated-client/configuration';
 import type { AuthenticationResult } from './generated-client/models/authentication-result';
 import type { ClientInfo, DeviceInfo } from './models';
-/** The authorization header field name. */
-export declare const AUTHORIZATION_HEADER = "Authorization";
+import type { OutboundWebSocketMessageType, SocketMessageHandler } from './websocket';
 /** Class representing the Jellyfin API. */
 export declare class Api {
-    basePath: string;
-    clientInfo: ClientInfo;
-    deviceInfo: DeviceInfo;
-    accessToken: string;
-    axiosInstance: AxiosInstance;
+    private _basePath;
+    private _clientInfo;
+    private _deviceInfo;
+    private _accessToken;
+    readonly axiosInstance: AxiosInstance;
+    private webSocket;
     constructor(basePath: string, clientInfo: ClientInfo, deviceInfo: DeviceInfo, accessToken?: string, axiosInstance?: AxiosInstance);
+    get accessToken(): string;
+    get basePath(): string;
+    get clientInfo(): ClientInfo;
+    get deviceInfo(): DeviceInfo;
     get configuration(): Configuration;
     /**
-     * Convenience method for authenticating a user by name and updating the internal state.
+     * Convenience method for authenticating a user by name.
+     * @deprecated Use `getAuthenticationApi().authenticateUserByName()` instead.
      * @param username The username.
      * @param password The user password if required.
      */
@@ -32,8 +37,27 @@ export declare class Api {
      */
     getUri(url: string, params?: object): string;
     /**
-     * Convenience method for logging out and updating the internal state.
+     * Convenience method for logging out.
+     * @deprecated Use `getSessionApi().reportSessionEnded()` instead.
      */
     logout(): Promise<AxiosResponse<never> | AxiosResponse<void>>;
+    /**
+     * Updates this {@link Api} instance with new data.
+     *
+     * If the access token is cleared, any existing WebSocket connection will be closed.
+     *
+     * If the base path or access token changes while a WebSocket connection is active,
+     * the connection will be reconnected with the new credentials.
+     *
+     * @param data The data to update.
+     */
+    update(data: Partial<{
+        basePath: string;
+        clientInfo: ClientInfo;
+        deviceInfo: DeviceInfo;
+        accessToken: string;
+    }>): void;
     get authorizationHeader(): string;
+    get acceptLanguageHeader(): string | undefined;
+    subscribe<T extends OutboundWebSocketMessageType>(messageTypes: T[], onMessage: SocketMessageHandler<T>): () => void;
 }

package/lib/api.js

@@ -1,42 +1,55 @@
 import globalAxios from 'axios';
+import { ACCEPT_LANGUAGE_HEADER, AUTHORIZATION_HEADER, AUTHORIZATION_PARAMETER } from './constants.js';
 import { Configuration } from './generated-client/configuration.js';
 import { getAuthorizationHeader } from './utils/authentication.js';
+import { getAuthenticationApi } from './utils/api/authentication-api.js';
 import { getSessionApi } from './utils/api/session-api.js';
-import { getUserApi } from './utils/api/user-api.js';
+import { WebSocketService } from './websocket/websocket-service.js';
+import { WEBSOCKET_URL_PATH } from './websocket/constants.js';
 
-/** The authorization header field name. */
-const AUTHORIZATION_HEADER = 'Authorization';
 /** Class representing the Jellyfin API. */
 class Api {
     constructor(basePath, clientInfo, deviceInfo, accessToken = '', axiosInstance = globalAxios) {
         // Remove trailing slash if present
-        this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
-        this.clientInfo = clientInfo;
-        this.deviceInfo = deviceInfo;
-        this.accessToken = accessToken;
+        this._basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+        this._clientInfo = clientInfo;
+        this._deviceInfo = deviceInfo;
+        this._accessToken = accessToken;
         this.axiosInstance = axiosInstance;
     }
+    get accessToken() {
+        return this._accessToken;
+    }
+    get basePath() {
+        return this._basePath;
+    }
+    get clientInfo() {
+        return this._clientInfo;
+    }
+    get deviceInfo() {
+        return this._deviceInfo;
+    }
     get configuration() {
         return new Configuration({
-            basePath: this.basePath,
-            apiKey: this.authorizationHeader
+            basePath: this._basePath,
+            baseOptions: {
+                headers: {
+                    [AUTHORIZATION_HEADER]: this.authorizationHeader,
+                    [ACCEPT_LANGUAGE_HEADER]: this.acceptLanguageHeader
+                }
+            }
         });
     }
     /**
-     * Convenience method for authenticating a user by name and updating the internal state.
+     * Convenience method for authenticating a user by name.
+     * @deprecated Use `getAuthenticationApi().authenticateUserByName()` instead.
      * @param username The username.
      * @param password The user password if required.
      */
     authenticateUserByName(username, password) {
-        return getUserApi(this).authenticateUserByName(
+        return getAuthenticationApi(this).authenticateUserByName(
         // The axios client does some strange wrapping of the param object
-        { authenticateUserByName: { Username: username, Pw: password } }, 
-        // The authorization header is required for the request to succeed
-        { headers: { [AUTHORIZATION_HEADER]: this.authorizationHeader } }).then(response => {
-            // Update the current token and configuration object
-            this.accessToken = response.data.AccessToken || '';
-            return response;
-        });
+        { authenticateUserByName: { Username: username, Pw: password } });
     }
     /**
      * Gets a full URI for a relative URL to the Jellyfin server for a given SDK Api instance.
@@ -46,23 +59,72 @@ class Api {
      */
     getUri(url, params) {
         return this.axiosInstance.getUri({
-            baseURL: this.basePath,
+            baseURL: this._basePath,
             url,
             params
         });
     }
     /**
-     * Convenience method for logging out and updating the internal state.
+     * Convenience method for logging out.
+     * @deprecated Use `getSessionApi().reportSessionEnded()` instead.
      */
     logout() {
-        return getSessionApi(this).reportSessionEnded().then(response => {
-            this.accessToken = '';
-            return response;
-        });
+        return getSessionApi(this).reportSessionEnded();
+    }
+    /**
+     * Updates this {@link Api} instance with new data.
+     *
+     * If the access token is cleared, any existing WebSocket connection will be closed.
+     *
+     * If the base path or access token changes while a WebSocket connection is active,
+     * the connection will be reconnected with the new credentials.
+     *
+     * @param data The data to update.
+     */
+    update(data) {
+        var _a, _b;
+        if (data.basePath) {
+            this._basePath = data.basePath;
+        }
+        if (data.clientInfo) {
+            this._clientInfo = data.clientInfo;
+        }
+        if (data.deviceInfo) {
+            this._deviceInfo = data.deviceInfo;
+        }
+        if (data.accessToken !== undefined) {
+            this._accessToken = data.accessToken;
+        }
+        if (data.basePath ||
+            (data.accessToken && data.accessToken !== '')) {
+            (_a = this.webSocket) === null || _a === void 0 ? void 0 : _a.updateUrl(this.getUri(WEBSOCKET_URL_PATH, {
+                [AUTHORIZATION_PARAMETER]: this.accessToken
+            }));
+        }
+        else if (data.accessToken === '') {
+            // Token was cleared, dispose of WebSocket
+            (_b = this.webSocket) === null || _b === void 0 ? void 0 : _b.disconnect();
+        }
     }
     get authorizationHeader() {
-        return getAuthorizationHeader(this.clientInfo, this.deviceInfo, this.accessToken);
+        return getAuthorizationHeader(this._clientInfo, this._deviceInfo, this._accessToken);
+    }
+    get acceptLanguageHeader() {
+        const languages = this._deviceInfo.languages;
+        return (languages === null || languages === void 0 ? void 0 : languages.length) ? languages.join(',') : undefined;
+    }
+    subscribe(messageTypes, onMessage) {
+        if (!this.webSocket) {
+            // Pass undefined when there is no access token so subscriptions are stored
+            // but no connection attempt is made until updateUrl() is called later.
+            this.webSocket = new WebSocketService(this.accessToken
+                ? this.getUri(WEBSOCKET_URL_PATH, {
+                    [AUTHORIZATION_PARAMETER]: this.accessToken
+                })
+                : undefined);
+        }
+        return this.webSocket.subscribe(messageTypes, onMessage);
     }
 }
 
-export { AUTHORIZATION_HEADER, Api };
+export { Api };

package/lib/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+/** The authorization header field name. */
+export declare const AUTHORIZATION_HEADER = "Authorization";
+/** The accept language header field name. */
+export declare const ACCEPT_LANGUAGE_HEADER = "Accept-Language";
+/** The authorization query parameter name. */
+export declare const AUTHORIZATION_PARAMETER = "ApiKey";

package/lib/constants.js

@@ -0,0 +1,13 @@
+/**
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+/** The authorization header field name. */
+const AUTHORIZATION_HEADER = 'Authorization';
+/** The accept language header field name. */
+const ACCEPT_LANGUAGE_HEADER = 'Accept-Language';
+/** The authorization query parameter name. */
+const AUTHORIZATION_PARAMETER = 'ApiKey';
+
+export { ACCEPT_LANGUAGE_HEADER, AUTHORIZATION_HEADER, AUTHORIZATION_PARAMETER };