@ctrl/plex 3.9.2 → 3.10.0

package/README.md

@@ -84,31 +84,37 @@ export PLEX_USERNAME=email
 export PLEX_PASSWORD=password
 ```
 
-Claim server and setup test content (once)
+Setup test content (once)
 
 ```sh
-npm run claim-server && npm run add-media
+pnpm run add-media
 ```
 
 Run tests
 
 ```sh
-npm test
+pnpm test
 ```
 
 Post testing, remove plex server from account. Warning this is destructive. Do not use this on a real plex account.
 
 ```sh
-npm run test-cleanup
+pnpm run test-cleanup
 ```
 
-### Running tests locally (mostly for myself)
+### Running tests locally
+
+#### Step 1
 
 get a claim token from https://www.plex.tv/claim/
 export PLEX_CLAIM_TOKEN=claim-token
 
 Start plex container for testing. Replace `/Users/scooper/gh/plex` with the path to this repo's directory.
 
+#### Step 2
+
+Replace `/Users/scooper/gh/plex` with the path to this repo's directory.
+
 ```console
 docker run -d \
   --name=plex \

package/dist/src/audio.d.ts

@@ -1,4 +1,4 @@
-import { PartialPlexObject } from './base/partialPlexObject.js';
+import { Playable } from './base/playable.js';
 import { PlexObject } from './base/plexObject.js';
 import type { AlbumData, ArtistData, TrackData } from './audio.types.js';
 import { Chapter, Collection, Country, Field, Format, Genre, Guid, Image, Label, Media, Mood, Similar, Style, Subformat } from './media.js';
@@ -6,7 +6,7 @@ import type { PlexServer } from './server.js';
 /**
  * Base class for all audio objects including Artist, Album, and Track.
  */
