@ctrl/plex 3.9.2 → 3.11.0

package/dist/src/media.js

@@ -5,6 +5,7 @@ import { PlexObject } from './base/plexObject.js';
  * the construct used for things such as Country, Director, Genre, etc.
  */
 class MediaTag extends PlexObject {
+    static TAG;
     // async items(): Promise<any[]> {
     //   if (!this.key) {
     //     throw new Error(`Key is not defined for this tag: ${this.tag}`);
@@ -19,7 +20,7 @@ class MediaTag extends PlexObject {
     }
 }
 export class Media extends PlexObject {
-    static { this.TAG = 'Media'; }
+    static TAG = 'Media';
     _loadData(data) {
         this.aspectRatio = data.aspectRatio;
         this.audioChannels = data.audioChannels;
@@ -39,7 +40,7 @@ export class Media extends PlexObject {
     }
 }
 export class MediaPart extends PlexObject {
-    static { this.TAG = 'Part'; }
+    static TAG = 'Part';
     /**
      * Set the selected {@link AudioStream} for this MediaPart.
      * @param stream Audio stream or stream ID to set as selected.
@@ -97,7 +98,7 @@ export class MediaPart extends PlexObject {
     }
 }
 export class MediaPartStream extends PlexObject {
-    static { this.TAG = 'Stream'; }
+    static TAG = 'Stream';
     _loadData(data) {
         this.id = data.id;
         this.codec = data.codec;
@@ -112,8 +113,8 @@ export class MediaPartStream extends PlexObject {
  * Represents a single Subtitle stream within a {@link MediaPart}.
  */
 export class SubtitleStream extends MediaPartStream {
-    static { this.TAG = 'Stream'; }
-    static { this.STREAMTYPE = 3; }
+    static TAG = 'Stream';
+    static STREAMTYPE = 3;
     /**
      * Sets this subtitle stream as the selected subtitle stream.
      * Alias for `MediaPart.setSelectedSubtitleStream`.
@@ -145,8 +146,8 @@ export class SubtitleStream extends MediaPartStream {
  * Represents a single Lyric stream within a {@link MediaPart}.
  */
 export class LyricStream extends MediaPartStream {
-    static { this.TAG = 'Stream'; }
-    static { this.STREAMTYPE = 4; }
+    static TAG = 'Stream';
+    static STREAMTYPE = 4;
     _loadData(data) {
         super._loadData(data);
         this.format = data.format;
@@ -159,72 +160,48 @@ export class LyricStream extends MediaPartStream {
  * Represents a single Role (actor/actress) media tag.
  */
 export class Role extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'role';
-    }
-    static { this.TAG = 'Role'; }
+    static TAG = 'Role';
+    FILTER = 'role';
 }
 /**
  * Represents a single Genre media tag.
  */
 export class Genre extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'genre';
-    }
-    static { this.TAG = 'Genre'; }
+    static TAG = 'Genre';
+    FILTER = 'genre';
 }
 /**
  * Represents a single Country media tag.
  */
 export class Country extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'country';
-    }
-    static { this.TAG = 'Country'; }
+    static TAG = 'Country';
+    FILTER = 'country';
 }
 /**
  * Represents a single Writer media tag.
  */
 export class Writer extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'writer';
-    }
-    static { this.TAG = 'Writer'; }
+    static TAG = 'Writer';
+    FILTER = 'writer';
 }
 /**
  * Represents a single Director media tag.
  */
 export class Director extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'director';
-    }
-    static { this.TAG = 'Director'; }
+    static TAG = 'Director';
+    FILTER = 'director';
 }
 export class Similar extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'similar';
-    }
-    static { this.TAG = 'Similar'; }
+    static TAG = 'Similar';
+    FILTER = 'similar';
 }
 export class Producer extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'producer';
-    }
-    static { this.TAG = 'Producer'; }
+    static TAG = 'Producer';
+    FILTER = 'producer';
 }
 export class Marker extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'marker';
