@francofantomius/jellyfin 0.1.0 → 0.2.0

package/README.md

@@ -5,6 +5,9 @@ A modern, lightweight, modular, and type-safe Jellyfin SDK for Node.js and the B
 [![npm version](https://img.shields.io/npm/v/@francofantomius/jellyfin.svg)](https://www.npmjs.com/package/@francofantomius/jellyfin)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+**Current Version: `v0.2.0`** (THE PROJECT IS BEING ACTIVELY DEVELOPED. WAIT FOR VERSION 0.5.0 TO USE IT)
+
+
 ---
 
 ## Features
@@ -15,12 +18,17 @@ A modern, lightweight, modular, and type-safe Jellyfin SDK for Node.js and the B
 - **Clean modular architecture**:
   - `client.auth` - Server authentication, user profiles, capabilities reporting.
   - `client.library` - Browse music and video libraries (movies, series, seasons, episodes, videos, search, playback info).
+  - `client.search` - Dedicated universal search with granular item type, genre, year, and library view scoping.
   - `client.media` - Universal audio and video stream URLs, HLS playlists, subtitles, direct downloads, and responsive artwork.
   - `client.playlists` - Create, edit, delete playlists, manage tracks, and upload cover images.
   - `client.playback` - Report playback start, progress, and stop to Jellyfin for scrobbling and playback sync.
   - `client.lyrics` - Fetch synced or unsynced song lyrics.
   - `client.favorites` - Toggle favorite items.
   - `client.offline` - Browser IndexedDB media download manager for offline audio and video playback.
+  - `client.resume` - Continue watching / resume items querying (`/UserItems/Resume`).
+  - `client.nextUp` - Next unplayed TV show episodes (`/Shows/NextUp`).
+  - `client.latest` - Recently added media (movies, episodes, albums) (`/Users/{userId}/Items/Latest`).
+  - `client.transcode` - Teardown active transcoding sessions (`/Videos/ActiveEncodings`).
 - **Quality Settings & Presets**: Standard video (4K, 1080p, 720p, 480p, 360p, direct) and audio (320k, 256k, 192k, 128k, direct) presets and resolution utilities.
 - **Subtitles**: Direct VTT/SRT subtitle streaming URLs, raw text fetching, and automated track extraction from media metadata.
 - **Direct Downloads**: Server file download URLs, progress-tracked file downloads, and offline caching.
@@ -280,6 +288,67 @@ client.on('unauthorized', () => {
 
 ---
 
+### 11. Dashboard, Continue Watching & Next Up
+
+```typescript
+// Fetch in-progress items for Continue Watching carousels
+const resume = await client.resume.getResumeItems({
+  limit: 10,
+  mediaTypes: ['Video']
+});
+console.log('Continue watching:', resume.Items);
+
+// Fetch the next unplayed episodes for followed series
+const nextUp = await client.nextUp.getNextUp({
+  limit: 12,
+  enableTotalRecordCount: true
+});
+console.log('Next up episodes:', nextUp.Items);
+
+// Query recently added media across libraries or specific types
+const latestMovies = await client.latest.getLatestMovies({ limit: 10 });
+const latestEpisodes = await client.latest.getLatestEpisodes({ limit: 10 });
+const latestAlbums = await client.latest.getLatestAlbums({ limit: 10 });
+```
+
+---
+
+### 12. Active Transcode Session Teardown
+
+```typescript
+const playSessionId = 'playback-session-id';
+
+// Teardown active server transcoding to terminate lingering FFmpeg processes
+await client.transcode.stopActiveEncoding(playSessionId);
+
+// Or automatically teardown during playback stop reporting:
+await client.playback.reportStopped(movieId, currentTicks, { playSessionId });
+```
+
+---
+
+### 13. Universal & Scoped Search
+
+```typescript
+// Universal search across all items
+const results = await client.search.search('Inception', {
+  includeItemTypes: ['Movie', 'Series'],
+  genres: ['Sci-Fi'],
+  limit: 20
+});
+
+// Search within a specific library folder
+const musicResults = await client.search.searchInLibrary('music-library-id', 'Queen');
+
+// Media-specific search shortcuts
+const songs = await client.search.searchSongs('Yellow');
+const albums = await client.search.searchAlbums('Parachutes');
+const movies = await client.search.searchMovies('Interstellar');
+const series = await client.search.searchSeries('Breaking Bad');
+```
+
+---
+
 ## License
 
 MIT © [Franco Fantomius](https://github.com/francofantomius)

package/dist/index.cjs

@@ -702,22 +702,41 @@ var LibraryModule = class {
     if (!query || !query.trim()) {
       return { Items: [], TotalRecordCount: 0 };
     }
-    const userId = this.requireUserId();
+    const userId = options.userId || this.requireUserId();
     const {
       limit = 30,
       startIndex = 0,
-      includeItemTypes = "Audio,MusicAlbum,MusicArtist,Playlist,Movie,Series,Episode"
+      parentId,
+      includeItemTypes = "Audio,MusicAlbum,MusicArtist,Playlist,Movie,Series,Episode",
+      mediaTypes,
+      genres,
+      years,
+      isFavorite,
+      sortBy,
+      sortOrder,
+      fields = COMMON_ITEM_FIELDS,
+      recursive = true
     } = options;
-    return await this.http.request(`/Users/${userId}/Items`, {
-      params: {
-        SearchTerm: query.trim(),
-        IncludeItemTypes: includeItemTypes,
-        Limit: limit,
-        StartIndex: startIndex,
-        Recursive: true,
-        Fields: COMMON_ITEM_FIELDS
-      }
-    });
+    const params = {
+      SearchTerm: query.trim(),
+      Limit: limit,
+      StartIndex: startIndex,
+      Recursive: recursive,
+      Fields: fields
+    };
+    if (parentId) params.ParentId = parentId;
+    if (includeItemTypes) {
+      params.IncludeItemTypes = Array.isArray(includeItemTypes) ? includeItemTypes.join(",") : includeItemTypes;
+    }
+    if (mediaTypes) {
+      params.MediaTypes = Array.isArray(mediaTypes) ? mediaTypes.join(",") : mediaTypes;
+    }
+    if (genres && genres.length > 0) params.Genres = genres.join("|");
+    if (years && years.length > 0) params.Years = years.join(",");
+    if (isFavorite) params.Filters = "IsFavorite";
+    if (sortBy) params.SortBy = sortBy;
+    if (sortOrder) params.SortOrder = sortOrder;
+    return await this.http.request(`/Users/${userId}/Items`, { params });
   }
 };
 
@@ -960,8 +979,9 @@ var PlaybackModule = class {
   }
   /**
    * Report that playback has stopped for an item.
+   * Optionally teardown active transcoding session if playSessionId is provided.
    */
-  async reportStopped(itemId, positionTicks = 0) {
+  async reportStopped(itemId, positionTicks = 0, options) {
     if (!itemId || !this.http.getToken()) return;
     try {
       await this.http.request("/Sessions/Playing/Stopped", {
@@ -971,6 +991,20 @@ var PlaybackModule = class {
           PositionTicks: positionTicks
         }
       });
+      if (options?.playSessionId) {
+        const deviceId = this.http.getClientInfo()?.deviceId;
+        if (deviceId) {
+          await this.http.request("/Videos/ActiveEncodings", {
+            method: "DELETE",
+            params: {
+              DeviceId: deviceId,
+              PlaySessionId: options.playSessionId
+            }
+          }).catch((err) => {
+            console.warn("[Jellyfin SDK] Teardown active encoding error:", err);
+          });
+        }
+      }
     } catch (e) {
       console.warn("[Jellyfin SDK] Stop playback report error:", e);
     }
@@ -1858,6 +1892,333 @@ var OfflineStorageManager = class {
   }
 };
 
+// src/resume.ts
+var RESUME_ITEM_FIELDS = "PrimaryImageAspectRatio,PrimaryImageTag,ImageTags,BackdropImageTags,AlbumPrimaryImageTag,AlbumId,AudioInfo,MediaSources,Chapters,HasLyrics,Overview,Genres,Studios,ProductionYear,OfficialRating,CommunityRating,CriticRating,PremiereDate,RunTimeTicks,IndexNumber,ParentIndexNumber,SeriesName,SeriesId,SeasonId,SeasonName,UserData";
+var ResumeModule = class {
+  http;
+  getUserId;
+  constructor(http, getUserId) {
+    this.http = http;
+    this.getUserId = getUserId;
+  }
+  resolveUserId(explicitUserId) {
+    const userId = explicitUserId || this.getUserId();
+    if (!userId) {
+      throw new JellyfinError("User ID is required for resume requests. Please authenticate or provide a userId.");
+    }
+    return userId;
+  }
+  /**
+   * Fetch items currently in-progress for the user via /UserItems/Resume.
+   */
+  async getResumeItems(options = {}) {
+    const userId = this.resolveUserId(options.userId);
+    const {
+      limit = 20,
+      startIndex = 0,
+      parentId,
+      mediaTypes,
+      enableImages,
+      enableUserData,
+      imageTypeLimit,
+      enableImageTypes,
+      fields = RESUME_ITEM_FIELDS
+    } = options;
+    const params = {
+      UserId: userId,
+      Limit: limit,
+      StartIndex: startIndex,
+      Recursive: true,
+      Fields: fields
+    };
+    if (parentId) params.ParentId = parentId;
+    if (mediaTypes && mediaTypes.length > 0) params.MediaTypes = mediaTypes.join(",");
+    if (enableImages !== void 0) params.EnableImages = enableImages;
+    if (enableUserData !== void 0) params.EnableUserData = enableUserData;
+    if (imageTypeLimit !== void 0) params.ImageTypeLimit = imageTypeLimit;
+    if (enableImageTypes && enableImageTypes.length > 0) params.EnableImageTypes = enableImageTypes.join(",");
+    return await this.http.request("/UserItems/Resume", { params });
+  }
+  /**
+   * Convenience alias for getResumeItems.
+   */
+  async getItems(options = {}) {
+    return await this.getResumeItems(options);
+  }
+};
+
+// src/next-up.ts
+var NEXT_UP_FIELDS = "PrimaryImageAspectRatio,PrimaryImageTag,ImageTags,BackdropImageTags,AlbumPrimaryImageTag,AudioInfo,MediaSources,Chapters,Overview,Genres,ProductionYear,PremiereDate,RunTimeTicks,IndexNumber,ParentIndexNumber,SeriesName,SeriesId,SeasonId,SeasonName,UserData";
+var NextUpModule = class {
+  http;
+  getUserId;
+  constructor(http, getUserId) {
+    this.http = http;
+    this.getUserId = getUserId;
+  }
+  resolveUserId(explicitUserId) {
+    const userId = explicitUserId || this.getUserId();
+    if (!userId) {
+      throw new JellyfinError("User ID is required for next up requests. Please authenticate or provide a userId.");
+    }
+    return userId;
+  }
+  /**
+   * Fetch the next unplayed episodes for followed series via /Shows/NextUp.
+   */
+  async getNextUp(options = {}) {
+    const userId = this.resolveUserId(options.userId);
+    const {
+      limit = 24,
+      startIndex = 0,
+      parentId,
+      seriesId,
+      fields = NEXT_UP_FIELDS,
+      enableImages,
+      enableUserData,
+      enableTotalRecordCount,
+      imageTypeLimit,
+      enableImageTypes,
+      disableFirstEpisode,
+      nextUpDateCutoff
+    } = options;
+    const params = {
+      UserId: userId,
+      Limit: limit,
+      StartIndex: startIndex,
+      Fields: fields
+    };
+    if (parentId) params.ParentId = parentId;
+    if (seriesId) params.SeriesId = seriesId;
+    if (enableImages !== void 0) params.EnableImages = enableImages;
+    if (enableUserData !== void 0) params.EnableUserData = enableUserData;
+    if (enableTotalRecordCount !== void 0) params.EnableTotalRecordCount = enableTotalRecordCount;
+    if (imageTypeLimit !== void 0) params.ImageTypeLimit = imageTypeLimit;
+    if (enableImageTypes && enableImageTypes.length > 0) params.EnableImageTypes = enableImageTypes.join(",");
+    if (disableFirstEpisode !== void 0) params.DisableFirstEpisode = disableFirstEpisode;
+    if (nextUpDateCutoff) params.NextUpDateCutoff = nextUpDateCutoff;
+    return await this.http.request("/Shows/NextUp", { params });
+  }
+  /**
+   * Convenience alias for getNextUp.
+   */
+  async getEpisodes(options = {}) {
+    return await this.getNextUp(options);
+  }
+};
+
+// src/latest.ts
+var LATEST_ITEM_FIELDS = "PrimaryImageAspectRatio,PrimaryImageTag,ImageTags,BackdropImageTags,AlbumPrimaryImageTag,AlbumId,AudioInfo,MediaSources,Chapters,Overview,Genres,Studios,ProductionYear,PremiereDate,RunTimeTicks,IndexNumber,ParentIndexNumber,SeriesName,SeriesId,SeasonId,SeasonName,UserData";
+var LatestModule = class {
+  http;
+  getUserId;
+  constructor(http, getUserId) {
+    this.http = http;
+    this.getUserId = getUserId;
+  }
+  resolveUserId(explicitUserId) {
+    const userId = explicitUserId || this.getUserId();
+    if (!userId) {
+      throw new JellyfinError("User ID is required for latest media requests. Please authenticate or provide a userId.");
+    }
+    return userId;
+  }
+  /**
+   * Fetch recently added media items for the user via /Users/{userId}/Items/Latest.
+   */
+  async getLatest(options = {}) {
+    const userId = this.resolveUserId(options.userId);
+    const {
+      parentId,
+      limit = 20,
+      fields = LATEST_ITEM_FIELDS,
+      includeItemTypes,
+      isPlayed,
+      enableImages,
+      imageTypeLimit,
+      enableImageTypes,
+      groupItems
+    } = options;
+    const params = {
+      Limit: limit,
+      Fields: fields
+    };
+    if (parentId) params.ParentId = parentId;
+    if (includeItemTypes && includeItemTypes.length > 0) {
+      params.IncludeItemTypes = includeItemTypes.join(",");
+    }
+    if (isPlayed !== void 0) params.IsPlayed = isPlayed;
+    if (enableImages !== void 0) params.EnableImages = enableImages;
+    if (imageTypeLimit !== void 0) params.ImageTypeLimit = imageTypeLimit;
+    if (enableImageTypes && enableImageTypes.length > 0) {
+      params.EnableImageTypes = enableImageTypes.join(",");
+    }
+    if (groupItems !== void 0) params.GroupItems = groupItems;
+    const result = await this.http.request(`/Users/${userId}/Items/Latest`, { params });
+    return Array.isArray(result) ? result : [];
+  }
+  /**
+   * Convenience helper to fetch recently added movies.
+   */
+  async getLatestMovies(options = {}) {
+    return await this.getLatest({ ...options, includeItemTypes: ["Movie"] });
+  }
+  /**
+   * Convenience helper to fetch recently added TV episodes.
+   */
+  async getLatestEpisodes(options = {}) {
+    return await this.getLatest({ ...options, includeItemTypes: ["Episode"] });
+  }
+  /**
+   * Convenience helper to fetch recently added music albums.
+   */
+  async getLatestAlbums(options = {}) {
+    return await this.getLatest({ ...options, includeItemTypes: ["MusicAlbum"] });
+  }
+};
+
+// src/transcode.ts
+var TranscodeModule = class {
+  http;
+  getDeviceId;
+  constructor(http, getDeviceId) {
+    this.http = http;
+    this.getDeviceId = getDeviceId;
+  }
+  /**
+   * Explicitly stop an active server transcoding session via DELETE /Videos/ActiveEncodings.
+   * This terminates lingering FFmpeg processes on the Jellyfin server.
+   *
+   * @param playSessionId The unique playback session ID.
+   * @param deviceId The client device ID (defaults to configured client device ID).
+   */
+  async stopActiveEncoding(playSessionId, deviceId) {
+    if (!playSessionId) {
+      throw new JellyfinError("playSessionId is required to stop an active encoding session.");
+    }
+    const resolvedDeviceId = deviceId || this.getDeviceId();
+    if (!resolvedDeviceId) {
+      throw new JellyfinError("deviceId is required to stop an active encoding session.");
+    }
+    await this.http.request("/Videos/ActiveEncodings", {
+      method: "DELETE",
+      params: {
+        DeviceId: resolvedDeviceId,
+        PlaySessionId: playSessionId
+      }
+    });
+  }
+  /**
+   * Convenience alias for stopActiveEncoding.
+   */
+  async stop(playSessionId, deviceId) {
+    return await this.stopActiveEncoding(playSessionId, deviceId);
+  }
+};
+
+// src/search.ts
+var COMMON_SEARCH_FIELDS = "PrimaryImageAspectRatio,PrimaryImageTag,ImageTags,BackdropImageTags,AlbumPrimaryImageTag,AlbumId,AudioInfo,MediaSources,Chapters,HasLyrics,Overview,Genres,Studios,ProductionYear,OfficialRating,CommunityRating,CriticRating,PremiereDate,RunTimeTicks,IndexNumber,ParentIndexNumber,SeriesName,SeriesId,SeasonId,SeasonName,UserData";
+var SearchModule = class {
+  http;
+  getUserId;
+  constructor(http, getUserId) {
+    this.http = http;
+    this.getUserId = getUserId;
+  }
+  resolveUserId(explicitUserId) {
+    const userId = explicitUserId || this.getUserId();
+    if (!userId) {
+      throw new JellyfinError("User ID is required for search requests. Please authenticate or provide a userId.");
+    }
+    return userId;
+  }
+  /**
+   * Universal search across Jellyfin items with comprehensive filters.
+   */
+  async search(query, options = {}) {
+    if (!query || !query.trim()) {
+      return { Items: [], TotalRecordCount: 0 };
+    }
+    const userId = this.resolveUserId(options.userId);
+    const {
+      limit = 30,
+      startIndex = 0,
+      parentId,
+      includeItemTypes = "Audio,MusicAlbum,MusicArtist,Playlist,Movie,Series,Episode",
+      mediaTypes,
+      genres,
+      years,
+      isFavorite,
+      sortBy,
+      sortOrder,
+      fields = COMMON_SEARCH_FIELDS,
+      recursive = true
+    } = options;
+    const params = {
+      SearchTerm: query.trim(),
+      Limit: limit,
+      StartIndex: startIndex,
+      Recursive: recursive,
+      Fields: fields
+    };
+    if (parentId) params.ParentId = parentId;
+    if (includeItemTypes) {
+      params.IncludeItemTypes = Array.isArray(includeItemTypes) ? includeItemTypes.join(",") : includeItemTypes;
+    }
+    if (mediaTypes) {
+      params.MediaTypes = Array.isArray(mediaTypes) ? mediaTypes.join(",") : mediaTypes;
+    }
+    if (genres && genres.length > 0) params.Genres = genres.join("|");
+    if (years && years.length > 0) params.Years = years.join(",");
+    if (isFavorite) params.Filters = "IsFavorite";
+    if (sortBy) params.SortBy = sortBy;
+    if (sortOrder) params.SortOrder = sortOrder;
+    return await this.http.request(`/Users/${userId}/Items`, { params });
+  }
+  /**
+   * Search specifically within a specific library or parent folder.
+   */
+  async searchInLibrary(parentId, query, options = {}) {
+    return await this.search(query, { ...options, parentId });
+  }
+  /**
+   * Convenience helper to search audio tracks / songs.
+   */
+  async searchSongs(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "Audio" });
+  }
+  /**
+   * Convenience helper to search music albums.
+   */
+  async searchAlbums(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "MusicAlbum" });
+  }
+  /**
+   * Convenience helper to search music artists.
+   */
+  async searchArtists(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "MusicArtist" });
+  }
+  /**
+   * Convenience helper to search movies.
+   */
+  async searchMovies(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "Movie" });
+  }
+  /**
+   * Convenience helper to search TV series.
+   */
+  async searchSeries(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "Series" });
+  }
+  /**
+   * Convenience helper to search TV episodes.
+   */
+  async searchEpisodes(query, options = {}) {
+    return await this.search(query, { ...options, includeItemTypes: "Episode" });
+  }
+};
+
 // src/cache.ts
 var MemoryCacheAdapter = class {
   cache = /* @__PURE__ */ new Map();
@@ -2049,12 +2410,17 @@ var JellyfinClient = class {
   auth;
   system;
   library;
+  search;
   playlists;
   playback;
   media;
   lyrics;
   favorites;
   offline;
+  resume;
+  nextUp;
+  latest;
+  transcode;
   http;
   storage;
   cache;
@@ -2065,7 +2431,7 @@ var JellyfinClient = class {
     this.cache = new MemoryCacheAdapter();
     this.clientInfo = {
       name: options.clientInfo?.name || "@francofantomius/jellyfin",
-      version: options.clientInfo?.version || "0.1.0",
+      version: options.clientInfo?.version || "0.2.0",
       device: options.clientInfo?.device || (typeof window !== "undefined" ? "Web Browser" : "Node.js"),
       deviceId: options.clientInfo?.deviceId || generateDeviceId()
     };
@@ -2082,18 +2448,24 @@ var JellyfinClient = class {
       }
     });
     const getUserId = () => this.auth.getUserId();
+    const getDeviceId = () => this.clientInfo.deviceId;
     this.system = new SystemModule(this.http, {
       serverVersion: options.serverVersion,
       targetVersion: options.targetVersion
     });
     this.auth = new AuthModule(this.http, options.userId || "");
     this.library = new LibraryModule(this.http, getUserId);
+    this.search = new SearchModule(this.http, getUserId);
     this.playlists = new PlaylistsModule(this.http, getUserId);
     this.playback = new PlaybackModule(this.http);
     this.media = new MediaModule(this.http, getUserId);
     this.lyrics = new LyricsModule(this.http);
     this.favorites = new FavoritesModule(this.http, getUserId);
     this.offline = new OfflineStorageManager(this.media);
+    this.resume = new ResumeModule(this.http, getUserId);
+    this.nextUp = new NextUpModule(this.http, getUserId);
+    this.latest = new LatestModule(this.http, getUserId);
+    this.transcode = new TranscodeModule(this.http, getDeviceId);
   }
   // --- Configuration Getters & Setters ---
   get serverUrl() {
@@ -2212,6 +2584,7 @@ var JellyfinClient = class {
 
 exports.AUDIO_QUALITY_PRESETS = AUDIO_QUALITY_PRESETS;
 exports.AuthModule = AuthModule;
+exports.COMMON_SEARCH_FIELDS = COMMON_SEARCH_FIELDS;
 exports.FavoritesModule = FavoritesModule;
 exports.HttpTransport = HttpTransport;
 exports.IndexedDBCacheAdapter = IndexedDBCacheAdapter;
@@ -2219,16 +2592,21 @@ exports.JellyfinApiError = JellyfinApiError;
 exports.JellyfinAuthError = JellyfinAuthError;
 exports.JellyfinClient = JellyfinClient;
 exports.JellyfinError = JellyfinError;
+exports.LatestModule = LatestModule;
 exports.LibraryModule = LibraryModule;
 exports.LocalStorageAdapter = LocalStorageAdapter;
 exports.LyricsModule = LyricsModule;
 exports.MediaModule = MediaModule;
 exports.MemoryCacheAdapter = MemoryCacheAdapter;
 exports.MemoryStorage = MemoryStorage;
+exports.NextUpModule = NextUpModule;
 exports.OfflineStorageManager = OfflineStorageManager;
 exports.PlaybackModule = PlaybackModule;
 exports.PlaylistsModule = PlaylistsModule;
+exports.ResumeModule = ResumeModule;
+exports.SearchModule = SearchModule;
 exports.SystemModule = SystemModule;
+exports.TranscodeModule = TranscodeModule;
 exports.VIDEO_QUALITY_PRESETS = VIDEO_QUALITY_PRESETS;
 exports.buildAuthHeader = buildAuthHeader;
 exports.cleanUrl = cleanUrl;