@ctrl/plex 3.9.2 → 3.11.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/alert.js

@@ -1,9 +1,11 @@
 import WebSocket from 'ws';
 export class AlertListener {
+    server;
+    callback;
+    key = '/:/websockets/notifications';
     constructor(server, callback) {
         this.server = server;
         this.callback = callback;
-        this.key = '/:/websockets/notifications';
     }
     async run() {
         const url = this.server.url(this.key, true).toString().replace('http', 'ws');

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,13 +1,13 @@
 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'; }
+    static METADATA_TYPE = 'track';
     /** Hardcoded list type for filtering. */
     get listType() {
         return 'audio';
@@ -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;
@@ -151,8 +153,8 @@ export class Audio extends PartialPlexObject {
  * Represents a single Track.
  */
 export class Track extends Audio {
-    static { this.TAG = 'Track'; }
-    static { this.TYPE = 'track'; }
+    static TAG = 'Track';
+    static TYPE = 'track';
     // Properties from Mixins (assuming, some might overlap with Audio)
     // userRating inherited from Audio
     // art inherited from Audio
@@ -307,8 +309,8 @@ export class Track extends Audio {
  */
 export class Artist extends Audio {
     /* implements AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, ArtistEditMixins */
-    static { this.TAG = 'Directory'; }
-    static { this.TYPE = 'artist'; }
+    static TAG = 'Directory';
+    static TYPE = 'artist';
     get locations() {
         // Replicate listAttrs logic (assuming Location tag with path attribute)
         return this._data?.Location?.map((loc) => loc.path).filter(Boolean) ?? [];
@@ -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;
         }
     }
@@ -479,8 +480,8 @@ export class Artist extends Audio {
  * Represents a single Album.
  */
 export class Album extends Audio {
-    static { this.TAG = 'Directory'; }
-    static { this.TYPE = 'album'; }
+    static TAG = 'Directory';
+    static TYPE = 'album';
     constructor(server, data, initpath, parent) {
         super(server, data, initpath, parent);
         this._loadData(data);

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/base/partialPlexObject.js

@@ -3,31 +3,28 @@ import { SearchResult, searchType } from '../search.js';
 import { getAgentIdentifier, ltrim, tagHelper } from '../util.js';
 import { PlexObject } from './plexObject.js';
 export class PartialPlexObject extends PlexObject {
-    constructor() {
-        super(...arguments);
-        this._INCLUDES = {
-            checkFiles: 0,
-            includeAllConcerts: 0,
-            includeBandwidths: 1,
-            includeChapters: 1,
-            includeChildren: 0,
-            includeConcerts: 0,
-            includeExternalMedia: 0,
-            includeExtras: 0,
-            includeFields: 'thumbBlurHash,artBlurHash',
-            includeGeolocation: 1,
-            includeLoudnessRamps: 1,
-            includeMarkers: 1,
-            includeOnDeck: 0,
-            includePopularLeaves: 0,
-            includePreferences: 0,
-            includeRelated: 0,
-            includeRelatedCount: 0,
-            includeReviews: 0,
-            includeStations: 0,
-        };
-        this._detailsKey = this._buildDetailsKey();
-    }
+    _INCLUDES = {
+        checkFiles: 0,
+        includeAllConcerts: 0,
+        includeBandwidths: 1,
+        includeChapters: 1,
+        includeChildren: 0,
+        includeConcerts: 0,
+        includeExternalMedia: 0,
+        includeExtras: 0,
+        includeFields: 'thumbBlurHash,artBlurHash',
+        includeGeolocation: 1,
+        includeLoudnessRamps: 1,
+        includeMarkers: 1,
+        includeOnDeck: 0,
+        includePopularLeaves: 0,
+        includePreferences: 0,
+        includeRelated: 0,
+        includeRelatedCount: 0,
+        includeReviews: 0,
+        includeStations: 0,
+    };
+    _detailsKey = this._buildDetailsKey();
     /**
      * Tell Plex Media Server to performs analysis on it this item to gather
      *  information. Analysis includes:

package/dist/src/base/plexObject.js

@@ -3,10 +3,18 @@ import { URLSearchParams } from 'url';
  * Base class for all? Plex objects
  */
 export class PlexObject {
+    server;
     /** xml element tag */
-    static { this.TAG = null; }
+    static TAG = null;
     /** xml element type */
-    static { this.TYPE = null; }
+    static TYPE = null;
+    /**
+     * WeakRef to the parent object that this object is built from.
+     */
+    parent;
+    _detailsKey;
+    initpath;
+    _INCLUDES;
     constructor(server, data, initpath, parent) {
         this.server = server;
         this.initpath = initpath ?? this.key;

package/dist/src/client.d.ts

@@ -57,6 +57,7 @@ export declare class PlexClient {
     _token: string | null;
     TAG: string;
     key: string;
+    timeout: number;
     deviceClass?: string;
     machineIdentifier?: string;
     product?: string;
@@ -66,7 +67,6 @@ export declare class PlexClient {
     platform?: string;
     platformVersion?: string;
     title?: string;
-    timeout: number;
     constructor(options?: PlexOptions);
     /**
      * Alias of reload as any subsequent requests to this client will be

package/dist/src/client.js

@@ -32,17 +32,18 @@ import { BASE_HEADERS, TIMEOUT } from './config.js';
  *         :func:`~plexapi.client.PlexClient.proxyThroughServer()` (default False).
  */
 export class PlexClient {
+    /**
+     * HTTP address of the client
+     */
+    _baseurl = null;
+    /**
+     * Token used to access this client
+     */
+    _token = null;
+    TAG = 'Player';
+    key = '/resources';
+    timeout;
     constructor(options = {}) {
-        /**
-         * HTTP address of the client
-         */
-        this._baseurl = null;
-        /**
-         * Token used to access this client
-         */
-        this._token = null;
-        this.TAG = 'Player';
-        this.key = '/resources';
         if (options.baseurl) {
             if (options.baseurl.endsWith('/')) {
                 this._baseurl = options.baseurl.slice(0, -1);

package/dist/src/exceptions.js

@@ -1,39 +1,39 @@
 export class BadRequest extends Error {
+    message = 'An invalid request, generally a user error.';
     constructor(message) {
         super(message);
-        this.message = 'An invalid request, generally a user error.';
         this.name = 'BadRequest';
         this.message = message;
     }
 }
 export class NotFound extends Error {
+    message = 'Request media item or device is not found.';
     constructor(message) {
         super(message);
-        this.message = 'Request media item or device is not found.';
         this.name = 'NotFound';
         this.message = message;
     }
 }
 export class UnknownType extends Error {
+    message = 'Unknown library type.';
     constructor(message) {
         super(message);
-        this.message = 'Unknown library type.';
         this.name = 'UnknownType';
         this.message = message;
     }
 }
 export class Unsupported extends Error {
+    message = 'Unsupported client request.';
     constructor(message) {
         super(message);
-        this.message = 'Unsupported client request.';
         this.name = 'Unsupported';
         this.message = message;
     }
 }
 export class Unauthorized extends Error {
+    message = 'Invalid username or password.';
     constructor(message) {
         super(message);
-        this.message = 'Invalid username or password.';
         this.name = 'Unauthorized';
         this.message = message;
     }

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

@@ -8,7 +8,8 @@ import { Playlist } from './playlist.js';
 import { searchType } from './search.js';
 import { Movie, Show } from './video.js';
 export class Library {
-    static { this.key = '/library'; }
+    server;
+    static key = '/library';
     constructor(server, data) {
         this.server = server;
         this._loadData(data);
@@ -26,7 +27,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);
                 }
@@ -36,9 +36,9 @@ export class Library {
     }
     async section(title) {
         const sections = await this.sections();
-        const section = sections.find(s => s.title.toLowerCase() === title.toLowerCase());
+        const section = sections.find(s => s.title?.toLowerCase() === title.toLowerCase());
         if (!section) {
-            const avilableSections = sections.map(s => s.title).join(', ');
+            const avilableSections = sections.map(s => s.title || 'Unknown').join(', ');
             throw new Error(`Invalid library section: ${title}. Available: ${avilableSections}`);
         }
         return section;
@@ -276,9 +276,10 @@ export class Library {
  * Base class for a single library section.
  */
 export class LibrarySection extends PlexObject {
-    static { this.ALLOWED_FILTERS = []; }
-    static { this.ALLOWED_SORT = []; }
-    static { this.BOOLEAN_FILTERS = ['unwatched', 'duplicate']; }
+    static ALLOWED_FILTERS = [];
+    static ALLOWED_SORT = [];
+    static BOOLEAN_FILTERS = ['unwatched', 'duplicate'];
+    SECTION_TYPE;
     async all(sort = '') {
         let sortStr = '';
         if (sort) {
@@ -574,14 +575,8 @@ export class LibrarySection extends PlexObject {
     }
 }
 export class MovieSection extends LibrarySection {
-    constructor() {
-        super(...arguments);
-        this.METADATA_TYPE = 'movie';
-        this.CONTENT_TYPE = 'video';
-        this.SECTION_TYPE = Movie;
-    }
-    static { this.TYPE = 'movie'; }
-    static { this.ALLOWED_FILTERS = [
+    static TYPE = 'movie';
+    static ALLOWED_FILTERS = [
         'unwatched',
         'duplicate',
         'year',
@@ -603,8 +598,8 @@ export class MovieSection extends LibrarySection {
         'lastViewedAt',
         'viewCount',
         'addedAt',
-    ]; }
-    static { this.ALLOWED_SORT = [
+    ];
+    static ALLOWED_SORT = [
         'addedAt',
         'originallyAvailableAt',
         'lastViewedAt',
@@ -612,18 +607,15 @@ export class MovieSection extends LibrarySection {
         'rating',
         'mediaHeight',
         'duration',
-    ]; }
-    static { this.TAG = 'Directory'; }
+    ];
+    static TAG = 'Directory';
+    METADATA_TYPE = 'movie';
+    CONTENT_TYPE = 'video';
+    SECTION_TYPE = Movie;
 }
 export class ShowSection extends LibrarySection {
-    constructor() {
-        super(...arguments);
-        this.METADATA_TYPE = 'episode';
-        this.CONTENT_TYPE = 'video';
-        this.SECTION_TYPE = Show;
-    }
-    static { this.TYPE = 'show'; }
-    static { this.ALLOWED_FILTERS = [
+    static TYPE = 'show';
+    static ALLOWED_FILTERS = [
         'unwatched',
         'year',
         'genre',
@@ -649,16 +641,19 @@ export class ShowSection extends LibrarySection {
         'episode.userRating',
         'episode.viewCount',
         'episode.lastViewedAt',
-    ]; }
-    static { this.ALLOWED_SORT = [
+    ];
+    static ALLOWED_SORT = [
         'addedAt',
         'lastViewedAt',
         'originallyAvailableAt',
         'titleSort',
         'rating',
         'unwatched',
-    ]; }
-    static { this.TAG = 'Directory'; }
+    ];
+    static TAG = 'Directory';
+    METADATA_TYPE = 'episode';
+    CONTENT_TYPE = 'video';
+    SECTION_TYPE = Show;
     // TODO: figure out how to return episode objects
     // /**
     //  * Search for an episode. See :func:`~plexapi.library.LibrarySection.search` for usage.
@@ -676,14 +671,11 @@ export class ShowSection extends LibrarySection {
     }
 }
 export class MusicSection extends LibrarySection {
-    constructor() {
-        super(...arguments);
-        this.METADATA_TYPE = 'track';
-        this.CONTENT_TYPE = 'audio';
-        this.SECTION_TYPE = Track;
-    }
-    static { this.TYPE = 'artist'; }
-    static { this.TAG = 'Directory'; }
+    static TYPE = 'artist';
+    static TAG = 'Directory';
+    METADATA_TYPE = 'track';
+    CONTENT_TYPE = 'audio';
+    SECTION_TYPE = Track;
     /** Returns a list of Album objects in this section. */
     async albums() {
         const key = `/library/sections/${this.key}/albums`;
@@ -737,7 +729,7 @@ export class MusicSection extends LibrarySection {
 }
 /** Represents a single Hub (or category) in the PlexServer search */
 export class Hub extends PlexObject {
-    static { this.TAG = 'Hub'; }
+    static TAG = 'Hub';
     _loadData(data) {
         this.hubIdentifier = data.hubIdentifier;
         this.size = data.size;
@@ -767,11 +759,8 @@ export class Folder extends PlexObject {
     }
 }
 export class Collections extends PartialPlexObject {
-    constructor() {
-        super(...arguments);
-        this.TYPE = 'collection';
-    }
-    static { this.TAG = 'Directory'; }
+    static TAG = 'Directory';
+    TYPE = 'collection';
     // Alias for childCount
     get size() {
         return this.childCount;
@@ -810,7 +799,7 @@ export class Collections extends PartialPlexObject {
     }
 }
 export class FilterChoice extends PlexObject {
-    static { this.TAG = 'Directory'; }
+    static TAG = 'Directory';
     _loadData(data) {
         this.key = data.key;
         this.title = data.title;
@@ -819,7 +808,7 @@ export class FilterChoice extends PlexObject {
     }
 }
 export class FilteringType extends PlexObject {
-    static { this.TAG = 'Type'; }
+    static TAG = 'Type';
     _loadData(data) {
         this.active = data.active;
         this.fields = findItems(data, undefined, FilteringField);
@@ -834,7 +823,7 @@ export class FilteringType extends PlexObject {
  * Represents a single Filter object for a {@link FilteringType}
  */
 export class FilteringFilter extends PlexObject {
-    static { this.TAG = 'Filter'; }
+    static TAG = 'Filter';
     _loadData(data) {
         this.filter = data.filter;
         this.filterType = data.filterType;
@@ -847,7 +836,7 @@ export class FilteringFilter extends PlexObject {
  * Represents a single Sort object for a {@link FilteringType}
  */
 export class FilteringSort extends PlexObject {
-    static { this.TAG = 'Sort'; }
+    static TAG = 'Sort';
     _loadData(data) {
         this.active = data.active;
         this.activeDirection = data.activeDirection;
@@ -863,7 +852,7 @@ export class FilteringSort extends PlexObject {
  * Represents a single Field object for a {@link FilteringType}
  */
 export class FilteringField extends PlexObject {
-    static { this.TAG = 'Field'; }
+    static TAG = 'Field';
     _loadData(data) {
         this.key = data.key;
         this.title = data.title;
@@ -875,7 +864,7 @@ export class FilteringField extends PlexObject {
  * Represents a single FieldType for library filtering.
  */
 export class FilteringFieldType extends PlexObject {
-    static { this.TAG = 'FieldType'; }
+    static TAG = 'FieldType';
     _loadData(data) {
         this.type = data.type;
         this.operators = findItems(data, undefined, FilteringOperator);
@@ -885,7 +874,7 @@ export class FilteringFieldType extends PlexObject {
  * Represents a single FilterChoice for library filtering.
  */
 export class FilteringOperator extends PlexObject {
-    static { this.TAG = 'Operator'; }
+    static TAG = 'Operator';
     _loadData(data) {
         this.key = data.key;
         this.type = data.type;