@ctrl/plex 3.7.0 → 3.8.0

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

@@ -1,3 +1,4 @@
+import type { Section } from '../library.js';
 import { SearchResult } from '../search.js';
 import { PlexObject } from './plexObject.js';
 export declare abstract class PartialPlexObject extends PlexObject {
@@ -100,7 +101,7 @@ export declare abstract class PartialPlexObject extends PlexObject {
      * @param mindate Min datetime to return results from.
      */
     history(maxresults?: number, mindate?: Date): Promise<import("../server.types.js").HistoryMetadatum[]>;
-    section(): Promise<import("../library.js").Section>;
+    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,5 +8,6 @@ export * from './myplex.js';
 export * from './playlist.js';
 export * from './server.js';
 export * from './video.js';
+export * from './audio.js';
 export { X_PLEX_IDENTIFIER } from './config.js';
 export { SearchResult, Agent, SEARCHTYPES } from './search.js';

package/dist/src/index.js

@@ -7,5 +7,6 @@ export * from './myplex.js';
 export * from './playlist.js';
 export * from './server.js';
 export * from './video.js';
+export * from './audio.js';
 export { X_PLEX_IDENTIFIER } from './config.js';
 export { SearchResult, Agent, SEARCHTYPES } from './search.js';

package/dist/src/library.d.ts

@@ -1,13 +1,14 @@
 import type { Class } from 'type-fest';
 import { PartialPlexObject } from './base/partialPlexObject.js';
 import { PlexObject } from './base/plexObject.js';
+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 { PlexServer } from './server.js';
-import { Movie, Show, type VideoType } from './video.js';
-export type Section = MovieSection | ShowSection;
+import { Movie, Show } from './video.js';
+export type Section = MovieSection | ShowSection | MusicSection;
 export declare class Library {
     private readonly server;
     static key: string;
@@ -198,7 +199,7 @@ export declare class Library {
 }
 type Libtype = keyof typeof SEARCHTYPES;
 interface SearchArgs {
-    [key: string]: number | string | boolean | string[];
+    [key: string]: number | string | boolean | string[] | Record<string, string | number | boolean>;
     /** General string query to search for. Partial string matches are allowed. */
     title: string;
     /** A string of comma separated sort fields or a list of sort fields in the format ``column:dir``. */
@@ -221,11 +222,14 @@ interface SearchArgs {
      * Return only results that have duplicates.
      */
     duplicate: number;
+    /** Advanced filters object used by music searches. */
+    filters?: Record<string, string | number | boolean>;
 }
+export type SectionType = Movie | Show | Artist | Album | Track;
 /**
  * Base class for a single library section.
  */
-export declare abstract class LibrarySection<SectionVideoType = VideoType> extends PlexObject {
+export declare abstract class LibrarySection<SType = SectionType> extends PlexObject {
     static ALLOWED_FILTERS: string[];
     static ALLOWED_SORT: string[];
     static BOOLEAN_FILTERS: string[];
@@ -261,16 +265,16 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
     /** Unique id for this section (32258d7c-3e6c-4ac5-98ad-bad7a3b78c63) */
     uuid: string;
     CONTENT_TYPE: string;
-    readonly VIDEO_TYPE: Class<SectionVideoType>;
+    readonly SECTION_TYPE: Class<SType>;
     _filterTypes?: FilteringType[];
     _fieldTypes?: FilteringFieldType[];
-    all(sort?: string): Promise<SectionVideoType[]>;
+    all(sort?: string): Promise<SType[]>;
     agents(): Promise<Agent[]>;
     /**
      * @param title Title of the item to return.
      * @returns the media item with the specified title.
      */
-    get(title: string): Promise<SectionVideoType>;
+    get(title: string): Promise<SType>;
     /**
      * Returns the media item with the specified external IMDB, TMDB, or TVDB ID.
      * Note: This search uses a PlexAPI operator so performance may be slow. All items from the
@@ -296,7 +300,7 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
      * 				result2 = guidLookup['tmdb://1399']
      * 				result3 = guidLookup['tvdb://121361']
      */
-    getGuid(guid: string): Promise<SectionVideoType>;
+    getGuid(guid: string): Promise<SType>;
     /**
      * Returns the Plex Web URL for the library.
      *
@@ -316,7 +320,7 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
      * TLDR: This is untested but seems to work. Use library section search when you can.
      * @param args Search using a number of different attributes
      */
-    search<T = SectionVideoType>(args?: Partial<SearchArgs>, Cls?: any): Promise<T[]>;
+    search<C = SType>(args?: Partial<SearchArgs>, Cls?: Class<C>): Promise<C[]>;
     /**
      * Run an analysis on all of the items in this library section.
      * See :func:`~plexapi.base.PlexPartialObject.analyze` for more details.
@@ -361,7 +365,7 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
      * Returns a list of playlists from this library section.
      */
     playlists(): Promise<Playlist[]>;
-    collections(args?: Record<string, number | string | boolean>): Promise<Collections<SectionVideoType>[]>;
+    collections(args?: Record<string, number | string | boolean>): Promise<Collections<SType>[]>;
     /**
      * Returns a list of available Folders for this library section.
      */
@@ -405,7 +409,7 @@ export declare class MovieSection extends LibrarySection<Movie> {
     static TAG: string;
     METADATA_TYPE: string;
     CONTENT_TYPE: string;
-    readonly VIDEO_TYPE: typeof Movie;
+    readonly SECTION_TYPE: typeof Movie;
 }
 export declare class ShowSection extends LibrarySection<Show> {
     static TYPE: string;
@@ -414,7 +418,7 @@ export declare class ShowSection extends LibrarySection<Show> {
     static TAG: string;
     METADATA_TYPE: string;
     CONTENT_TYPE: string;
-    readonly VIDEO_TYPE: typeof Show;
+    readonly SECTION_TYPE: typeof Show;
     /**
      * Returns a list of recently added episodes from this library section.
      *
@@ -422,6 +426,40 @@ export declare class ShowSection extends LibrarySection<Show> {
      */
     recentlyAdded(args: any, libtype?: string, maxresults?: number): Promise<Show[]>;
 }
+export declare class MusicSection extends LibrarySection<Track> {
+    static TYPE: string;
+    static TAG: string;
+    METADATA_TYPE: string;
+    CONTENT_TYPE: string;
+    readonly SECTION_TYPE: typeof Track;
+    /** Returns a list of Album objects in this section. */
+    albums(): Promise<Album[]>;
+    /**
+     * Returns the music stations Hub for this section, if available.
+     * TODO: Investigate how to return actual station items (Playlists?) from the Hub.
+     */
+    stations(): Promise<Hub | undefined>;
+    /** Search for an artist. */
+    searchArtists(args?: Partial<SearchArgs>): Promise<Artist[]>;
+    /** Search for an album. */
+    searchAlbums(args?: Partial<SearchArgs>): Promise<Album[]>;
+    /** Search for a track. */
+    searchTracks(args?: Partial<SearchArgs>): Promise<Track[]>;
+    /** Returns a list of recently added artists from this library section. */
+    recentlyAddedArtists(maxresults?: number): Promise<Artist[]>;
+    /** Returns a list of recently added albums from this library section. */
+    recentlyAddedAlbums(maxresults?: number): Promise<Album[]>;
+    /** Returns a list of recently added tracks from this library section. */
+    recentlyAddedTracks(maxresults?: number): Promise<Track[]>;
+    /**
+     * Returns a list of tracks from this library section that are part of a sonic adventure.
+     * IDs should be of a track; other IDs will return an empty list or an error.
+     * @param start The Track or ID of the first track in the sonic adventure.
+     * @param end The Track or ID of the last track in the sonic adventure.
+     * @returns A list of tracks that are part of a sonic adventure.
+     */
+    sonicAdventure(start: Track | number, end: Track | number): Promise<Track[]>;
+}
 /** Represents a single Hub (or category) in the PlexServer search */
 export declare class Hub extends PlexObject {
     static TAG: string;
@@ -446,7 +484,7 @@ export declare class Folder extends PlexObject {
     subfolders(): Promise<Folder[]>;
     protected _loadData(data: any): void;
 }
-export declare class Collections<CollectionVideoType = VideoType> extends PartialPlexObject {
+export declare class Collections<CollectionVideoType = SectionType> extends PartialPlexObject {
     static TAG: string;
     TYPE: string;
     guid: string;

package/dist/src/library.js

@@ -1,6 +1,7 @@
 import { URLSearchParams } from 'url';
 import { PartialPlexObject } from './base/partialPlexObject.js';
 import { PlexObject } from './base/plexObject.js';
+import { Album, Artist, Track } from './audio.js';
 import { fetchItem, fetchItems, findItems } from './baseFunctionality.js';
 import { NotFound } from './exceptions.js';
 import { Playlist } from './playlist.js';
@@ -19,8 +20,11 @@ export class Library {
         const key = '/library/sections';
         const elems = await this.server.query(key);
         const sections = [];
+        if (!elems.MediaContainer.Directory) {
+            return sections;
+        }
         for (const elem of elems.MediaContainer.Directory) {
-            for (const cls of [MovieSection, ShowSection]) {
+            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);
@@ -281,7 +285,7 @@ export class LibrarySection extends PlexObject {
             sortStr = `?sort=${sort}`;
         }
         const key = `/library/sections/${this.key}/all${sortStr}`;
-        const items = await fetchItems(this.server, key, undefined, this.VIDEO_TYPE, this);
+        const items = await fetchItems(this.server, key, undefined, this.SECTION_TYPE, this);
         return items;
     }
     async agents() {
@@ -294,7 +298,7 @@ export class LibrarySection extends PlexObject {
     async get(title) {
         const key = `/library/sections/${this.key}/all?includeGuids=1&title=${title}`;
         const data = await fetchItem(this.server, key, { title__iexact: title });
-        return new this.VIDEO_TYPE(this.server, data, key, this);
+        return new this.SECTION_TYPE(this.server, data, key, this);
     }
     /**
      * Returns the media item with the specified external IMDB, TMDB, or TVDB ID.
@@ -355,7 +359,7 @@ export class LibrarySection extends PlexObject {
      * TLDR: This is untested but seems to work. Use library section search when you can.
      * @param args Search using a number of different attributes
      */
-    async search(args = {}, Cls = this.VIDEO_TYPE) {
+    async search(args = {}, Cls) {
         const params = new URLSearchParams();
         for (const [key, value] of Object.entries(args)) {
             let strValue;
@@ -374,7 +378,8 @@ export class LibrarySection extends PlexObject {
             params.append('type', searchType(args.libtype).toString());
         }
         const key = `/library/sections/${this.key}/all?${params.toString()}`;
-        const data = await fetchItems(this.server, key, undefined, Cls, this);
+        const ClsToUse = Cls ?? this.SECTION_TYPE;
+        const data = await fetchItems(this.server, key, undefined, ClsToUse, this);
         return data;
     }
     /**
@@ -467,7 +472,7 @@ export class LibrarySection extends PlexObject {
     async collections(args = {}) {
         const collections = await this.search({ ...args, libtype: 'collection' }, Collections);
         collections.forEach(collection => {
-            collection.VIDEO_TYPE = this.VIDEO_TYPE;
+            collection.VIDEO_TYPE = this.SECTION_TYPE;
         });
         return collections;
     }
@@ -573,7 +578,7 @@ export class MovieSection extends LibrarySection {
         super(...arguments);
         this.METADATA_TYPE = 'movie';
         this.CONTENT_TYPE = 'video';
-        this.VIDEO_TYPE = Movie;
+        this.SECTION_TYPE = Movie;
     }
     static { this.TYPE = 'movie'; }
     static { this.ALLOWED_FILTERS = [
@@ -615,7 +620,7 @@ export class ShowSection extends LibrarySection {
         super(...arguments);
         this.METADATA_TYPE = 'episode';
         this.CONTENT_TYPE = 'video';
-        this.VIDEO_TYPE = Show;
+        this.SECTION_TYPE = Show;
     }
     static { this.TYPE = 'show'; }
     static { this.ALLOWED_FILTERS = [
@@ -670,6 +675,66 @@ export class ShowSection extends LibrarySection {
         return this.search({ libtype, maxresults, sort: 'episode.addedAt:desc', ...args });
     }
 }
+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'; }
+    /** Returns a list of Album objects in this section. */
+    async albums() {
+        const key = `/library/sections/${this.key}/albums`;
+        return fetchItems(this.server, key, undefined, Album, this);
+    }
+    /**
+     * Returns the music stations Hub for this section, if available.
+     * TODO: Investigate how to return actual station items (Playlists?) from the Hub.
+     */
+    async stations() {
+        const hubs = await this.hubs();
+        return hubs.find(hub => hub.hubIdentifier === 'hub.music.stations');
+    }
+    /** Search for an artist. */
+    async searchArtists(args = {}) {
+        return this.search({ ...args, libtype: 'artist' }, Artist);
+    }
+    /** Search for an album. */
+    async searchAlbums(args = {}) {
+        return this.search({ ...args, libtype: 'album' }, Album);
+    }
+    /** Search for a track. */
+    async searchTracks(args = {}) {
+        return this.search({ ...args, libtype: 'track' }, Track);
+    }
+    /** Returns a list of recently added artists from this library section. */
+    async recentlyAddedArtists(maxresults = 50) {
+        return this.search({ maxresults, sort: 'addedAt:desc', libtype: 'artist' }, Artist);
+    }
+    /** Returns a list of recently added albums from this library section. */
+    async recentlyAddedAlbums(maxresults = 50) {
+        return this.search({ maxresults, sort: 'addedAt:desc', libtype: 'album' }, Album);
+    }
+    /** Returns a list of recently added tracks from this library section. */
+    async recentlyAddedTracks(maxresults = 50) {
+        return this.search({ maxresults, sort: 'addedAt:desc', libtype: 'track' }, Track);
+    }
+    /**
+     * Returns a list of tracks from this library section that are part of a sonic adventure.
+     * IDs should be of a track; other IDs will return an empty list or an error.
+     * @param start The Track or ID of the first track in the sonic adventure.
+     * @param end The Track or ID of the last track in the sonic adventure.
+     * @returns A list of tracks that are part of a sonic adventure.
+     */
+    async sonicAdventure(start, end) {
+        const startID = typeof start === 'number' ? start : start.ratingKey;
+        const endID = typeof end === 'number' ? end : end.ratingKey;
+        const key = `/library/sections/${this.key}/computePath?startID=${startID}&endID=${endID}`;
+        return fetchItems(this.server, key, undefined, Track, this);
+    }
+}
 /** Represents a single Hub (or category) in the PlexServer search */
 export class Hub extends PlexObject {
     static { this.TAG = 'Hub'; }

package/dist/src/media.d.ts

@@ -231,6 +231,26 @@ export declare class Collection extends MediaTag {
     static TAG: "Collection";
     FILTER: "collection";
 }
+/** Represents a single Label media tag. */
+export declare class Label extends MediaTag {
+    static TAG: "Label";
+    FILTER: "label";
+}
+/** Represents a single Style media tag. */
+export declare class Style extends MediaTag {
+    static TAG: "Style";
+    FILTER: "style";
+}
+/** Represents a single Format media tag. */
+export declare class Format extends MediaTag {
+    static TAG: "Format";
+    FILTER: "format";
+}
+/** Represents a single Subformat media tag. */
+export declare class Subformat extends MediaTag {
+    static TAG: "Subformat";
+    FILTER: "subformat";
+}
 export declare class Optimized extends PlexObject {
     static TAG: string;
     id: string;
@@ -380,4 +400,29 @@ export declare class AudioStream extends MediaPartStream {
     setSelected(): Promise<void>;
     protected _loadData(data: any): void;
 }
+/** Represents a single Image media tag. */
+export declare class Image extends PlexObject {
+    static TAG: "Image";
+    /** The alt text for the image. */
+    alt?: string;
+    /** The type of image (e.g. coverPoster, background, snapshot). */
+    type?: string;
+    /** The API URL (/library/metadata/<ratingKey>/thumb/<thumbid>). */
+    url?: string;
+    protected _loadData(data: any): void;
+}
+/** Represents a single Field. */
+export declare class Field extends PlexObject {
+    static TAG: "Field";
+    /** True if the field is locked. */
+    locked: boolean;
+    /** The name of the field. */
+    name: string;
+    protected _loadData(data: any): void;
+}
+/** Represents a single Mood media tag. */
+export declare class Mood extends MediaTag {
+    static TAG: "Mood";
+    FILTER: "mood";
+}
 export {};

package/dist/src/media.js

@@ -256,6 +256,38 @@ export class Collection extends MediaTag {
     }
     static { this.TAG = 'Collection'; }
 }
+/** Represents a single Label media tag. */
+export class Label extends MediaTag {
+    constructor() {
+        super(...arguments);
+        this.FILTER = 'label';
+    }
+    static { this.TAG = 'Label'; }
+}
+/** Represents a single Style media tag. */
+export class Style extends MediaTag {
+    constructor() {
+        super(...arguments);
+        this.FILTER = 'style';
+    }
+    static { this.TAG = 'Style'; }
+}
+/** Represents a single Format media tag. */
+export class Format extends MediaTag {
+    constructor() {
+        super(...arguments);
+        this.FILTER = 'format';
+    }
+    static { this.TAG = 'Format'; }
+}
+/** Represents a single Subformat media tag. */
+export class Subformat extends MediaTag {
+    constructor() {
+        super(...arguments);
+        this.FILTER = 'subformat';
+    }
+    static { this.TAG = 'Subformat'; }
+}
 export class Optimized extends PlexObject {
     static { this.TAG = 'Item'; }
     // TODO: Implement items()
@@ -402,3 +434,30 @@ export class AudioStream extends MediaPartStream {
         this.startRamp = data.startRamp;
     }
 }
+/** Represents a single Image media tag. */
+export class Image extends PlexObject {
+    static { this.TAG = 'Image'; }
+    _loadData(data) {
+        this.alt = data.alt;
+        this.type = data.type;
+        // Assuming server.url is needed to make this a complete URL
+        this.url = data.url ? this.server.url(data.url, true)?.toString() : undefined;
+    }
+}
+/** Represents a single Field. */
+export class Field extends PlexObject {
+    static { this.TAG = 'Field'; }
+    _loadData(data) {
+        // Convert potential string '1' or '0' to boolean
+        this.locked = data.locked === '1' || data.locked === true;
+        this.name = data.name;
+    }
+}
+/** Represents a single Mood media tag. */
+export class Mood extends MediaTag {
+    constructor() {
+        super(...arguments);
+        this.FILTER = 'mood';
+    }
+    static { this.TAG = 'Mood'; }
+}

package/dist/src/myplex.js

@@ -110,12 +110,14 @@ export class MyPlexAccount {
         if (this.token) {
             Object.defineProperty(this, 'token', {
                 enumerable: false,
+                configurable: true,
                 value: this.token,
             });
         }
         if (this.password) {
             Object.defineProperty(this, 'password', {
                 enumerable: false,
+                configurable: true,
                 value: this.password,
             });
         }
@@ -249,6 +251,7 @@ export class MyPlexAccount {
         // Attempt to prevent token from being logged accidentally
         Object.defineProperty(this, 'token', {
             enumerable: false,
+            configurable: true,
             value: user.authToken,
         });
         this.authenticationToken = this.token;
@@ -406,6 +409,7 @@ export class MyPlexDevice extends PlexObject {
         // Attempt to prevent token from being logged accidentally
         Object.defineProperty(this, 'token', {
             enumerable: false,
+            configurable: true,
             value: data.$.token,
         });
         this.screenResolution = data.$.screenResolution;

package/dist/src/playlist.d.ts

@@ -1,13 +1,13 @@
 import { Playable } from './base/playable.js';
-import type { Section } from './library.js';
+import type { Section, SectionType } from './library.js';
 import type { PlaylistResponse } from './playlist.types.js';
 import type { PlexServer } from './server.js';
-import { Episode, Movie, type VideoType } from './video.js';
+import { Episode, Movie } from './video.js';
 interface CreateRegularPlaylistOptions {
     /** True to create a smart playlist */
     smart?: false;
     /** Regular playlists only */
-    items?: VideoType[];
+    items?: SectionType[];
 }
 interface CreateSmartPlaylistOptions {
     /** True to create a smart playlist */

package/dist/src/video.d.ts

@@ -3,7 +3,6 @@ import { Playable } from './base/playable.js';
 import type { ExtrasData, FullShowData, MovieData, ShowData } from './library.types.js';
 import { Chapter, Collection, Country, Director, Genre, Guid, Marker, Media, Poster, Producer, Rating, Role, Similar, Writer } from './media.js';
 import type { ChapterSource, EpisodeMetadata, FullMovieResponse } from './video.types.js';
-export type VideoType = Movie | Show;
 declare abstract class Video extends Playable {
     /** Datetime this item was added to the library. */
     addedAt: Date;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ctrl/plex",
-  "version": "3.7.0",
-  "description": "plex api client in typescript",
+  "version": "3.8.0",
+  "description": "plex api client in typescript using ofetch",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "publishConfig": {
     "access": "public"