@francofantomius/jellyfin 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1092 @@
+type VideoQualityPresetKey = 'auto' | 'direct' | '4k' | '1080p-high' | '1080p' | '720p-high' | '720p' | '480p' | '360p' | '240p';
+interface VideoQualityOption {
+    key: VideoQualityPresetKey;
+    label: string;
+    bitrate?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}
+type AudioQualityPresetKey = 'direct' | '320k' | '256k' | '192k' | '128k' | '64k';
+interface AudioQualityOption {
+    key: AudioQualityPresetKey;
+    label: string;
+    bitrate?: number;
+}
+declare const VIDEO_QUALITY_PRESETS: Record<VideoQualityPresetKey, VideoQualityOption>;
+declare const AUDIO_QUALITY_PRESETS: Record<AudioQualityPresetKey, AudioQualityOption>;
+/**
+ * Returns a list of all available video quality presets.
+ */
+declare function getVideoQualityList(): VideoQualityOption[];
+/**
+ * Returns a list of all available audio quality presets.
+ */
+declare function getAudioQualityList(): AudioQualityOption[];
+/**
+ * Resolves video quality option into bitrate, maxWidth, and maxHeight constraints.
+ */
+declare function resolveVideoQuality(quality?: VideoQualityPresetKey | VideoQualityOption | number | string): {
+    maxStreamingBitrate?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+};
+/**
+ * Resolves audio quality option into bitrate constraint.
+ */
+declare function resolveAudioQuality(quality?: AudioQualityPresetKey | AudioQualityOption | number | string): {
+    maxStreamingBitrate?: number;
+};
+/**
+ * Formats a bitrate in bps into a human-readable string (e.g. "10 Mbps", "320 kbps").
+ */
+declare function formatBitrate(bitrate?: number): string;
+
+/**
+ * Client identification info sent in Jellyfin authorization headers.
+ */
+interface ClientInfo {
+    name: string;
+    version: string;
+    device: string;
+    deviceId: string;
+}
+/**
+ * Storage adapter interface for persisting session data.
+ */
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/**
+ * Options to initialize a JellyfinClient.
+ */
+interface JellyfinClientOptions {
+    /**
+     * Base URL of the Jellyfin server (e.g., https://jellyfin.example.com).
+     */
+    serverUrl?: string;
+    /**
+     * Jellyfin access token for authenticated requests.
+     */
+    accessToken?: string;
+    /**
+     * Jellyfin User ID.
+     */
+    userId?: string;
+    /**
+     * Client identity parameters. Defaults to generic SDK information if omitted.
+     */
+    clientInfo?: Partial<ClientInfo>;
+    /**
+     * Custom storage adapter to persist session data (e.g. LocalStorageAdapter or custom).
+     * Defaults to MemoryStorage.
+     */
+    storage?: StorageAdapter;
+    /**
+     * Custom fetch function (defaults to globalThis.fetch).
+     */
+    fetch?: typeof fetch;
+    /**
+     * Callback invoked when a 401 Unauthorized response is received.
+     */
+    onUnauthorized?: () => void;
+    /**
+     * Pinned server version or version hint (e.g. "12.0.0" or "10.9.11").
+     * If omitted, the client can auto-detect via SystemModule.
+     */
+    serverVersion?: string;
+    /**
+     * Compatibility target version: 'auto' (detect automatically), '10' (legacy Jellyfin 10.x), or '12' (Jellyfin 12+).
+     * Defaults to 'auto'.
+     */
+    targetVersion?: 'auto' | '10' | '12';
+}
+/**
+ * Authenticated user information.
+ */
+interface UserDto {
+    Id: string;
+    Name: string;
+    ServerId?: string;
+    PrimaryImageTag?: string;
+    ImageTags?: Record<string, string>;
+    HasPassword?: boolean;
+    LastLoginDate?: string;
+    LastActivityDate?: string;
+    Configuration?: Record<string, unknown>;
+    Policy?: Record<string, unknown>;
+}
+/**
+ * Authentication response from Jellyfin.
+ */
+interface AuthenticationResult {
+    User: UserDto;
+    AccessToken: string;
+    ServerId: string;
+    SessionInfo?: Record<string, unknown>;
+}
+/**
+ * Generic Jellyfin items response.
+ */
+interface ItemsResponse<T = BaseItemDto> {
+    Items: T[];
+    TotalRecordCount: number;
+    StartIndex?: number;
+}
+/**
+ * User data associated with an item (played status, favorites, rating).
+ */
+interface UserItemDataDto {
+    Rating?: number;
+    PlayedPercentage?: number;
+    UnplayedItemCount?: number;
+    PlaybackPositionTicks?: number;
+    PlayCount?: number;
+    IsFavorite?: boolean;
+    LastPlayedDate?: string;
+    Played?: boolean;
+    Key?: string;
+}
+/**
+ * Common Jellyfin item structure.
+ */
+interface BaseItemDto {
+    Id: string;
+    Name: string;
+    ServerId?: string;
+    Type?: string;
+    CollectionType?: string;
+    RunTimeTicks?: number;
+    Container?: string;
+    MediaType?: string;
+    ProductionYear?: number;
+    IndexNumber?: number;
+    ParentIndexNumber?: number;
+    IndexNumberEnd?: number;
+    IsFolder?: boolean;
+    ParentId?: string;
+    Album?: string;
+    AlbumId?: string;
+    AlbumPrimaryImageTag?: string;
+    AlbumArtist?: string;
+    Artists?: string[];
+    ArtistItems?: Array<{
+        Id: string;
+        Name: string;
+    }>;
+    Overview?: string;
+    Genres?: string[];
+    Taglines?: string[];
+    DateCreated?: string;
+    DateLastMediaAdded?: string;
+    UserData?: UserItemDataDto;
+    PrimaryImageAspectRatio?: number;
+    ImageTags?: Record<string, string>;
+    PrimaryImageTag?: string;
+    BackdropImageTags?: string[];
+    MediaSources?: MediaSourceInfo[];
+    HasLyrics?: boolean;
+    /**
+     * Unique relational playlist entry ID (Jellyfin 12+).
+     * Distinguishes duplicate tracks inside the same playlist.
+     */
+    PlaylistItemId?: string;
+    [key: string]: unknown;
+}
+interface MediaSourceInfo {
+    Id?: string;
+    Path?: string;
+    Protocol?: string;
+    MediaStreams?: MediaStreamInfo[];
+    Container?: string;
+    Size?: number;
+    Bitrate?: number;
+}
+interface MediaStreamInfo {
+    Codec?: string;
+    Type?: string;
+    Index?: number;
+    BitRate?: number;
+    Channels?: number;
+    SampleRate?: number;
+    Width?: number;
+    Height?: number;
+    AspectRatio?: string;
+    AverageFrameRate?: number;
+    RealFrameRate?: number;
+    Profile?: string;
+    Level?: number;
+    PixelFormat?: string;
+    IsInterlaced?: boolean;
+    Language?: string;
+    DisplayTitle?: string;
+    DisplayLanguage?: string;
+    IsDefault?: boolean;
+    IsForced?: boolean;
+    IsExternal?: boolean;
+    DeliveryMethod?: string;
+    DeliveryUrl?: string;
+    [key: string]: unknown;
+}
+interface GetAlbumsOptions {
+    limit?: number;
+    startIndex?: number;
+    parentId?: string;
+    artistId?: string;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+}
+interface GetArtistsOptions {
+    limit?: number;
+    startIndex?: number;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+}
+interface GetSongsOptions {
+    limit?: number;
+    startIndex?: number;
+    albumId?: string;
+    artistId?: string;
+    isFavorite?: boolean;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+}
+interface SearchOptions {
+    limit?: number;
+    startIndex?: number;
+    includeItemTypes?: string;
+}
+interface CreatePlaylistDto {
+    Name: string;
+    Ids?: string[];
+    UserId?: string;
+    MediaType?: string;
+    Users?: Array<{
+        UserId: string;
+        CanEdit?: boolean;
+    }>;
+    IsPublic?: boolean;
+}
+interface CreatePlaylistOptions {
+    name: string;
+    isPublic?: boolean;
+    trackIds?: string[];
+    userId?: string;
+    mediaType?: string;
+}
+interface UpdatePlaylistOptions {
+    name?: string;
+}
+interface AudioStreamOptions {
+    maxStreamingBitrate?: string | number;
+    quality?: AudioQualityPresetKey | AudioQualityOption | number | string;
+    startTimeTicks?: number;
+    container?: string;
+    transcodingContainer?: string;
+    audioCodec?: string;
+    /**
+     * Whether to include the api_key token in the URL query parameters.
+     * Defaults to true for HTML5 <audio> tag compatibility.
+     * If false, callers are expected to provide Authorization headers.
+     */
+    useQueryToken?: boolean;
+}
+interface AudioHlsStreamOptions {
+    maxStreamingBitrate?: string | number;
+    quality?: AudioQualityPresetKey | AudioQualityOption | number | string;
+    startTimeTicks?: number;
+    audioCodec?: string;
+    segmentLength?: number;
+    /**
+     * Whether to include the api_key token in the URL query parameters.
+     * Defaults to true for legacy compatibility.
+     * If false, players (e.g. hls.js) should be configured with Authorization headers via xhrSetup.
+     */
+    useQueryToken?: boolean;
+}
+interface ArtworkUrlOptions {
+    imageType?: 'Primary' | 'Art' | 'Backdrop' | 'Banner' | 'Logo' | 'Thumb' | 'Disc';
+    maxWidth?: number;
+    maxHeight?: number;
+    quality?: number;
+    fallbackUrl?: string;
+}
+interface PublicSystemInfo {
+    LocalAddress?: string;
+    ServerName?: string;
+    Version?: string;
+    ProductName?: string;
+    OperatingSystem?: string;
+    Id?: string;
+    StartupWizardCompleted?: boolean;
+    [key: string]: unknown;
+}
+interface SystemInfo extends PublicSystemInfo {
+    SystemArchitecture?: string;
+    HasPendingRestart?: boolean;
+    IsShuttingDown?: boolean;
+    SupportsLibraryMonitor?: boolean;
+    WebSocketPortNumber?: number;
+    CompletedInstallations?: unknown[];
+    CanSelfRestart?: boolean;
+    CanLaunchWebBrowser?: boolean;
+    ProgramDataPath?: string;
+    WebPath?: string;
+    ItemsByNamePath?: string;
+    CachePath?: string;
+    LogPath?: string;
+    InternalMetadataPath?: string;
+    TranscodingTempPath?: string;
+    HasUpdateAvailable?: boolean;
+}
+interface LyricLine {
+    Start?: number;
+    Text: string;
+}
+interface LyricsDto {
+    Lyrics?: LyricLine[];
+    [key: string]: unknown;
+}
+interface ClientCapabilities {
+    PlayableMediaTypes?: string[];
+    SupportedCommands?: string[];
+    SupportsMediaControl?: boolean;
+    SupportsSync?: boolean;
+    SupportsPersistentIdentifier?: boolean;
+    IconUrl?: string;
+    AppStoreUrl?: string;
+    MessageFormat?: string;
+}
+interface GetMoviesOptions {
+    limit?: number;
+    startIndex?: number;
+    parentId?: string;
+    isFavorite?: boolean;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+    genres?: string[];
+    years?: number[];
+    searchTerm?: string;
+}
+interface GetSeriesOptions {
+    limit?: number;
+    startIndex?: number;
+    parentId?: string;
+    isFavorite?: boolean;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+    genres?: string[];
+    years?: number[];
+    searchTerm?: string;
+}
+interface GetSeasonsOptions {
+    userId?: string;
+    fields?: string;
+    isSpecialSeason?: boolean;
+}
+interface GetEpisodesOptions {
+    seasonId?: string;
+    seasonNumber?: number;
+    startIndex?: number;
+    limit?: number;
+    isMissing?: boolean;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+}
+interface GetVideosOptions {
+    limit?: number;
+    startIndex?: number;
+    parentId?: string;
+    includeItemTypes?: string;
+    sortBy?: string;
+    sortOrder?: 'Ascending' | 'Descending';
+}
+interface PlaybackInfoOptions {
+    userId?: string;
+    startTimeTicks?: number;
+    audioStreamIndex?: number;
+    subtitleStreamIndex?: number;
+    maxStreamingBitrate?: number;
+    mediaSourceId?: string;
+    deviceProfile?: Record<string, unknown>;
+    autoOpenLiveStream?: boolean;
+}
+interface PlaybackInfoResponse {
+    MediaSources: MediaSourceInfo[];
+    PlaySessionId?: string;
+    ErrorCode?: string;
+    [key: string]: unknown;
+}
+interface VideoStreamOptions {
+    mediaSourceId?: string;
+    static?: boolean;
+    videoCodec?: string;
+    audioCodec?: string;
+    maxStreamingBitrate?: string | number;
+    quality?: VideoQualityPresetKey | VideoQualityOption | number | string;
+    maxWidth?: number;
+    maxHeight?: number;
+    maxFramerate?: number;
+    audioStreamIndex?: number;
+    subtitleStreamIndex?: number;
+    subtitleMethod?: 'Embed' | 'Encode' | 'Hls' | 'External';
+    startTimeTicks?: number;
+    container?: string;
+    transcodingContainer?: string;
+    transcodingProtocol?: string;
+    useQueryToken?: boolean;
+}
+interface VideoHlsStreamOptions {
+    mediaSourceId?: string;
+    videoCodec?: string;
+    audioCodec?: string;
+    maxStreamingBitrate?: string | number;
+    quality?: VideoQualityPresetKey | VideoQualityOption | number | string;
+    maxWidth?: number;
+    maxHeight?: number;
+    maxFramerate?: number;
+    segmentLength?: number;
+    minSegments?: number;
+    audioStreamIndex?: number;
+    subtitleStreamIndex?: number;
+    subtitleMethod?: 'Embed' | 'Encode' | 'Hls' | 'External';
+    transcodingContainer?: 'ts' | 'fmp4' | string;
+    transcodingProtocol?: 'hls';
+    startTimeTicks?: number;
+    useQueryToken?: boolean;
+}
+interface SubtitleTrackInfo {
+    index: number;
+    codec: string;
+    language?: string;
+    displayTitle: string;
+    displayLanguage?: string;
+    isDefault: boolean;
+    isForced: boolean;
+    isExternal: boolean;
+    deliveryMethod?: string;
+    deliveryUrl?: string;
+    url: string;
+}
+interface SubtitleUrlOptions {
+    format?: 'vtt' | 'srt' | 'subrip' | string;
+    useQueryToken?: boolean;
+    startTimeTicks?: number;
+}
+interface DownloadUrlOptions {
+    useQueryToken?: boolean;
+    filename?: string;
+}
+interface DownloadItemOptions {
+    onProgress?: (progressFraction: number) => void;
+    group?: {
+        id?: string;
+        name?: string;
+        type?: string;
+        artworkUrl?: string;
+        owner?: string;
+        count?: number;
+    } | null;
+    index?: number;
+    quality?: VideoQualityPresetKey | VideoQualityOption | number | string;
+}
+
+interface RequestOptions {
+    method?: string;
+    params?: Record<string, unknown>;
+    body?: unknown;
+    contentType?: string;
+    headers?: Record<string, string>;
+}
+declare function cleanUrl(url: string): string;
+declare function buildAuthHeader(clientInfo: ClientInfo, token?: string): string;
+declare class HttpTransport {
+    private serverUrl;
+    private token;
+    private clientInfo;
+    private fetchFn;
+    private onUnauthorized?;
+    constructor(options: {
+        serverUrl?: string;
+        token?: string;
+        clientInfo: ClientInfo;
+        fetch?: typeof fetch;
+        onUnauthorized?: () => void;
+    });
+    setServerUrl(url: string): void;
+    getServerUrl(): string;
+    setToken(token: string): void;
+    getToken(): string;
+    setClientInfo(info: Partial<ClientInfo>): void;
+    getClientInfo(): ClientInfo;
+    setOnUnauthorized(handler?: () => void): void;
+    getAuthHeader(): string;
+    requestRaw(endpoint: string, options?: RequestOptions): Promise<Response>;
+    request<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T>;
+    requestText(endpoint: string, options?: RequestOptions): Promise<string>;
+    requestBlob(endpoint: string, options?: RequestOptions): Promise<Blob>;
+}
+
+declare class AuthModule {
+    private http;
+    private currentUser;
+    private currentUserId;
+    private currentUsername;
+    constructor(http: HttpTransport, userId?: string);
+    getUserId(): string;
+    setUserId(id: string): void;
+    getUsername(): string;
+    getCurrentUser(): UserDto | null;
+    setCurrentUser(user: UserDto | null): void;
+    /**
+     * Authenticate with the Jellyfin server using username and password.
+     */
+    authenticateByName(username: string, password?: string): Promise<AuthenticationResult>;
+    /**
+     * Report client capabilities to the Jellyfin server.
+     */
+    reportCapabilities(capabilities?: ClientCapabilities): Promise<void>;
+    /**
+     * Build the user profile avatar image URL.
+     */
+    getUserImageUrl(userId?: string, tag?: string): string;
+    /**
+     * Clear active user credentials and token.
+     */
+    logout(): void;
+}
+
+/**
+ * Parses a semantic version string (e.g. "10.9.11", "12.0.0", "12.0.0-rc1") into numeric components.
+ */
+declare function parseSemVer(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+} | null;
+/**
+ * Checks if currentVersion is greater than or equal to targetVersion.
+ */
+declare function isVersionAtLeast(currentVersion: string, targetVersion: string): boolean;
+/**
+ * Checks if the given version string represents Jellyfin 12.0.0 or higher.
+ */
+declare function isV12OrHigher(version?: string): boolean;
+declare class SystemModule {
+    private http;
+    private serverVersion;
+    private targetVersion;
+    constructor(http: HttpTransport, options?: {
+        serverVersion?: string;
+        targetVersion?: 'auto' | '10' | '12';
+    });
+    /**
+     * Get public system info without requiring authentication.
+     */
+    getPublicInfo(): Promise<PublicSystemInfo>;
+    /**
+     * Get full system info (requires authentication).
+     */
+    getInfo(): Promise<SystemInfo>;
+    /**
+     * Get the cached or explicitly configured server version string.
+     */
+    getVersion(): string | null;
+    /**
+     * Manually set or override the server version.
+     */
+    setVersion(version: string | null): void;
+    /**
+     * Get the configured target compatibility mode.
+     */
+    getTargetVersion(): 'auto' | '10' | '12';
+    /**
+     * Set target compatibility mode.
+     */
+    setTargetVersion(target: 'auto' | '10' | '12'): void;
+    /**
+     * Detects and caches the server version by calling /System/Info/Public.
+     */
+    detectVersion(): Promise<string | null>;
+    /**
+     * Checks whether the current server is Jellyfin 12 or higher.
+     * If targetVersion is explicitly set to '12' or '10', that preference is honored.
+     * If 'auto', resolves against known version or attempts detection.
+     */
+    isV12(): Promise<boolean>;
+    /**
+     * Synchronously checks if the server is known to be v12+ based on cached version or target setting.
+     * Defaults to true (modern behavior) if unknown.
+     */
+    isV12Sync(): boolean;
+}
+
+declare class LibraryModule {
+    private http;
+    private getUserId;
+    constructor(http: HttpTransport, getUserId: () => string);
+    private requireUserId;
+    /**
+     * Get list of music library views (folders) for the current user.
+     */
+    getMusicLibraries(): Promise<BaseItemDto[]>;
+    /**
+     * Get list of video library views (movies, tv shows, home videos) for the current user.
+     */
+    getVideoLibraries(): Promise<BaseItemDto[]>;
+    /**
+     * Get music albums.
+     */
+    getAlbums(options?: GetAlbumsOptions): Promise<ItemsResponse>;
+    /**
+     * Get music artists.
+     */
+    getArtists(options?: GetArtistsOptions): Promise<ItemsResponse>;
+    /**
+     * Get audio songs/tracks.
+     */
+    getSongs(options?: GetSongsOptions): Promise<ItemsResponse>;
+    /**
+     * Get favorite songs/tracks for the current user.
+     */
+    getFavoriteSongs(options?: Omit<GetSongsOptions, 'isFavorite'>): Promise<ItemsResponse>;
+    /**
+     * Get movies for the current user.
+     */
+    getMovies(options?: GetMoviesOptions): Promise<ItemsResponse>;
+    /**
+     * Get TV series for the current user.
+     */
+    getSeries(options?: GetSeriesOptions): Promise<ItemsResponse>;
+    /**
+     * Get seasons for a given TV series.
+     */
+    getSeasons(seriesId: string, options?: GetSeasonsOptions): Promise<ItemsResponse>;
+    /**
+     * Get episodes for a TV series or specific season.
+     */
+    getEpisodes(seriesId?: string, seasonId?: string, options?: GetEpisodesOptions): Promise<ItemsResponse>;
+    /**
+     * General query for video items (movies, episodes, videos).
+     */
+    getVideos(options?: GetVideosOptions): Promise<ItemsResponse>;
+    /**
+     * Request media playback information for an item (sources, streams, play session).
+     */
+    getPlaybackInfo(itemId: string, options?: PlaybackInfoOptions): Promise<PlaybackInfoResponse>;
+    /**
+     * Get single item details by its Jellyfin ID.
+     */
+    getItem(itemId: string): Promise<BaseItemDto | null>;
+    /**
+     * Search Jellyfin library for songs, albums, artists, playlists, movies, or series.
+     */
+    search(query: string, options?: SearchOptions): Promise<ItemsResponse>;
+}
+
+declare class PlaylistsModule {
+    private http;
+    private getUserId;
+    constructor(http: HttpTransport, getUserId: () => string);
+    private requireUserId;
+    /**
+     * Get all playlists for the current user.
+     */
+    getPlaylists(): Promise<ItemsResponse>;
+    /**
+     * Get items belonging to a specific playlist.
+     */
+    getPlaylistItems(playlistId: string): Promise<ItemsResponse>;
+    /**
+     * Create a new playlist.
+     * Jellyfin 12 requires a JSON request body with CreatePlaylistDto.
+     * Falls back to legacy query parameters if server returns 400/415.
+     */
+    createPlaylist(options: CreatePlaylistOptions): Promise<string>;
+    /**
+     * Update playlist metadata (e.g. name).
+     * Jellyfin 12 removed POST /Playlists/{id}; item updates use POST /Items/{id},
+     * which is also supported across older Jellyfin versions.
+     */
+    updatePlaylist(playlistId: string, options: UpdatePlaylistOptions): Promise<void>;
+    /**
+     * Upload custom cover image for a playlist.
+     */
+    uploadPlaylistImage(playlistId: string, base64ImageString: string, mimeType?: string): Promise<void>;
+    /**
+     * Delete a playlist.
+     */
+    deletePlaylist(playlistId: string): Promise<void>;
+    /**
+     * Add tracks to an existing playlist.
+     */
+    addTracks(playlistId: string, trackIds: string | string[]): Promise<void>;
+    /**
+     * Remove a track from a playlist by playlist entry ID or track ID.
+     */
+    removeTrack(playlistId: string, entryIdOrTrackId: string): Promise<void>;
+    /**
+     * Remove a specific playlist item by its unique entry ID (PlaylistItemId).
+     * Especially recommended on Jellyfin 12+ when playlists contain duplicate tracks.
+     */
+    removePlaylistItem(playlistId: string, playlistItemId: string): Promise<void>;
+}
+
+declare class PlaybackModule {
+    private http;
+    constructor(http: HttpTransport);
+    /**
+     * Report to the Jellyfin server that playback has started for an item.
+     */
+    reportStart(itemId: string, positionTicks?: number): Promise<void>;
+    /**
+     * Report current playback progress to the Jellyfin server.
+     */
+    reportProgress(itemId: string, positionTicks?: number, isPaused?: boolean): Promise<void>;
+    /**
+     * Report that playback has stopped for an item.
+     */
+    reportStopped(itemId: string, positionTicks?: number): Promise<void>;
+}
+
+declare class MediaModule {
+    private http;
+    private getUserId;
+    constructor(http: HttpTransport, getUserId: () => string);
+    /**
+     * Constructs the URL for an item's image/artwork.
+     * If the item lacks images or server is not set, returns options.fallbackUrl or null.
+     */
+    getArtworkUrl(itemOrId: BaseItemDto | string | null | undefined, options?: ArtworkUrlOptions): string | null;
+    /**
+     * Constructs the audio stream URL using Jellyfin's universal audio endpoint.
+     * Transparently negotiates codecs (direct play or transcode to MP3/AAC as needed).
+     */
+    getAudioStreamUrl(itemId: string, options?: AudioStreamOptions): string;
+    /**
+     * Constructs the HLS master playlist URL for an audio stream.
+     */
+    getAudioHlsStreamUrl(itemId: string, options?: AudioHlsStreamOptions): string;
+    /**
+     * Constructs the progressive/universal video stream URL.
+     * Supports direct play (static=true) or on-the-fly transcoding with quality, audio, and subtitle options.
+     */
+    getVideoStreamUrl(itemId: string, options?: VideoStreamOptions): string;
+    /**
+     * Constructs the HLS master playlist URL for an adaptive video stream.
+     */
+    getVideoHlsStreamUrl(itemId: string, options?: VideoHlsStreamOptions): string;
+    /**
+     * Constructs the URL for streaming a specific subtitle track.
+     */
+    getSubtitleUrl(itemId: string, mediaSourceId: string, subtitleStreamIndex: number, options?: SubtitleUrlOptions): string;
+    /**
+     * Fetches subtitle content as raw text (e.g. WebVTT or SRT format).
+     */
+    getSubtitles(itemId: string, mediaSourceId: string, subtitleStreamIndex: number, options?: SubtitleUrlOptions): Promise<string>;
+    /**
+     * Extracts and normalizes subtitle streams from an item or media source into SubtitleTrackInfo objects with URLs.
+     */
+    getSubtitleTracks(itemOrMediaSource: BaseItemDto | MediaSourceInfo): SubtitleTrackInfo[];
+    /**
+     * Constructs the direct download URL for an original, unmodified media file on the Jellyfin server.
+     */
+    getDownloadUrl(itemId: string, options?: DownloadUrlOptions): string;
+    /**
+     * Downloads a media file as a Blob with optional progress monitoring.
+     */
+    downloadFile(itemId: string, options?: {
+        onProgress?: (progressFraction: number) => void;
+        useQueryToken?: boolean;
+    }): Promise<Blob>;
+    /**
+     * Returns authentication headers for media streaming requests (e.g., configuring hls.js xhrSetup).
+     * Crucial for Jellyfin 12+ servers where query-based auth (?api_key=) is disabled.
+     */
+    getStreamHeaders(): Record<string, string>;
+}
+
+declare class LyricsModule {
+    private http;
+    constructor(http: HttpTransport);
+    /**
+     * Fetch synced or unsynced lyrics for an audio item.
+     */
+    getLyrics(itemId: string): Promise<LyricsDto | null>;
+}
+
+declare class FavoritesModule {
+    private http;
+    private getUserId;
+    constructor(http: HttpTransport, getUserId: () => string);
+    private requireUserId;
+    /**
+     * Mark an item as favorite.
+     */
+    markFavorite(itemId: string): Promise<void>;
+    /**
+     * Unmark an item as favorite.
+     */
+    unmarkFavorite(itemId: string): Promise<void>;
+}
+
+interface DownloadRecord {
+    id: string;
+    name: string;
+    mediaType?: 'Audio' | 'Video' | string;
+    type?: string;
+    artists?: string;
+    album?: string;
+    albumId?: string;
+    seriesName?: string;
+    seriesId?: string;
+    seasonName?: string;
+    seasonId?: string;
+    artworkUrl: string | null;
+    size: number;
+    savedAt: number;
+    hasLyrics?: boolean;
+    parentId?: string;
+    parentName?: string;
+    parentType?: string;
+    parentArtworkUrl?: string;
+    parentOwner?: string;
+    parentCount?: number;
+    index?: number;
+    blob?: Blob;
+    mimeType?: string;
+}
+interface DownloadProgress {
+    completed: number;
+    total: number;
+    item: BaseItemDto;
+    track?: BaseItemDto;
+    res: {
+        ok: boolean;
+        size?: number;
+        removed?: boolean;
+        error?: string;
+    };
+}
+declare class OfflineStorageManager {
+    private media;
+    private dbName;
+    private dbVersion;
+    private storeName;
+    private dbPromise;
+    private objectUrlCache;
+    private downloadStatusCache;
+    constructor(media: MediaModule, dbName?: string, dbVersion?: number, storeName?: string);
+    isSupported(): boolean;
+    initDB(): Promise<IDBDatabase | null>;
+    private getItemKey;
+    private dispatchDownloadChanged;
+    private revokeObjectUrl;
+    getDownloadedRecord(id: string): Promise<DownloadRecord | null>;
+    isItemDownloaded(id: string): Promise<boolean>;
+    isItemDownloadedSync(id: string): boolean;
+    isTrackDownloaded(id: string): Promise<boolean>;
+    isTrackDownloadedSync(id: string): boolean;
+    getDownloadedBlobUrl(id: string): Promise<string | null>;
+    getDownloadedBlobUrlSync(id: string): string | null;
+    getAllDownloads(): Promise<DownloadRecord[]>;
+    warmOfflineCache(): Promise<void>;
+    saveDownloadRecord(record: DownloadRecord, blob: Blob): Promise<boolean>;
+    removeDownload(id: string): Promise<boolean>;
+    /**
+     * Downloads an audio or video item to offline storage.
+     * If already downloaded, toggles it off (removes it).
+     */
+    downloadItem(item: BaseItemDto, onProgress?: (progressFraction: number) => void, group?: {
+        id?: string;
+        name?: string;
+        type?: string;
+        artworkUrl?: string;
+        owner?: string;
+        count?: number;
+    } | null, index?: number, options?: DownloadItemOptions): Promise<{
+        ok: boolean;
+        size?: number;
+        removed?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Backward-compatible alias for downloadItem.
+     */
+    downloadTrack(track: BaseItemDto, onProgress?: (progressFraction: number) => void, group?: {
+        id?: string;
+        name?: string;
+        type?: string;
+        artworkUrl?: string;
+        owner?: string;
+        count?: number;
+    } | null, index?: number): Promise<{
+        ok: boolean;
+        size?: number;
+        removed?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Downloads multiple items with aggregated progress callbacks.
+     */
+    downloadItems(items: BaseItemDto[], onProgress?: (progress: DownloadProgress) => void, group?: {
+        id?: string;
+        name?: string;
+        type?: string;
+        artworkUrl?: string;
+        owner?: string;
+        count?: number;
+    } | null, options?: DownloadItemOptions): Promise<{
+        ok: boolean;
+        downloaded: number;
+        failed: number;
+        total: number;
+    }>;
+    /**
+     * Backward-compatible alias for downloadItems.
+     */
+    downloadTracks(tracks: BaseItemDto[], onProgress?: (progress: DownloadProgress) => void, group?: {
+        id?: string;
+        name?: string;
+        type?: string;
+        artworkUrl?: string;
+        owner?: string;
+        count?: number;
+    } | null): Promise<{
+        ok: boolean;
+        downloaded: number;
+        failed: number;
+        total: number;
+    }>;
+    removeDownloads(items: BaseItemDto[]): Promise<{
+        ok: boolean;
+        removed: number;
+    }>;
+    formatBytes(bytes: number): string;
+}
+
+interface CacheRecord<T = unknown> {
+    key: string;
+    data: T;
+    timestamp: number;
+}
+interface CacheAdapter {
+    get<T = unknown>(key: string): Promise<T | null> | T | null;
+    set<T = unknown>(key: string, data: T): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+declare class MemoryCacheAdapter implements CacheAdapter {
+    private cache;
+    get<T = unknown>(key: string): T | null;
+    set<T = unknown>(key: string, data: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+declare class IndexedDBCacheAdapter implements CacheAdapter {
+    private dbName;
+    private dbVersion;
+    private storeName;
+    private dbPromise;
+    constructor(dbName?: string, dbVersion?: number, storeName?: string);
+    private getDB;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, data: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Executes a Stale-While-Revalidate pattern using a CacheAdapter.
+ */
+declare function fetchWithCache<T>(cache: CacheAdapter, cacheKey: string, fetchFn: () => Promise<T>, onFreshData?: (data: T) => void): Promise<T>;
+
+type ClientEventType = 'unauthorized' | 'authenticated' | 'logout';
+type ClientEventListener = (...args: unknown[]) => void;
+declare class JellyfinClient {
+    readonly auth: AuthModule;
+    readonly system: SystemModule;
+    readonly library: LibraryModule;
+    readonly playlists: PlaylistsModule;
+    readonly playback: PlaybackModule;
+    readonly media: MediaModule;
+    readonly lyrics: LyricsModule;
+    readonly favorites: FavoritesModule;
+    readonly offline: OfflineStorageManager;
+    private http;
+    private storage;
+    private cache;
+    private clientInfo;
+    private eventListeners;
+    constructor(options?: JellyfinClientOptions);
+    get serverUrl(): string;
+    set serverUrl(url: string);
+    get accessToken(): string;
+    set accessToken(token: string);
+    get userId(): string;
+    set userId(id: string);
+    get serverVersion(): string | null;
+    set serverVersion(version: string | null);
+    /**
+     * Check whether the connected Jellyfin server is version 12.0 or higher.
+     */
+    isV12(): Promise<boolean>;
+    /**
+     * Query server and detect the server version via /System/Info/Public.
+     */
+    detectServerVersion(): Promise<string | null>;
+    get info(): ClientInfo;
+    setClientInfo(info: Partial<ClientInfo>): void;
+    getCache(): CacheAdapter;
+    setCache(cache: CacheAdapter): void;
+    getStorage(): StorageAdapter;
+    setStorage(storage: StorageAdapter): void;
+    on(event: ClientEventType, listener: ClientEventListener): () => void;
+    off(event: ClientEventType, listener: ClientEventListener): void;
+    emit(event: ClientEventType, ...args: unknown[]): void;
+    /**
+     * Authenticate with username and password, update client state, and emit 'authenticated'.
+     */
+    authenticate(username: string, password?: string): Promise<AuthenticationResult>;
+    /**
+     * Log out and clear tokens and session.
+     */
+    logout(): void;
+    /**
+     * Manually set authentication credentials.
+     */
+    setCredentials(credentials: {
+        serverUrl?: string;
+        accessToken: string;
+        userId: string;
+    }): void;
+}
+
+declare class MemoryStorage implements StorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+declare class LocalStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare function getDefaultStorage(): StorageAdapter;
+declare function generateDeviceId(): string;
+
+declare class JellyfinError extends Error {
+    constructor(message: string);
+}
+declare class JellyfinApiError extends JellyfinError {
+    readonly status: number;
+    readonly endpoint?: string;
+    constructor(message: string, status: number, endpoint?: string);
+}
+declare class JellyfinAuthError extends JellyfinApiError {
+    constructor(message?: string, status?: number, endpoint?: string);
+}
+
+export { AUDIO_QUALITY_PRESETS, type ArtworkUrlOptions, type AudioHlsStreamOptions, type AudioQualityOption, type AudioQualityPresetKey, type AudioStreamOptions, AuthModule, type AuthenticationResult, type BaseItemDto, type CacheAdapter, type CacheRecord, type ClientCapabilities, type ClientEventListener, type ClientEventType, type ClientInfo, type CreatePlaylistDto, type CreatePlaylistOptions, type DownloadItemOptions, type DownloadProgress, type DownloadRecord, type DownloadUrlOptions, FavoritesModule, type GetAlbumsOptions, type GetArtistsOptions, type GetEpisodesOptions, type GetMoviesOptions, type GetSeasonsOptions, type GetSeriesOptions, type GetSongsOptions, type GetVideosOptions, HttpTransport, IndexedDBCacheAdapter, type ItemsResponse, JellyfinApiError, JellyfinAuthError, JellyfinClient, type JellyfinClientOptions, JellyfinError, LibraryModule, LocalStorageAdapter, type LyricLine, type LyricsDto, LyricsModule, MediaModule, type MediaSourceInfo, type MediaStreamInfo, MemoryCacheAdapter, MemoryStorage, OfflineStorageManager, type PlaybackInfoOptions, type PlaybackInfoResponse, PlaybackModule, PlaylistsModule, type PublicSystemInfo, type RequestOptions, type SearchOptions, type StorageAdapter, type SubtitleTrackInfo, type SubtitleUrlOptions, type SystemInfo, SystemModule, type UpdatePlaylistOptions, type UserDto, type UserItemDataDto, VIDEO_QUALITY_PRESETS, type VideoHlsStreamOptions, type VideoQualityOption, type VideoQualityPresetKey, type VideoStreamOptions, buildAuthHeader, cleanUrl, fetchWithCache, formatBitrate, generateDeviceId, getAudioQualityList, getDefaultStorage, getVideoQualityList, isV12OrHigher, isVersionAtLeast, parseSemVer, resolveAudioQuality, resolveVideoQuality };