-    }
-    static { this.TAG = 'Marker'; }
+    static TAG = 'Marker';
+    FILTER = 'marker';
     _loadData(data) {
         this.type = data.type;
         this.startTimeOffset = data.startTimeOffset;
@@ -235,11 +212,8 @@ export class Marker extends MediaTag {
  * Represents a single Chapter media tag.
  */
 export class Chapter extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'chapter';
-    }
-    static { this.TAG = 'Chapter'; }
+    static TAG = 'Chapter';
+    FILTER = 'chapter';
     _loadData(data) {
         this.startTimeOffset = data.startTimeOffset;
         this.endTimeOffset = data.endTimeOffset;
@@ -250,46 +224,31 @@ export class Chapter extends MediaTag {
  * Represents a single Collection media tag.
  */
 export class Collection extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'collection';
-    }
-    static { this.TAG = 'Collection'; }
+    static TAG = 'Collection';
+    FILTER = 'collection';
 }
 /** Represents a single Label media tag. */
 export class Label extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'label';
-    }
-    static { this.TAG = 'Label'; }
+    static TAG = 'Label';
+    FILTER = 'label';
 }
 /** Represents a single Style media tag. */
 export class Style extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'style';
-    }
-    static { this.TAG = 'Style'; }
+    static TAG = 'Style';
+    FILTER = 'style';
 }
 /** Represents a single Format media tag. */
 export class Format extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'format';
-    }
-    static { this.TAG = 'Format'; }
+    static TAG = 'Format';
+    FILTER = 'format';
 }
 /** Represents a single Subformat media tag. */
 export class Subformat extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'subformat';
