@jellyfin/sdk 0.13.0 → 1.0.0

package/lib/utils/api/year-api.js

@@ -0,0 +1,12 @@
+import { YearApi } from '../../generated-client/api/year-api.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/.
+ */
+function getYearApi(api) {
+    return new YearApi(api.configuration, undefined, api.axiosInstance);
+}
+
+export { getYearApi };

package/lib/utils/index.js

@@ -1,8 +1,8 @@
 export { JF_HTTPS_PORT, JF_HTTP_PORT, getAddressCandidates } from './address-candidates.js';
 export { getAuthorizationHeader } from './authentication.js';
 export { getBrowserDeviceProfile } from './browser-profiles.js';
-export { copyUrl, getDefaultPort, hasProtocolAndPort, isDefaultPort, parseUrl } from './url/index.js';
-export { isVersionLess } from './versioning.js';
+export { buildWebSocketUrl, copyUrl, getDefaultPort, hasProtocolAndPort, isDefaultPort, parseUrl } from './url/index.js';
+export { compareVersions, getDisplayVersion, isVersionLess } from './versioning.js';
 export { HTTPS_PORT, HTTPS_PROTOCOL, HTTP_PORT, HTTP_PROTOCOL } from './url/constants.js';
 
 /**

package/lib/utils/url/index.d.ts

@@ -36,3 +36,4 @@ export declare function isDefaultPort(url: URL): boolean;
  * @returns The URL object.
  */
 export declare function parseUrl(input: string): URL;
+export declare function buildWebSocketUrl(uri: string): URL;

package/lib/utils/url/index.js

@@ -59,5 +59,8 @@ function parseUrl(input) {
     }
     return new URL(normalizeUrl(input));
 }
+function buildWebSocketUrl(uri) {
+    return new URL(uri.replace(/^http/, 'ws'));
+}
 
-export { HTTPS_PORT, HTTPS_PROTOCOL, HTTP_PORT, HTTP_PROTOCOL, copyUrl, getDefaultPort, hasProtocolAndPort, isDefaultPort, parseUrl };
+export { HTTPS_PORT, HTTPS_PROTOCOL, HTTP_PORT, HTTP_PROTOCOL, buildWebSocketUrl, copyUrl, getDefaultPort, hasProtocolAndPort, isDefaultPort, parseUrl };

package/lib/utils/versioning.d.ts

@@ -1,9 +1,20 @@
+/**
+ * Compares two version strings (e.g., "1.2.3") and returns:
+ * -1 if a < b
+ * 1 if a > b
+ * 0 if a == b
+ *
+ * @throws If version is not in a numeric-only semver format
+ */
+export declare function compareVersions(a?: string, b?: string): 1 | 0 | -1;
 /**
  * Check if given version is less than a baseline
  *
- * Versions must be in semver format: X.Y.Z (Major.Minor.Patch)
+ * @deprecated Use {@link compareVersions} instead
  * @throws If version is not in a numeric-only semver format
  * @param check - The version to check
  * @param baseline - The minimum version considered supported
  */
 export declare function isVersionLess(check: string, baseline: string): boolean;
+/** Formats a version (e.g., "1.2.3") string for display. */
+export declare function getDisplayVersion(version: string | null | undefined): string | undefined;

package/lib/utils/versioning.js

