@jellyfin/sdk 0.12.0 → 1.0.0

package/lib/websocket/websocket-service.js

@@ -0,0 +1,296 @@
+import { buildWebSocketUrl } from '../utils/url/index.js';
+import { SUBSCRIPTION_REGISTRY, RECONNECT_INITIAL_DELAY, RECONNECT_DELAY_FACTOR, RECONNECT_MAX_DELAY } from './constants.js';
+import { PeriodicListenerInterval } from './models.js';
+import { OutboundWebSocketMessageType } from './types.js';
+
+/**
+ * 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/.
+ */
+/**
+ * A class used for managing the lifecycle of websocket connections
+ * to Jellyfin
+ */
+class WebSocketService {
+    /**
+     * Constructs a new instance of the {@link WebSocketService}
+     *
+     * @param uri The full URI path with the Authorization Header included as a query parameter.
+     *            May be omitted when no access token is available yet — subscriptions will be
+     *            preserved and the socket will connect once {@link updateUrl} is called.
+     */
+    constructor(uri) {
+        /**
+         * A map of message type subscriptions to their respective handlers
+         */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.subscriptions = new Map();
+        /**
+         * The number of consecutive reconnection attempts
+         */
+        this.reconnectionAttempts = 0;
+        /**
+         * Whether auto-reconnection is disabled (e.g., when token is cleared)
+         */
+        this.autoReconnectDisabled = false;
+        /**
+         * Status change event listeners
+         */
+        this.statusListeners = [];
+        /**
+         * Current connection status
+         */
+        this.currentStatus = 'disconnected';
+        if (uri) {
+            this.url = buildWebSocketUrl(uri);
+        }
+    }
+    /**
+     * Initializes the WebSocket connection and sets up event listeners
+     * if a valid URL is available. This function also establishes
+     * reconnection logic with exponential backoff if the connection is lost.
+     *
+     * This method is called internally when a new URL is provided or when
+     * the socket needs to be re-initialized.
+     *
+     * @returns void
+     */
+    initSocket() {
+        if (!this.url)
+            return;
+        this.socket = new WebSocket(this.url.toString());
+        this.socket.addEventListener('open', () => {
+            var _a, _b;
+            // Reset reconnection attempts on successful connection
+            this.reconnectionAttempts = 0;
+            // Update status and notify listeners
+            this.setStatus(WebSocket.OPEN);
+            // Send start messages for subscriptions that were added before the socket opened
+            for (const type of this.subscriptions.keys()) {
+                const mapping = SUBSCRIPTION_REGISTRY[type];
+                if (mapping) {
+                    this.sendMessage(mapping.createStartMessage((_b = (_a = this.subscriptionIntervals) === null || _a === void 0 ? void 0 : _a[type]) !== null && _b !== void 0 ? _b : new PeriodicListenerInterval(0, 1000)));
+                }
+            }
+        });
+        this.socket.addEventListener('message', (event) => {
+            const data = JSON.parse(event.data);
+            const { MessageType } = data;
+            if (MessageType === OutboundWebSocketMessageType.ForceKeepAlive && data.Data) {
+                this.clearKeepAlive();
+                this.sendKeepAlive();
+                this.keepAlive = setInterval(() => this.sendKeepAlive(), (data.Data * 1000) / 2);
+            }
+            else {
+                const handlers = this.subscriptions.get(MessageType);
+                handlers === null || handlers === void 0 ? void 0 : handlers.forEach(handler => handler(data));
+            }
+        });
+        this.socket.addEventListener('close', () => {
+            // Update status and notify listeners
+            this.setStatus('disconnected');
+            // Reconnect with exponential backoff if there are active subscriptions
+            // and auto-reconnect is not disabled
+            if (this.subscriptions.size > 0 && !this.autoReconnectDisabled) {
+                this.reconnectionAttempts++;
+                const delay = this.calculateBackoffDelay();
+                this.reconnectionTimeout = setTimeout(() => this.initSocket(), delay);
+            }
+            else {
+                // Else, close and dispose
+                this.socket = undefined;
+            }
+            this.clearKeepAlive();
+        });
+    }
+    /**
+     * Calculates the exponential backoff delay for reconnection attempts
+     * @returns The delay in milliseconds, capped at the maximum
+     */
+    calculateBackoffDelay() {
+        const exponentialDelay = RECONNECT_INITIAL_DELAY * Math.pow(RECONNECT_DELAY_FACTOR, this.reconnectionAttempts - 1);
+        return Math.min(exponentialDelay, RECONNECT_MAX_DELAY);
+    }
+    /**
+     * Sends a keep-alive message to the server.
+     */
+    sendKeepAlive() {
+        this.sendMessage({
+            MessageType: OutboundWebSocketMessageType.KeepAlive
+        });
+    }
+    /**
+     * Stops sending keep-alive messages.
+     */
+    clearKeepAlive() {
+        if (this.keepAlive) {
+            clearInterval(this.keepAlive);
+            this.keepAlive = undefined;
+        }
+    }
+    sendMessage(message) {
+        var _a;
+        if (((_a = this.socket) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
+            this.socket.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Internal method to update status and notify all listeners
+     */
+    setStatus(status) {
+        if (this.currentStatus !== status) {
+            this.currentStatus = status;
+            this.statusListeners.forEach(listener => listener(status));
+        }
+    }
+    /**
+     * Gets the current status of the websocket connection
+     * @returns The connection status
+     */
+    get socketStatus() {
+        return this.currentStatus;
+    }
+    /**
+     * Disconnects the WebSocket connection.
+     *
+     * Subscriptions are preserved and can be automatically restored
+     * when `updateUrl` is called with a new valid URL.
+     */
+    disconnect() {
+        var _a;
+        this.autoReconnectDisabled = true;
+        (_a = this.socket) === null || _a === void 0 ? void 0 : _a.close();
+        this.setStatus('disconnected');
+        this.socket = undefined;
+        this.reconnectionAttempts = 0;
+        if (this.reconnectionTimeout) {
+            clearTimeout(this.reconnectionTimeout);
+            this.reconnectionTimeout = undefined;
+        }
+        this.clearKeepAlive();
+    }
+    /**
+     * Updates the WebSocket URL and reconnects if there are active subscriptions.
+     *
+     * This re-enables auto-reconnection if it was previously disabled.
+     *
+     * Also used to supply the initial URL when the service was constructed without one
+     * (e.g. when no access token was available at construction time). In that case any
+     * subscriptions that were registered while disconnected will be restored immediately.
+     */
+    updateUrl(uri) {
+        var _a;
+        this.autoReconnectDisabled = true;
+        (_a = this.socket) === null || _a === void 0 ? void 0 : _a.close();
+        this.socket = undefined;
+        // Clear any pending reconnection timeout
+        if (this.reconnectionTimeout) {
+            clearTimeout(this.reconnectionTimeout);
+            this.reconnectionTimeout = undefined;
+        }
+        this.url = buildWebSocketUrl(uri);
+        // Re-disable auto-reconnect
+        this.autoReconnectDisabled = false;
+        if (this.subscriptions.size > 0) {
+            this.initSocket();
+        }
+    }
+    /**
+     * Adds a listener for websocket status changes
+     *
+     * @param onStatusChange Callback invoked when the connection status changes
+     * @returns A function which can be invoked to remove the listener
+     */
+    onStatusChange(onStatusChange) {
+        this.statusListeners.push(onStatusChange);
+        return () => {
+            const index = this.statusListeners.indexOf(onStatusChange);
+            if (index !== -1) {
+                this.statusListeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Adds message listeners for the provided message types.
+     *
+     * Adding a listener will establish a websocket connection if one does not already exist.
+     *
+     * Listeners will be automatically resubscribed if the connection is lost and re-established.
+     *
+     * Listeners can be removed by invoking the returned unsubscribe function.
+     *
+     * @param messageTypes Any array of {@link OutboundWebSocketMessage} message types to listen for
+     * @param onMessage The callback to invoke when a message is received
+     *
+     * @example
+     * const unsubscribe = api.webSocket.subscribe([OutboundWebSocketMessageType.Sessions], (message) => {
+     *   console.log('Received session update:', message);
+     * });
+     *
+     * @returns A function which can be invoked to remove the added listeners
+     */
+    subscribe(messageTypes, onMessage, subscriptionIntervals) {
+        var _a, _b;
+        // Check if socket needs to be initialized (only when a URL is available)
+        const needsInitialization = !!this.url && (!this.socket || this.socket.readyState === WebSocket.CLOSED);
+        // Update subscription intervals as provided
+        for (const interval in subscriptionIntervals) {
+            if (!this.subscriptionIntervals) {
+                this.subscriptionIntervals = subscriptionIntervals;
+            }
+            else {
+                this.subscriptionIntervals[interval] = subscriptionIntervals[interval];
+            }
+        }
+        if (needsInitialization) {
+            this.initSocket();
+        }
+        // Add the new handler for each message type
+        for (const type of messageTypes) {
+            const isNewType = !this.subscriptions.has(type);
+            if (isNewType) {
+                this.subscriptions.set(type, []);
+            }
+            this.subscriptions.get(type).push(onMessage);
+            // Send start message if socket is already open and this is a new type
+            // (if socket not open, it will be sent when the socket opens)
+            if (isNewType && ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN) {
+                const mapping = SUBSCRIPTION_REGISTRY[type];
+                if (mapping) {
+                    this.sendMessage(mapping.createStartMessage((_b = subscriptionIntervals === null || subscriptionIntervals === void 0 ? void 0 : subscriptionIntervals[type]) !== null && _b !== void 0 ? _b : new PeriodicListenerInterval(0, 1000)));
+                }
+            }
+        }
+        // Return an unsubscription function
+        return () => {
+            var _a;
+            for (const type of messageTypes) {
+                const handlers = this.subscriptions.get(type);
+                if (!handlers)
+                    continue;
+                const index = handlers.indexOf(onMessage);
+                if (index !== -1)
+                    handlers.splice(index, 1);
+                if (handlers.length === 0) {
+                    this.subscriptions.delete(type);
+                    // Send Stop Message
+                    const mapping = SUBSCRIPTION_REGISTRY[type];
+                    if (mapping)
+                        this.sendMessage(mapping.createStopMessage());
+                }
+            }
+            if (this.subscriptions.size === 0) {
+                (_a = this.socket) === null || _a === void 0 ? void 0 : _a.close();
+                this.setStatus('disconnected');
+                this.reconnectionAttempts = 0;
+                if (this.reconnectionTimeout) {
+                    clearTimeout(this.reconnectionTimeout);
+                    this.reconnectionTimeout = undefined;
+                }
+            }
+        };
+    }
+}
+
+export { WebSocketService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jellyfin/sdk",
-  "version": "0.12.0",
+  "version": "1.0.0",
   "description": "A TypeScript SDK for Jellyfin.",
   "keywords": [
     "jellyfin"
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "build": "npm run build:generated-client && npm run build:sdk",
-    "build:generated-client": "openapi-generator-cli generate",
+    "build:generated-client": "rimraf src/generated-client && openapi-generator-cli generate",
     "build:sdk": "rollup -c",
     "clean:build:sdk": "rimraf lib && rollup -c",
     "docs": "typedoc --tsconfig .",
@@ -26,22 +26,26 @@
     "test:integration": "vitest integration"
   },
   "devDependencies": {
-    "@openapitools/openapi-generator-cli": "2.25.0",
-    "@rollup/plugin-typescript": "12.1.4",
-    "@stylistic/eslint-plugin": "2.13.0",
-    "@tsconfig/recommended": "1.0.10",
-    "@typescript-eslint/eslint-plugin": "8.46.1",
-    "@typescript-eslint/parser": "8.46.1",
-    "@vitest/coverage-v8": "3.2.4",
-    "@vitest/eslint-plugin": "1.3.23",
-    "eslint": "8.57.1",
+    "@openapitools/openapi-generator-cli": "2.39.1",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@stylistic/eslint-plugin": "5.10.0",
+    "@tsconfig/recommended": "1.0.13",
+    "@types/node": "24.13.2",
+    "@typescript-eslint/eslint-plugin": "8.63.0",
+    "@typescript-eslint/parser": "8.63.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/eslint-plugin": "1.6.21",
+    "eslint": "9.39.4",
+    "eslint-import-resolver-typescript": "4.4.5",
     "eslint-plugin-import": "2.32.0",
-    "glob": "11.0.3",
+    "glob": "13.0.6",
+    "globals": "17.7.0",
     "rimraf": "5.0.10",
-    "rollup": "4.52.4",
-    "typedoc": "0.28.14",
-    "typescript": "5.9.3",
-    "vitest": "3.2.4"
+    "rollup": "4.62.2",
+    "typedoc": "0.28.20",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.63.0",
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
     "axios": "^1.12.0"

package/lib/generated-client/api/activity-log-api.d.ts

@@ -1,110 +0,0 @@
-/**
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * Do not edit the class manually.
- *
- * Jellyfin API
- *
- * 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/.
- */
-import type { Configuration } from '../configuration';
-import type { AxiosPromise, AxiosInstance, RawAxiosRequestConfig } from 'axios';
-import { type RequestArgs, BaseAPI } from '../base';
-import type { ActivityLogEntryQueryResult } from '../models';
-/**
- * ActivityLogApi - axios parameter creator
- * @export
- */
-export declare const ActivityLogApiAxiosParamCreator: (configuration?: Configuration) => {
-    /**
-     *
-     * @summary Gets activity log entries.
-     * @param {number} [startIndex] Optional. The record index to start at. All items with a lower index will be dropped from the results.
-     * @param {number} [limit] Optional. The maximum number of records to return.
-     * @param {string} [minDate] Optional. The minimum date. Format = ISO.
-     * @param {boolean} [hasUserId] Optional. Filter log entries if it has user id, or not.
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     */
-    getLogEntries: (startIndex?: number, limit?: number, minDate?: string, hasUserId?: boolean, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
-};
-/**
- * ActivityLogApi - functional programming interface
- * @export
- */
-export declare const ActivityLogApiFp: (configuration?: Configuration) => {
-    /**
-     *
-     * @summary Gets activity log entries.
-     * @param {number} [startIndex] Optional. The record index to start at. All items with a lower index will be dropped from the results.
-     * @param {number} [limit] Optional. The maximum number of records to return.
-     * @param {string} [minDate] Optional. The minimum date. Format &#x3D; ISO.
-     * @param {boolean} [hasUserId] Optional. Filter log entries if it has user id, or not.
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     */
-    getLogEntries(startIndex?: number, limit?: number, minDate?: string, hasUserId?: boolean, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<ActivityLogEntryQueryResult>>;
-};
-/**
- * ActivityLogApi - factory interface
- * @export
- */
-export declare const ActivityLogApiFactory: (configuration?: Configuration, basePath?: string, axios?: AxiosInstance) => {
-    /**
-     *
-     * @summary Gets activity log entries.
-     * @param {ActivityLogApiGetLogEntriesRequest} requestParameters Request parameters.
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     */
-    getLogEntries(requestParameters?: ActivityLogApiGetLogEntriesRequest, options?: RawAxiosRequestConfig): AxiosPromise<ActivityLogEntryQueryResult>;
-};
-/**
- * Request parameters for getLogEntries operation in ActivityLogApi.
- * @export
- * @interface ActivityLogApiGetLogEntriesRequest
- */
-export interface ActivityLogApiGetLogEntriesRequest {
-    /**
-     * Optional. The record index to start at. All items with a lower index will be dropped from the results.
-     * @type {number}
-     * @memberof ActivityLogApiGetLogEntries
-     */
-    readonly startIndex?: number;
-    /**
-     * Optional. The maximum number of records to return.
-     * @type {number}
-     * @memberof ActivityLogApiGetLogEntries
-     */
-    readonly limit?: number;
-    /**
-     * Optional. The minimum date. Format &#x3D; ISO.
-     * @type {string}
-     * @memberof ActivityLogApiGetLogEntries
-     */
-    readonly minDate?: string;
-    /**
-     * Optional. Filter log entries if it has user id, or not.
-     * @type {boolean}
-     * @memberof ActivityLogApiGetLogEntries
-     */
-    readonly hasUserId?: boolean;
-}
-/**
- * ActivityLogApi - object-oriented interface
- * @export
- * @class ActivityLogApi
- * @extends {BaseAPI}
- */
-export declare class ActivityLogApi extends BaseAPI {
-    /**
-     *
-     * @summary Gets activity log entries.
-     * @param {ActivityLogApiGetLogEntriesRequest} requestParameters Request parameters.
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     * @memberof ActivityLogApi
-     */
-    getLogEntries(requestParameters?: ActivityLogApiGetLogEntriesRequest, options?: RawAxiosRequestConfig): Promise<import("axios").AxiosResponse<ActivityLogEntryQueryResult, any, {}>>;
-}

package/lib/generated-client/api/activity-log-api.js

@@ -1,135 +0,0 @@
-import globalAxios from 'axios';
-import { DUMMY_BASE_URL, setApiKeyToObject, setSearchParams, toPathString, createRequestFunction } from '../common.js';
-import { operationServerMap, BaseAPI, BASE_PATH } from '../base.js';
-
-/* tslint:disable */
-/* eslint-disable */
-/**
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * Do not edit the class manually.
- *
- * Jellyfin API
- *
- * 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/.
- */
-/**
- * ActivityLogApi - axios parameter creator
- * @export
- */
-const ActivityLogApiAxiosParamCreator = function (configuration) {
-    return {
-        /**
-         *
-         * @summary Gets activity log entries.
-         * @param {number} [startIndex] Optional. The record index to start at. All items with a lower index will be dropped from the results.
-         * @param {number} [limit] Optional. The maximum number of records to return.
-         * @param {string} [minDate] Optional. The minimum date. Format = ISO.
-         * @param {boolean} [hasUserId] Optional. Filter log entries if it has user id, or not.
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        getLogEntries: async (startIndex, limit, minDate, hasUserId, options = {}) => {
-            const localVarPath = `/System/ActivityLog/Entries`;
-            // use dummy base URL string because the URL constructor only accepts absolute URLs.
-            const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL);
-            let baseOptions;
-            if (configuration) {
-                baseOptions = configuration.baseOptions;
-            }
-            const localVarRequestOptions = { method: 'GET', ...baseOptions, ...options };
-            const localVarHeaderParameter = {};
-            const localVarQueryParameter = {};
-            // authentication CustomAuthentication required
-            await setApiKeyToObject(localVarHeaderParameter, "Authorization", configuration);
-            if (startIndex !== undefined) {
-                localVarQueryParameter['startIndex'] = startIndex;
-            }
-            if (limit !== undefined) {
-                localVarQueryParameter['limit'] = limit;
-            }
-            if (minDate !== undefined) {
-                localVarQueryParameter['minDate'] = (minDate instanceof Date) ?
-                    minDate.toISOString() :
-                    minDate;
-            }
-            if (hasUserId !== undefined) {
-                localVarQueryParameter['hasUserId'] = hasUserId;
-            }
-            setSearchParams(localVarUrlObj, localVarQueryParameter);
-            let headersFromBaseOptions = baseOptions && baseOptions.headers ? baseOptions.headers : {};
-            localVarRequestOptions.headers = { ...localVarHeaderParameter, ...headersFromBaseOptions, ...options.headers };
-            return {
-                url: toPathString(localVarUrlObj),
-                options: localVarRequestOptions,
-            };
-        },
-    };
-};
-/**
- * ActivityLogApi - functional programming interface
- * @export
- */
-const ActivityLogApiFp = function (configuration) {
-    const localVarAxiosParamCreator = ActivityLogApiAxiosParamCreator(configuration);
-    return {
-        /**
-         *
-         * @summary Gets activity log entries.
-         * @param {number} [startIndex] Optional. The record index to start at. All items with a lower index will be dropped from the results.
-         * @param {number} [limit] Optional. The maximum number of records to return.
-         * @param {string} [minDate] Optional. The minimum date. Format = ISO.
-         * @param {boolean} [hasUserId] Optional. Filter log entries if it has user id, or not.
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        async getLogEntries(startIndex, limit, minDate, hasUserId, options) {
-            var _a, _b, _c;
-            const localVarAxiosArgs = await localVarAxiosParamCreator.getLogEntries(startIndex, limit, minDate, hasUserId, options);
-            const localVarOperationServerIndex = (_a = configuration === null || configuration === void 0 ? void 0 : configuration.serverIndex) !== null && _a !== void 0 ? _a : 0;
-            const localVarOperationServerBasePath = (_c = (_b = operationServerMap['ActivityLogApi.getLogEntries']) === null || _b === void 0 ? void 0 : _b[localVarOperationServerIndex]) === null || _c === void 0 ? void 0 : _c.url;
-            return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath);
-        },
-    };
-};
-/**
- * ActivityLogApi - factory interface
- * @export
- */
-const ActivityLogApiFactory = function (configuration, basePath, axios) {
-    const localVarFp = ActivityLogApiFp(configuration);
-    return {
-        /**
-         *
-         * @summary Gets activity log entries.
-         * @param {ActivityLogApiGetLogEntriesRequest} requestParameters Request parameters.
-         * @param {*} [options] Override http request option.
-         * @throws {RequiredError}
-         */
-        getLogEntries(requestParameters = {}, options) {
-            return localVarFp.getLogEntries(requestParameters.startIndex, requestParameters.limit, requestParameters.minDate, requestParameters.hasUserId, options).then((request) => request(axios, basePath));
-        },
-    };
-};
-/**
- * ActivityLogApi - object-oriented interface
- * @export
- * @class ActivityLogApi
- * @extends {BaseAPI}
- */
-class ActivityLogApi extends BaseAPI {
-    /**
-     *
-     * @summary Gets activity log entries.
-     * @param {ActivityLogApiGetLogEntriesRequest} requestParameters Request parameters.
-     * @param {*} [options] Override http request option.
-     * @throws {RequiredError}
-     * @memberof ActivityLogApi
-     */
-    getLogEntries(requestParameters = {}, options) {
-        return ActivityLogApiFp(this.configuration).getLogEntries(requestParameters.startIndex, requestParameters.limit, requestParameters.minDate, requestParameters.hasUserId, options).then((request) => request(this.axios, this.basePath));
-    }
-}
-
-export { ActivityLogApi, ActivityLogApiAxiosParamCreator, ActivityLogApiFactory, ActivityLogApiFp };