-export declare class Audio extends PartialPlexObject {
+export declare class Audio extends Playable {
     /** Default metadata type for audio sync items. */
     static METADATA_TYPE: string;
     /** Hardcoded list type for filtering. */

package/dist/src/audio.js

@@ -1,11 +1,11 @@
 import { URLSearchParams } from 'url';
-import { PartialPlexObject } from './base/partialPlexObject.js';
+import { Playable } from './base/playable.js';
 import { fetchItem, fetchItems } from './baseFunctionality.js';
 import { Chapter, Collection, Country, Field, Format, Genre, Guid, Image, Label, Media, Mood, Similar, Style, Subformat, } from './media.js';
 /**
  * Base class for all audio objects including Artist, Album, and Track.
  */
-export class Audio extends PartialPlexObject {
+export class Audio extends Playable {
     /** Default metadata type for audio sync items. */
     static { this.METADATA_TYPE = 'track'; }
     /** Hardcoded list type for filtering. */
@@ -114,6 +114,8 @@ export class Audio extends PartialPlexObject {
         this.musicAnalysisVersion = isNaN(musicAnalysisVersionInt)
             ? undefined
             : musicAnalysisVersionInt;
+        this.playlistItemID = data.playlistItemID;
+        this.ratingKey = data.ratingKey;
         const ratingKeyInt = data.ratingKey ? parseInt(data.ratingKey, 10) : NaN;
         this.ratingKey = isNaN(ratingKeyInt) ? this.ratingKey : ratingKeyInt.toString();
         this.summary = data.summary;
@@ -383,7 +385,6 @@ export class Artist extends Audio {
             if (e.constructor.name === 'NotFound') {
                 return undefined;
             }
-            // eslint-disable-next-line @typescript-eslint/only-throw-error
             throw e;
         }
     }

package/dist/src/base/partialPlexObject.d.ts

@@ -100,7 +100,7 @@ export declare abstract class PartialPlexObject extends PlexObject {
      * @param maxresults Only return the specified number of results (optional).
      * @param mindate Min datetime to return results from.
      */
-    history(maxresults?: number, mindate?: Date): Promise<import("../server.types.js").HistoryMetadatum[]>;
+    history(maxresults?: number, mindate?: Date): Promise<import("../server.types.js").HistoryResult[]>;
     section(): Promise<Section>;
     /**
      * Delete a media element. This has to be enabled under settings > server > library in plex webui.

package/dist/src/index.d.ts

@@ -8,6 +8,7 @@ export * from './myplex.js';
 export * from './playlist.js';
 export * from './playqueue.js';
 export * from './server.js';
+export type { HistoryResult } from './server.types.js';
 export * from './video.js';
 export * from './audio.js';
 export { X_PLEX_IDENTIFIER } from './config.js';

package/dist/src/library.d.ts

@@ -5,7 +5,7 @@ import { Album, Artist, Track } from './audio.js';
 import type { CollectionData, LibraryRootResponse, Location, SectionsDirectory } from './library.types.js';
 import { Playlist } from './playlist.js';
 import { type Agent, type SEARCHTYPES } from './search.js';
-import type { SearchResult } from './search.types.js';
+import type { SearchResultContainer } from './search.types.js';
 import type { PlexServer } from './server.js';
 import { Movie, Show } from './video.js';
 export type Section = MovieSection | ShowSection | MusicSection;
@@ -26,7 +26,7 @@ export declare class Library {
      */
     sections(): Promise<Section[]>;
     section<T extends Section = Section>(title: string): Promise<T>;
-    sectionByID(sectionId: string | number): Promise<Section>;
+    sectionByID<T extends Section = Section>(sectionId: string | number): Promise<T>;
     /**
      * Simplified add for the most common options.
      *
@@ -468,9 +468,9 @@ export declare class Hub extends PlexObject {
     size: number;
     title: string;
     type: string;
-    Directory: SearchResult['Directory'];
-    Metadata: SearchResult['Metadata'];
-    protected _loadData(data: SearchResult): void;
+    Directory: SearchResultContainer['Directory'];
+    Metadata: SearchResultContainer['Metadata'];
+    protected _loadData(data: SearchResultContainer): void;
 }
 /**
  * Represents a Folder inside a library.

package/dist/src/library.js

@@ -26,7 +26,6 @@ export class Library {
         for (const elem of elems.MediaContainer.Directory) {
             for (const cls of [MovieSection, ShowSection, MusicSection]) {
                 if (cls.TYPE === elem.type) {
-                    // eslint-disable-next-line new-cap
                     const instance = new cls(this.server, elem, key);
                     sections.push(instance);
                 }

package/dist/src/playlist.d.ts

@@ -1,4 +1,5 @@
 import { Playable } from './base/playable.js';
+import { Album, Artist, Track } from './audio.js';
 import type { Section, SectionType } from './library.js';
 import type { PlaylistResponse } from './playlist.types.js';
 import type { PlexServer } from './server.js';
@@ -29,10 +30,32 @@ interface CreateSmartPlaylistOptions {
     filters?: Record<string, any>;
 }
 type CreatePlaylistOptions = CreateRegularPlaylistOptions | CreateSmartPlaylistOptions;
-type PlaylistContent = Episode | Movie;
+type PlaylistContent = Episode | Movie | Track | Album | Artist;
+export interface UpdatePlaylistOptions {
+    /** New title for the playlist */
+    title?: string;
+    /** New summary/description for the playlist */
+    summary?: string;
+}
 export declare class Playlist extends Playable {
     static TAG: string;
     static create(server: PlexServer, title: string, options: CreatePlaylistOptions): Promise<Playlist>;
+    /**
+     * Update a playlist's metadata by ratingKey without fetching the full playlist first.
+     *
+     * @param server - The Plex server instance
+     * @param ratingKey - The playlist's ratingKey
+     * @param options - Fields to update (title and/or summary)
+     *
+     * @example
+     * ```typescript
+     * await Playlist.update(server, '12345', {
+     *   title: 'My Updated Playlist',
+     *   summary: 'A new description'
+     * });
+     * ```
+     */
+    static update(server: PlexServer, ratingKey: string, options: UpdatePlaylistOptions): Promise<void>;
     /** Create a smart playlist. */
     private static _create;
     TYPE: string;
@@ -61,7 +84,7 @@ export declare class Playlist extends Playable {
      * @returns the item in the playlist that matches the specified title.
      */
     item(title: string): Promise<PlaylistContent | null>;
-    items(): Promise<PlaylistContent[]>;
+    items<T extends PlaylistContent>(): Promise<T[]>;
     /** Add items to a playlist. */
     addItems(items: PlaylistContent[]): Promise<void>;
     /** Remove an item from a playlist. */

package/dist/src/playlist.js

@@ -1,5 +1,6 @@
 import { URLSearchParams } from 'url';
 import { Playable } from './base/playable.js';
+import { Album, Artist, Track } from './audio.js';
 import { fetchItems } from './baseFunctionality.js';
 import { BadRequest, NotFound } from './exceptions.js';
 import { Episode, Movie } from './video.js';
@@ -12,8 +13,14 @@ function contentClass(data) {
             return Episode;
         case 'movie':
             return Movie;
+        case 'track':
+            return Track;
+        case 'album':
+            return Album;
+        case 'artist':
+            return Artist;
         default:
-            throw new Error('Media type not implemented');
+            throw new Error(`Media type '${data.type}' not implemented`);
     }
 }
 export class Playlist extends Playable {
@@ -31,6 +38,35 @@ export class Playlist extends Playable {
         }
         return this._create(server, title, options.items);
     }
+    /**
+     * Update a playlist's metadata by ratingKey without fetching the full playlist first.
+     *
+     * @param server - The Plex server instance
+     * @param ratingKey - The playlist's ratingKey
+     * @param options - Fields to update (title and/or summary)
+     *
+     * @example
+     * ```typescript
+     * await Playlist.update(server, '12345', {
+     *   title: 'My Updated Playlist',
+     *   summary: 'A new description'
+     * });
+     * ```
+     */
+    static async update(server, ratingKey, options) {
+        if (!options.title && !options.summary) {
+            return;
+        }
+        const params = new URLSearchParams();
+        if (options.title) {
+            params.set('title', options.title);
+        }
+        if (options.summary) {
+            params.set('summary', options.summary);
+        }
+        const key = `/playlists/${ratingKey}?${params.toString()}`;
+        await server.query(key, 'put');
+    }
     /** Create a smart playlist. */
     // private static _createSmart(server: PlexServer, title: string, options: CreatePlaylistOptions) {}
     static async _create(server, title, items) {
@@ -135,6 +171,7 @@ export class Playlist extends Playable {
         if (!playlistItem) {
             throw new NotFound(`Item with title "${item.title}" not found in the playlist`);
         }
+        // playlistItemID is added dynamically by Plex API for playlist items
         return playlistItem.playlistItemID;
     }
 }

package/dist/src/search.types.d.ts

@@ -6,7 +6,7 @@ export interface MatchSearchResult {
     year: number;
     lifespanEnded: boolean;
 }
-export interface SearchResult {
+export interface SearchResultContainer {
     title: string;
     type: string;
     hubIdentifier: string;
@@ -15,7 +15,7 @@ export interface SearchResult {
     more: boolean;
     style: string;
     Directory?: Directory[];
-    Metadata?: Metadatum[];
+    Metadata?: SearchResult[];
 }
 export interface Directory {
     key: string;
@@ -34,7 +34,7 @@ export interface Directory {
     count: number;
     thumb?: string;
 }
-interface Metadatum {
+interface SearchResult {
     librarySectionTitle: string;
     ratingKey: string;
     key: string;

package/dist/src/server.d.ts

@@ -8,7 +8,7 @@ import type { Playlist } from './playlist.js';
 import { PlayQueue } from './playqueue.js';
 import type { CreatePlayQueueOptions } from './playqueue.types.js';
 import { Agent, SEARCHTYPES } from './search.js';
-import type { HistoryMetadatum } from './server.types.js';
+import type { HistoryResult } from './server.types.js';
 import { Settings } from './settings.js';
 /**
  * This is the main entry point to interacting with a Plex server. It allows you to
@@ -190,7 +190,7 @@ export declare class PlexServer {
      * @param accountId request history for a specific account ID.
      * @param librarySectionId request history for a specific library section ID.
      */
-    history(maxresults?: number, mindate?: Date, ratingKey?: number | string, accountId?: number | string, librarySectionId?: number | string): Promise<HistoryMetadatum[]>;
+    history(maxresults?: number, mindate?: Date, ratingKey?: number | string, accountId?: number | string, librarySectionId?: number | string): Promise<HistoryResult[]>;
     settings(): Promise<Settings>;
     /**
      * Creates and returns a new PlayQueue.

package/dist/src/server.js

@@ -143,7 +143,7 @@ export class PlexServer {
             args.librarySectionID = librarySectionId.toString();
         }
         if (mindate !== undefined) {
-            args['viewedAt>'] = mindate.getTime().toString();
+            args['viewedAt>'] = Math.floor(mindate.getTime() / 1000).toString();
         }
         args['X-Plex-Container-Start'] = '0';
         args['X-Plex-Container-Size'] = Math.min(X_PLEX_CONTAINER_SIZE, maxresults).toString();
@@ -151,14 +151,18 @@ export class PlexServer {
         let key = '/status/sessions/history/all?' + new URLSearchParams(args).toString();
         let raw = await this.query(key);
         const totalResults = raw.MediaContainer.totalSize;
-        results = results.concat(raw.MediaContainer.Metadata);
+        // Filter out null/undefined items from the metadata
+        const validMetadata = raw.MediaContainer.Metadata?.filter(Boolean) ?? [];
+        results = results.concat(validMetadata);
         while (results.length <= totalResults &&
             X_PLEX_CONTAINER_SIZE === raw.MediaContainer.size &&
             maxresults > results.length) {
             args['X-Plex-Container-Start'] = (Number(args['X-Plex-Container-Start']) + Number(args['X-Plex-Container-Size'])).toString();
             key = '/status/sessions/history/all?' + new URLSearchParams(args).toString();
             raw = await this.query(key);
-            results = results.concat(raw.MediaContainer.Metadata);
+            // Filter out null/undefined items from the metadata
+            const validMetadata = raw.MediaContainer.Metadata?.filter(item => item != null) ?? [];
+            results = results.concat(validMetadata);
         }
         return results;
     }

package/dist/src/server.types.d.ts

@@ -65,10 +65,12 @@ export interface HistoryMediaContainer {
     size: number;
     totalSize: number;
     offset: number;
-    Metadata: HistoryMetadatum[];
+    Metadata?: Array<HistoryResult | null | undefined>;
 }
-export interface HistoryMetadatum {
+export interface HistoryResult {
     key: string;
+    ratingKey: string;
+    historyKey: string;
     parentKey?: string;
     grandparentKey?: string;
     title: string;
@@ -84,6 +86,7 @@ export interface HistoryMetadatum {
     viewedAt: number;
     accountID: number;
     deviceID: number;
+    librarySectionID: string;
 }
 export interface PlaylistMediaContainer {
     size: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl/plex",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "description": "plex api client in typescript using ofetch",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "publishConfig": {
@@ -41,25 +41,25 @@
     "xml2js": "^0.6.2"
   },
   "devDependencies": {
-    "@ctrl/oxlint-config": "1.2.6",
+    "@ctrl/oxlint-config": "1.2.8",
     "@ctrl/video-filename-parser": "5.4.1",
     "@sindresorhus/tsconfig": "8.0.1",
     "@trivago/prettier-plugin-sort-imports": "5.2.2",
-    "@types/node": "24.5.2",
+    "@types/node": "24.7.2",
     "@types/ws": "8.18.1",
     "@types/xml2js": "0.4.14",
     "@types/yargs": "17.0.33",
     "@vitest/coverage-v8": "3.2.4",
     "execa": "9.6.0",
-    "globby": "14.1.0",
+    "globby": "15.0.0",
     "make-dir": "5.1.0",
     "ora": "9.0.0",
-    "oxlint": "1.18.0",
-    "p-retry": "7.0.0",
+    "oxlint": "1.22.0",
+    "p-retry": "7.1.0",
     "prettier": "3.6.2",
     "tsx": "4.20.6",
-    "typedoc": "0.28.13",
-    "typescript": "5.9.2",
+    "typedoc": "0.28.14",
+    "typescript": "5.9.3",
     "vitest": "3.2.4",
     "yargs": "18.0.0"
   },
@@ -91,5 +91,5 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@10.17.1"
+  "packageManager": "pnpm@10.18.2"
 }