@@ -1,32 +1,63 @@
 /**
- * @returns - Array of 3 numbers or undefined
+ * @returns - Array of numbers or undefined
  * (if the passed string it's not in the MAJOR.MINOR.PATCH numeric-only format)
  */
 function parseVersion(version) {
     const arr = version.split('.').map(Number);
-    if (arr.length === 3 && arr.every((n) => n >= 0)) {
+    if (arr.length && arr.every((n) => n >= 0)) {
         return arr;
     }
 }
+/**
+ * Compares two version strings (e.g., "1.2.3") and returns:
+ * -1 if a < b
+ * 1 if a > b
+ * 0 if a == b
+ *
+ * @throws If version is not in a numeric-only semver format
+ */
+function compareVersions(a = '', b = '') {
+    const aParts = parseVersion(a);
+    const bParts = parseVersion(b);
+    if (!aParts || !bParts) {
+        throw new TypeError("Version doesn't match a numeric-only semver format");
+    }
+    for (let i = 0, length = Math.max(aParts.length, bParts.length); i < length; i++) {
+        const aVal = aParts[i] || 0;
+        const bVal = bParts[i] || 0;
+        if (aVal < bVal) {
+            return -1;
+        }
+        if (aVal > bVal) {
+            return 1;
+        }
+    }
+    return 0;
+}
 /**
  * Check if given version is less than a baseline
  *
- * Versions must be in semver format: X.Y.Z (Major.Minor.Patch)
+ * @deprecated Use {@link compareVersions} instead
  * @throws If version is not in a numeric-only semver format
  * @param check - The version to check
  * @param baseline - The minimum version considered supported
  */
 function isVersionLess(check, baseline) {
-    const parsedCheck = parseVersion(check);
-    const parsedBaseline = parseVersion(baseline);
-    if (!parsedCheck || !parsedBaseline) {
-        throw new TypeError("Version doesn't match a numeric-only semver format");
+    return compareVersions(check, baseline) < 0;
+}
+/** Formats a version (e.g., "1.2.3") string for display. */
+function getDisplayVersion(version) {
+    if (!version)
+        return;
+    // For versions above 10.X, we switch to only showing MAJOR.MINOR to reflect the new versioning scheme.
+    const parts = parseVersion(version);
+    if (parts && compareVersions(version, '11') >= 0) {
+        // Just in case we have a patch version that isn't 0, we want to show it. This should not happen.
+        if (parts.length === 3 && parts[2] !== 0)
+            return version;
+        return parts.slice(0, 2).join('.');
     }
-    const [majorCheck, minorCheck, patchCheck] = parsedCheck;
-    const [majorBaseline, minorBaseline, patchBaseline] = parsedBaseline;
-    return (majorCheck < majorBaseline ||
-        (majorCheck === majorBaseline && minorCheck < minorBaseline) ||
-        (majorCheck === majorBaseline && minorCheck === minorBaseline && patchCheck < patchBaseline));
+    return version;
 }
 
-export { isVersionLess };
+export { compareVersions, getDisplayVersion, isVersionLess };

package/lib/versions.d.ts

@@ -4,6 +4,6 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 /** The current API version of the generated client. */
-export declare const API_VERSION = "10.11.1";
+export declare const API_VERSION = "13.0.0";
 /** The minimum supported server version. */
 export declare const MINIMUM_VERSION = "10.10.0";

package/lib/versions.js

@@ -4,7 +4,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 /** The current API version of the generated client. */
-const API_VERSION = '10.11.1';
+const API_VERSION = '13.0.0';
 /** The minimum supported server version. */
 const MINIMUM_VERSION = '10.10.0';
 

package/lib/websocket/constants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 { WebSocketSubscription } from './types';
+import { OutboundWebSocketMessageType } from './types';
+/**
+ * The URL path segment for websocket connections
+ */
+export declare const WEBSOCKET_URL_PATH = "socket";
+/**
+ * The initial timeout interval in milliseconds for exponential backoff reconnection
+ */
+export declare const RECONNECT_INITIAL_DELAY = 1000;
+/**
+ * The multiplier for exponential backoff on each reconnection attempt
+ */
+export declare const RECONNECT_DELAY_FACTOR = 1.5;
+/**
+ * The maximum timeout interval in milliseconds for reconnection attempts
+ */
+export declare const RECONNECT_MAX_DELAY: number;
+export declare const SUBSCRIPTION_REGISTRY: Partial<Record<OutboundWebSocketMessageType, WebSocketSubscription<OutboundWebSocketMessageType>>>;

package/lib/websocket/constants.js

@@ -0,0 +1,42 @@
+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/.
+ */
+/**
+ * The URL path segment for websocket connections
+ */
+const WEBSOCKET_URL_PATH = 'socket';
+/**
+ * The initial timeout interval in milliseconds for exponential backoff reconnection
+ */
+const RECONNECT_INITIAL_DELAY = 1000;
+/**
+ * The multiplier for exponential backoff on each reconnection attempt
+ */
+const RECONNECT_DELAY_FACTOR = 1.5;
+/**
+ * The maximum timeout interval in milliseconds for reconnection attempts
+ */
+const RECONNECT_MAX_DELAY = 60000 * 5;
+const SUBSCRIPTION_REGISTRY = {
+    [OutboundWebSocketMessageType.Sessions]: {
+        messageType: OutboundWebSocketMessageType.Sessions,
+        createStartMessage: (interval) => ({ MessageType: 'SessionsStart', Data: interval.toString() }),
+        createStopMessage: () => ({ MessageType: 'SessionsStop' })
+    },
+    [OutboundWebSocketMessageType.ActivityLogEntry]: {
+        messageType: OutboundWebSocketMessageType.ActivityLogEntry,
+        createStartMessage: (interval) => ({ MessageType: 'ActivityLogEntryStart', Data: interval.toString() }),
+        createStopMessage: () => ({ MessageType: 'ActivityLogEntryStop' })
+    },
+    [OutboundWebSocketMessageType.ScheduledTasksInfo]: {
+        messageType: OutboundWebSocketMessageType.ScheduledTasksInfo,
+        createStartMessage: (interval) => ({ MessageType: 'ScheduledTasksInfoStart', Data: interval.toString() }),
+        createStopMessage: () => ({ MessageType: 'ScheduledTasksInfoStop' })
+    }
+};
+
+export { RECONNECT_DELAY_FACTOR, RECONNECT_INITIAL_DELAY, RECONNECT_MAX_DELAY, SUBSCRIPTION_REGISTRY, WEBSOCKET_URL_PATH };

package/lib/websocket/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/.
+ */
+export * from './websocket-service';
+export * from './types';
+export * from './models';

package/lib/websocket/index.js

@@ -0,0 +1,3 @@
+export { WebSocketService } from './websocket-service.js';
+export { OutboundWebSocketMessageType } from './types.js';
+export { PeriodicListenerInterval } from './models.js';

package/lib/{utils/api/client-log-api.d.ts → websocket/models.d.ts}

@@ -3,6 +3,9 @@
  * 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 { Api } from '../../api';
-import { ClientLogApi } from '../../generated-client/api/client-log-api';
-export declare function getClientLogApi(api: Api): ClientLogApi;
+export declare class PeriodicListenerInterval {
+    initialDelay: number;
+    interval: number;
+    constructor(initialDelay: number, interval: number);
+    toString(): string;
+}

package/lib/websocket/models.js

@@ -0,0 +1,16 @@
+/**
+ * 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/.
+ */
+class PeriodicListenerInterval {
+    constructor(initialDelay, interval) {
+        this.initialDelay = initialDelay;
+        this.interval = interval;
+    }
+    toString() {
+        return `${this.initialDelay},${this.interval}`;
+    }
+}
+
+export { PeriodicListenerInterval };

package/lib/websocket/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 { InboundWebSocketMessage } from '../generated-client';
+import type { OutboundWebSocketMessage } from '../generated-client/models/outbound-web-socket-message';
+import type { PeriodicListenerInterval } from './models';
+export type WebSocketStatus = WebSocket['readyState'] | 'disconnected';
+export type SocketMessageHandler<T extends OutboundWebSocketMessageType> = (message: Extract<OutboundWebSocketMessage, {
+    MessageType: T;
+}>) => void;
+export type SocketStatusHandler = (status: WebSocket['readyState'] | 'disconnected') => void;
+export type WebSocketSubscription<T extends OutboundWebSocketMessageType> = {
+    messageType: T;
+    createStartMessage: (interval: PeriodicListenerInterval) => InboundWebSocketMessage;
+    createStopMessage: () => InboundWebSocketMessage;
+};
+/**
+ * The different kinds of outbound messages sent by the WebSocket API.
+ * @export
+ * @enum {string}
+ */
+export declare const OutboundWebSocketMessageType: {
+    [T in OutboundWebSocketMessageType]: T;
+};
+export type OutboundWebSocketMessageType = OutboundWebSocketMessage['MessageType'];
+/**
+ * A mapping of outbound WebSocket message types to their respective periodic listener intervals.
+ *
+ * @example
+ * const intervals: WebSocketSubscriptionIntervals = {
+ *   [OutboundWebSocketMessageType.ActivityLogEntry]: new PeriodicListenerInterval(0, 1000),
+ *   [OutboundWebSocketMessageType.Sessions]: new PeriodicListenerInterval(0, 5000)
+ * };
+ */
+export type WebSocketSubscriptionIntervals = Partial<Record<OutboundWebSocketMessageType, PeriodicListenerInterval>>;

package/lib/websocket/types.js

@@ -0,0 +1,42 @@
+/**
+ * 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 different kinds of outbound messages sent by the WebSocket API.
+ * @export
+ * @enum {string}
+ */
+const OutboundWebSocketMessageType = {
+    ActivityLogEntry: 'ActivityLogEntry',
+    ForceKeepAlive: 'ForceKeepAlive',
+    GeneralCommand: 'GeneralCommand',
+    KeepAlive: 'KeepAlive',
+    LibraryChanged: 'LibraryChanged',
+    PackageInstallationCancelled: 'PackageInstallationCancelled',
+    PackageInstallationCompleted: 'PackageInstallationCompleted',
+    PackageInstallationFailed: 'PackageInstallationFailed',
+    PackageInstalling: 'PackageInstalling',
+    PackageUninstalled: 'PackageUninstalled',
+    Play: 'Play',
+    Playstate: 'Playstate',
+    RefreshProgress: 'RefreshProgress',
+    RestartRequired: 'RestartRequired',
+    ScheduledTaskEnded: 'ScheduledTaskEnded',
+    ScheduledTasksInfo: 'ScheduledTasksInfo',
+    SeriesTimerCancelled: 'SeriesTimerCancelled',
+    SeriesTimerCreated: 'SeriesTimerCreated',
+    ServerRestarting: 'ServerRestarting',
+    ServerShuttingDown: 'ServerShuttingDown',
+    Sessions: 'Sessions',
+    SyncPlayCommand: 'SyncPlayCommand',
+    SyncPlayGroupUpdate: 'SyncPlayGroupUpdate',
+    TimerCancelled: 'TimerCancelled',
+    TimerCreated: 'TimerCreated',
+    UserDataChanged: 'UserDataChanged',
+    UserDeleted: 'UserDeleted',
+    UserUpdated: 'UserUpdated'
+};
+
+export { OutboundWebSocketMessageType };

package/lib/websocket/websocket-service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 { WebSocketSubscriptionIntervals } from './types';
+import { OutboundWebSocketMessageType, type SocketMessageHandler, type SocketStatusHandler, type WebSocketStatus } from './types';
+/**
+ * A class used for managing the lifecycle of websocket connections
+ * to Jellyfin
+ */
+export declare class WebSocketService {
+    /**
+     * The URL to connect to.
+     *
+     * Created in the constructor (or later via {@link updateUrl}), using the fields from
+     * the authenticated Api instance. If undefined, the socket will not connect until
+     * a URL is provided via {@link updateUrl}.
+     */
+    private url;
+    /**
+     * The active websocket connection, if one exists.
+     */
+    private socket;
+    /**
+     * The keep-alive interval handle.
+     *
+     * Sends a keep-alive message for as long as the socket is open.
+     */
+    private keepAlive;
+    /**
+     * A map of message type subscriptions to their respective handlers
+     */
+    private readonly subscriptions;
+    private subscriptionIntervals?;
+    /**
+     * The number of consecutive reconnection attempts
+     */
+    private reconnectionAttempts;
+    /**
+     * The timeout handle for reconnection
+     */
+    private reconnectionTimeout;
+    /**
+     * Whether auto-reconnection is disabled (e.g., when token is cleared)
+     */
+    private autoReconnectDisabled;
+    /**
+     * Status change event listeners
+     */
+    private readonly statusListeners;
+    /**
+     * Current connection status
+     */
+    private currentStatus;
+    /**
+     * 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?: string);
+    /**
+     * 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
+     */
+    private initSocket;
+    /**
+     * Calculates the exponential backoff delay for reconnection attempts
+     * @returns The delay in milliseconds, capped at the maximum
+     */
+    private calculateBackoffDelay;
+    /**
+     * Sends a keep-alive message to the server.
+     */
+    private sendKeepAlive;
+    /**
+     * Stops sending keep-alive messages.
+     */
+    private clearKeepAlive;
+    private sendMessage;
+    /**
+     * Internal method to update status and notify all listeners
+     */
+    private setStatus;
+    /**
+     * Gets the current status of the websocket connection
+     * @returns The connection status
+     */
+    get socketStatus(): WebSocketStatus | undefined;
+    /**
+     * Disconnects the WebSocket connection.
+     *
+     * Subscriptions are preserved and can be automatically restored
+     * when `updateUrl` is called with a new valid URL.
+     */
+    disconnect(): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: SocketStatusHandler): () => void;
+    /**
+     * 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<T extends OutboundWebSocketMessageType>(messageTypes: T[], onMessage: SocketMessageHandler<T>, subscriptionIntervals?: WebSocketSubscriptionIntervals): () => void;
+}