-    }
-    static { this.TAG = 'Subformat'; }
+    static TAG = 'Subformat';
+    FILTER = 'subformat';
 }
 export class Optimized extends PlexObject {
-    static { this.TAG = 'Item'; }
+    static TAG = 'Item';
     // TODO: Implement items()
     /**
      * Remove this Optimized item.
@@ -332,13 +291,13 @@ class GuidTag extends PlexObject {
     }
 }
 export class Guid extends GuidTag {
-    static { this.TAG = 'Guid'; }
+    static TAG = 'Guid';
 }
 /**
  * Represents a single Rating media tag.
  */
 export class Rating extends PlexObject {
-    static { this.TAG = 'Rating'; }
+    static TAG = 'Rating';
     _loadData(data) {
         this.image = data.image;
         this.type = data.type;
@@ -380,26 +339,61 @@ class BaseResource extends PlexObject {
  * Represents a single Art object.
  */
 export class Art extends BaseResource {
-    static { this.TAG = 'Art'; }
+    static TAG = 'Art';
 }
 /**
  * Represents a single Poster object.
  */
 export class Poster extends BaseResource {
-    static { this.TAG = 'Photo'; }
+    static TAG = 'Photo';
 }
 /**
  * Represents a single Theme object.
  */
 export class Theme extends BaseResource {
-    static { this.TAG = 'Theme'; }
+    static TAG = 'Theme';
 }
 /**
  * Represents a single Audio stream within a {@link MediaPart}.
  */
 export class AudioStream extends MediaPartStream {
-    static { this.TAG = 'Stream'; }
-    static { this.STREAMTYPE = 2; }
+    static TAG = 'Stream';
+    static STREAMTYPE = 2;
+    /** The audio channel layout of the audio stream (ex: 5.1(side)). */
+    audioChannelLayout;
+    /** The bit depth of the audio stream (ex: 16). */
+    bitDepth;
+    /** The bitrate mode of the audio stream (ex: cbr). */
+    bitrateMode;
+    /** The number of audio channels of the audio stream (ex: 6). */
+    channels;
+    /** The duration of audio stream in milliseconds. */
+    duration;
+    /** The profile of the audio stream. */
+    profile;
+    /** The sampling rate of the audio stream (ex: 48000) */
+    samplingRate;
+    /** The stream identifier of the audio stream. */
+    streamIdentifier;
+    // Track only attributes
+    /** The gain for the album. */
+    albumGain;
+    /** The peak for the album. */
+    albumPeak;
+    /** The range for the album. */
+    albumRange;
+    /** The end ramp for the track. */
+    endRamp;
+    /** The gain for the track. */
+    gain;
+    /** The loudness for the track. */
+    loudness;
+    /** The lra for the track. */
+    lra;
+    /** The peak for the track. */
+    peak;
+    /** The start ramp for the track. */
+    startRamp;
     /**
      * Sets this audio stream as the selected audio stream.
      * Alias for {@link MediaPart.setSelectedAudioStream}.
@@ -436,7 +430,7 @@ export class AudioStream extends MediaPartStream {
 }
 /** Represents a single Image media tag. */
 export class Image extends PlexObject {
-    static { this.TAG = 'Image'; }
+    static TAG = 'Image';
     _loadData(data) {
         this.alt = data.alt;
         this.type = data.type;
@@ -446,7 +440,7 @@ export class Image extends PlexObject {
 }
 /** Represents a single Field. */
 export class Field extends PlexObject {
-    static { this.TAG = 'Field'; }
+    static TAG = 'Field';
     _loadData(data) {
         // Convert potential string '1' or '0' to boolean
         this.locked = data.locked === '1' || data.locked === true;
@@ -455,9 +449,6 @@ export class Field extends PlexObject {
 }
 /** Represents a single Mood media tag. */
 export class Mood extends MediaTag {
-    constructor() {
-        super(...arguments);
-        this.FILTER = 'mood';
-    }
-    static { this.TAG = 'Mood'; }
+    static TAG = 'Mood';
+    FILTER = 'mood';
 }

package/dist/src/myplex.js

@@ -13,7 +13,13 @@ import { PlexServer } from './server.js';
  * and return this object.
  */
 export class MyPlexAccount {
-    static { this.key = 'https://plex.tv/api/v2/user'; }
+    baseUrl;
+    username;
+    password;
+    token;
+    timeout;
+    server;
+    static key = 'https://plex.tv/api/v2/user';
     /**
      * This follows the outline described in https://forums.plex.tv/t/authenticating-with-plex/609370
      * to fetch a token and potentially compromise username and password. To use first call `getWebLogin()`
@@ -79,6 +85,18 @@ export class MyPlexAccount {
         }
         throw new Error('Failed to authenticate before timeout');
     }
+    FRIENDINVITE = 'https://plex.tv/api/servers/{machineId}/shared_servers'; // post with data
+    HOMEUSERCREATE = 'https://plex.tv/api/home/users?title={title}'; // post with data
+    EXISTINGUSER = 'https://plex.tv/api/home/users?invitedEmail={username}'; // post with data
+    FRIENDSERVERS = 'https://plex.tv/api/servers/{machineId}/shared_servers/{serverId}'; // put with data
+    PLEXSERVERS = 'https://plex.tv/api/servers/{machineId}'; // get
+    FRIENDUPDATE = 'https://plex.tv/api/friends/{userId}'; // put with args, delete
+    REMOVEHOMEUSER = 'https://plex.tv/api/home/users/{userId}'; // delete
+    REMOVEINVITE = 'https://plex.tv/api/invites/requested/{userId}?friend=0&server=1&home=0'; // delete
+    REQUESTED = 'https://plex.tv/api/invites/requested'; // get
+    REQUESTS = 'https://plex.tv/api/invites/requests'; // get
+    SIGNIN = 'https://plex.tv/users/sign_in.json'; // get with auth
+    WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'; // get, post with data
     /**
      *
      * @param username Your MyPlex username
@@ -95,18 +113,6 @@ export class MyPlexAccount {
         this.token = token;
         this.timeout = timeout;
         this.server = server;
-        this.FRIENDINVITE = 'https://plex.tv/api/servers/{machineId}/shared_servers'; // post with data
-        this.HOMEUSERCREATE = 'https://plex.tv/api/home/users?title={title}'; // post with data
-        this.EXISTINGUSER = 'https://plex.tv/api/home/users?invitedEmail={username}'; // post with data
-        this.FRIENDSERVERS = 'https://plex.tv/api/servers/{machineId}/shared_servers/{serverId}'; // put with data
-        this.PLEXSERVERS = 'https://plex.tv/api/servers/{machineId}'; // get
-        this.FRIENDUPDATE = 'https://plex.tv/api/friends/{userId}'; // put with args, delete
-        this.REMOVEHOMEUSER = 'https://plex.tv/api/home/users/{userId}'; // delete
-        this.REMOVEINVITE = 'https://plex.tv/api/invites/requested/{userId}?friend=0&server=1&home=0'; // delete
-        this.REQUESTED = 'https://plex.tv/api/invites/requested'; // get
-        this.REQUESTS = 'https://plex.tv/api/invites/requests'; // get
-        this.SIGNIN = 'https://plex.tv/users/sign_in.json'; // get with auth
-        this.WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'; // get, post with data
         if (this.token) {
             Object.defineProperty(this, 'token', {
                 enumerable: false,
@@ -292,11 +298,13 @@ async function connect(cls, url, token, timeout) {
  * content such as Plex Media Servers, iPhone or Android clients, etc.
  */
 export class MyPlexResource {
-    static { this.key = 'https://plex.tv/api/v2/resources?includeHttps=1&includeRelay=1'; }
+    account;
+    baseUrl;
+    static key = 'https://plex.tv/api/v2/resources?includeHttps=1&includeRelay=1';
+    TAG = 'Device';
     constructor(account, data, baseUrl = null) {
         this.account = account;
         this.baseUrl = baseUrl;
-        this.TAG = 'Device';
         this._loadData(data);
     }
     async connect(ssl = null, timeout) {
@@ -354,8 +362,8 @@ export class MyPlexResource {
     }
 }
 export class ResourceConnection {
+    TAG = 'Connection';
     constructor(data) {
-        this.TAG = 'Connection';
         this._loadData(data);
     }
     _loadData(data) {
@@ -374,8 +382,8 @@ export class ResourceConnection {
  * https://plex.tv/devices.xml
  */
 export class MyPlexDevice extends PlexObject {
-    static { this.TAG = 'Device'; }
-    static { this.key = 'https://plex.tv/devices.xml'; }
+    static TAG = 'Device';
+    static key = 'https://plex.tv/devices.xml';
     async connect() {
         // TODO: switch between PlexServer and PlexClient
         // Try connecting to all known resource connections in parellel, but

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,18 +13,18 @@ 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 {
-    constructor() {
-        super(...arguments);
-        this.TYPE = 'playlist';
-        /** Cache of playlist items */
-        this._items = null;
-    }
-    static { this.TAG = 'Playlist'; }
+    static TAG = 'Playlist';
     static async create(server, title, options) {
         if (options.smart) {
             throw new Error('not yet supported');
@@ -31,6 +32,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) {
@@ -50,6 +80,9 @@ export class Playlist extends Playable {
         const data = await server.query(key, 'post');
         return new Playlist(server, data.MediaContainer.Metadata[0], key);
     }
+    TYPE = 'playlist';
+    /** Cache of playlist items */
+    _items = null;
     async _edit(args) {
         const searchparams = new URLSearchParams(args);
         const key = `${this.key}?${searchparams.toString()}`;
@@ -63,7 +96,7 @@ export class Playlist extends Playable {
      */
     async item(title) {
         const items = await this.items();
-        const matched = items.find(item => item.title.toLowerCase() === title.toLowerCase());
+        const matched = items.find(item => item.title?.toLowerCase() === title.toLowerCase());
         return matched ?? null;
     }
     async items() {
@@ -135,6 +168,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/playqueue.js

@@ -9,13 +9,10 @@ import { BadRequest } from './exceptions.js';
  * removing, and reordering items.
  */
 export class PlayQueue extends PlexObject {
-    constructor() {
-        super(...arguments);
-        /** Cache of PlayQueue items */
-        this._items = null;
-    }
-    static { this.TAG = 'PlayQueue'; }
-    static { this.TYPE = 'playqueue'; }
+    static TAG = 'PlayQueue';
+    static TYPE = 'playqueue';
+    /** Cache of PlayQueue items */
+    _items = null;
     /**
      * Retrieve an existing PlayQueue by identifier.
      */

package/dist/src/search.js

@@ -1,7 +1,7 @@
 import { PlexObject } from './base/plexObject.js';
 import { rsplit } from './util.js';
 export class SearchResult extends PlexObject {
-    static { this.TAG = 'SearchResult'; }
+    static TAG = 'SearchResult';
     _loadData(data) {
         this.guid = data.guid;
         this.lifespanEnded = data.lifespanEnded;
@@ -14,7 +14,7 @@ export class SearchResult extends PlexObject {
  * Represents a single Agent
  */
 export class Agent extends PlexObject {
-    static { this.TAG = 'Agent'; }
+    static TAG = 'Agent';
     // languageCode: any[] = [];
     _loadData(data) {
         this.hasAttribution = data.hasAttribution;

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.