@ctrl/plex 3.6.1 → 3.8.0

package/README.md

@@ -1,9 +1,8 @@
 # @ctrl/plex
 
 [![npm](https://badgen.net/npm/v/@ctrl/plex)](https://www.npmjs.com/package/@ctrl/plex)
-[![coverage](https://badgen.net/codecov/c/github/scttcper/plex)](https://codecov.io/gh/scttcper/plex)
 
-> A TypeScript [Plex](https://www.plex.tv/) API client based on [pkkid/python-plexapi](https://github.com/pkkid/python-plexapi)
+> A TypeScript [Plex](https://www.plex.tv/) API client using [ofetch](https://github.com/unjs/ofetch) based on [pkkid/python-plexapi](https://github.com/pushingkarmaorg/python-plexapi)
 
 ### Install
 
@@ -13,11 +12,12 @@ npm install @ctrl/plex
 
 ### Docs
 
-https://ctrl-plex.vercel.app 
+https://ctrl-plex.vercel.app
 
 ### Use
 
 Create a plex connection
+
 ```ts
 import { MyPlexAccount } from '@ctrl/plex';
 
@@ -28,6 +28,7 @@ const library = await plex.library();
 ```
 
 ###### Example 1: List all unwatched movies.
+
 ```ts
 import { MovieSection } from '@ctrl/plex';
 
@@ -38,6 +39,7 @@ const results = await section.search({ unwatched: true });
 ```
 
 ###### Example 2: Search for a list of movies containing a title
+
 ```ts
 const library = await plex.library();
 const section = await library.section<MovieSection>('Movies');
@@ -45,6 +47,7 @@ const results = await section.search({ title: 'Rush Hour' });
 ```
 
 ###### Example 3: List all content containing a specific query
+
 ```ts
 const results = await plex.search('Arnold');
 // Each hub represents a single Hub (or category) in the PlexServer search (movie, actor, etc)
@@ -55,6 +58,7 @@ for (const hub of results) {
 ```
 
 ###### Example 4: List all episodes of a tv show.
+
 ```ts
 import { ShowSection } from '@ctrl/plex';
 
@@ -66,7 +70,8 @@ const episodes = await results[0].episodes();
 ```
 
 ### Differences from python plex client
-JS is a different language and some methods of the api were not possible. 
+
+JS is a different language and some methods of the api were not possible.
 Chaining functions with requests must be awaited mostly individually. Constructors in JS don't typically make requests
 and accessing properties normally cannot make requests either.
 
@@ -99,13 +104,13 @@ Post testing, remove plex server from account. Warning this is destructive. Do n
 npm run test-cleanup
 ```
 
-
 ### Running tests locally (mostly for myself)
 
 get a claim token from https://www.plex.tv/claim/
 export PLEX_CLAIM_TOKEN=claim-token
 
-start plex container for testing
+Start plex container for testing. Replace `/Users/scooper/gh/plex` with the path to this repo's directory.
+
 ```console
 docker run -d \
   --name=plex \
@@ -134,11 +139,13 @@ docker run -d \
 ```
 
 Pull latest plex container if needed
+
 ```console
 docker pull lscr.io/linuxserver/plex:latest
 ```
 
-bootstrap plex server with test media
+bootstrap plex server with test media. This assumes you have set the `PLEX_PASSWORD` and `PLEX_USERNAME` environment variables.
+
 ```console
-NODE_OPTIONS="--loader ts-node/esm" node scripts/bootstraptest.ts --no-docker --server-name=orbstack --password=$PLEX_PASSWORD --username=$PLEX_USERNAME
+npx tsx scripts/bootstraptest.ts --no-docker --server-name=orbstack --password=$PLEX_PASSWORD --username=$PLEX_USERNAME
 ```

package/dist/src/audio.d.ts

@@ -0,0 +1,295 @@
+import { PartialPlexObject } from './base/partialPlexObject.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';
+import type { PlexServer } from './server.js';
+/**
+ * Base class for all audio objects including Artist, Album, and Track.
+ */
+export declare class Audio extends PartialPlexObject {
+    /** Default metadata type for audio sync items. */
+    static METADATA_TYPE: string;
+    /** Hardcoded list type for filtering. */
+    get listType(): 'audio';
+    addedAt?: Date;
+    art?: string;
+    artBlurHash?: string;
+    /** Sonic distance from a seed item, used in sonically similar results. */
+    distance?: number;
+    guid?: string;
+    /** Plex index number (often the track number for tracks). */
+    index?: number;
+    lastRatedAt?: Date;
+    lastViewedAt?: Date;
+    /** Key of the library section this item belongs to. */
+    librarySectionKey?: string;
+    /** Title of the library section this item belongs to. */
+    librarySectionTitle?: string;
+    /** Plex music analysis version (1 indicates sonic analysis complete). */
+    musicAnalysisVersion?: number;
+    summary?: string;
+    thumb?: string;
+    thumbBlurHash?: string;
+    /** Title used for sorting (defaults to title). */
+    titleSort?: string;
+    updatedAt?: Date;
+    /** User rating (0.0-10.0). */
+    userRating?: number;
+    /** Count of times the item was played. */
+    viewCount?: number;
+    /** Store the raw data from the Plex API for lazy loading related items. */
+    protected _data?: any;
+    /** List of field objects. */
+    fields?: Field[];
+    /** List of image objects. */
+    images?: Image[];
+    /** List of mood objects. */
+    moods?: Mood[];
+    /**
+     * @protected Should not be called directly. Use `server.fetchItem()`.
+     * Initializes a new instance of the Audio class.
+     * @param server The PlexServer instance used for communication.
+     * @param data The raw data object received from the Plex API.
+     * @param initpath The path used to fetch this item initially.
+     */
+    constructor(server: PlexServer, data: any, initpath: string | undefined, parent: PlexObject | undefined);
+    /**
+     * Returns the full URL for a given part (like a media stream) relative to the item's key.
+     * Includes the authentication token.
+     * @param part The relative path or resource identifier.
+     * @returns The full URL string including the server address and token, or undefined if part is empty.
+     */
+    url(part: string): string | undefined;
+    /** Indicates if the audio item has undergone sonic analysis. */
+    get hasSonicAnalysis(): boolean;
+    /**
+     * Fetches a list of sonically similar audio items from the Plex server.
+     * The returned items will be instances of the same class as the current item
+     * (e.g., calling `sonicallySimilar` on a `Track` instance returns `Track[]`).
+     * @param limit Maximum number of similar items to return. Server default is 50.
+     * @param maxDistance Maximum sonic distance (0.0 - 1.0) between items. Server default is 0.25.
+     * @param options Optional additional filters to apply to the results.
+     * @returns A promise resolving to an array of sonically similar Audio items.
+     */
+    sonicallySimilar(limit?: number, maxDistance?: number, options?: Record<string, string | number>): Promise<Audio[]>;
+    /**
+     * Provides a default title for Sync operations based on the item's title.
+     * @returns The item's title, or undefined if the title is not set.
+     * @protected
+     */
+    protected _defaultSyncTitle(): string | undefined;
+    /**
+     * Populates the object's properties from the provided Plex API data.
+     * This method is called by the constructor and _loadFullData.
+     * @param data The raw data object from the Plex API.
+     * @protected
+     */
+    protected _loadData(data: Record<string, any>): void;
+    /**
+     * Overrides `PartialPlexObject._loadFullData` to apply Audio-specific attributes
+     * after fetching the full item data.
+     * @param data The raw data object representing the full item from the Plex API.
+     * @protected
+     */
+    protected _loadFullData(data: any): void;
+}
+/**
+ * Represents a single Track.
+ */
+export declare class Track extends Audio {
+    static TAG: string;
+    static TYPE: string;
+    audienceRating?: number;
+    chapterSource?: string;
+    duration?: number;
+    grandparentArt?: string;
+    grandparentGuid?: string;
+    grandparentKey?: string;
+    grandparentRatingKey?: number;
+    grandparentTheme?: string;
+    grandparentThumb?: string;
+    grandparentTitle?: string;
+    originalTitle?: string;
+    parentGuid?: string;
+    parentIndex?: number;
+    parentKey?: string;
+    parentRatingKey?: number;
+    parentThumb?: string;
+    parentTitle?: string;
+    primaryExtraKey?: string;
+    rating?: number;
+    skipCount?: number;
+    sourceURI?: string;
+    viewOffset?: number;
+    chapters?: Chapter[];
+    collections?: Collection[];
+    genres?: Genre[];
+    guids?: Guid[];
+    labels?: Label[];
+    media?: Media[];
+    constructor(server: PlexServer, data: any, initpath: string | undefined, parent: PlexObject | undefined);
+    /**
+     * @returns List of file paths where the track is found on disk.
+     */
+    get locations(): string[];
+    /**
+     * @returns The track number.
+     */
+    get trackNumber(): number | undefined;
+    /**
+     * @returns A filename for use in download.
+     */
+    prettyfilename(): string;
+    /**
+     * Return the track's Album.
+     */
+    album(): Promise<Album>;
+    /**
+     * Return the track's Artist.
+     */
+    artist(): Promise<Artist>;
+    /**
+     * @returns Default title for a new syncItem.
+     */
+    _defaultSyncTitle(): string;
+    /**
+     * Returns the Plex Web URL pointing to the album details page for this track.
+     */
+    getWebURL(base?: string): string;
+    /**
+     * Returns a sonic adventure from the current track to the specified track.
+     * @param to The target track for the sonic adventure.
+     */
+    sonicAdventure(to: Track): Promise<Track[]>;
+    /**
+     * Populates the object's properties from the provided Plex API data,
+     * overriding the base Audio class method to add Track-specific attributes.
+     * @param data The raw data object from the Plex API.
+     * @protected
+     */
+    _loadData(data: TrackData): void;
+}
+/**
+ * Represents a single Artist.
+ */
+export declare class Artist extends Audio {
+    static TAG: string;
+    static TYPE: string;
+    albumSort?: number;
+    audienceRating?: number;
+    rating?: number;
+    theme?: string;
+    countries?: Country[];
+    genres?: Genre[];
+    guids?: Guid[];
+    labels?: Label[];
+    similar?: Similar[];
+    styles?: Style[];
+    collections?: Collection[];
+    get locations(): string[];
+    constructor(server: PlexServer, data: any, initpath?: string, parent?: PlexObject);
+    /**
+     * Returns a list of Album objects by the artist.
+     * @param options Additional search options.
+     */
+    albums(options?: Record<string, unknown>): Promise<Album[]>;
+    /**
+     * Returns the Album that matches the specified title for this artist.
+     * Case-insensitive exact match on title.
+     */
+    album(title: string): Promise<Album | undefined>;
+    /**
+     * Returns the Track that matches the specified criteria.
+     * @param title Title of the track.
+     * @param album Album name (required if title not specified).
+     * @param track Track number (required if title not specified).
+     */
+    track(args: {
+        title: string;
+    } | {
+        album: string;
+        track: number;
+    }): Promise<Track | undefined>;
+    /**
+     * Returns a list of Track objects by the artist.
+     * @param options Additional fetch options.
+     */
+    tracks(options?: Record<string, string | number>): Promise<Track[]>;
+    /** Alias of track(). */
+    get(args: {
+        title: string;
+    } | {
+        album: string;
+        track: number;
+    }): Promise<Track | undefined>;
+    popularTracks(): Promise<Track[]>;
+    /**
+     * Load attribute values from Plex XML response.
+     * @protected
+     */
+    _loadData(data: ArtistData): void;
+}
+/**
+ * Represents a single Album.
+ */
+export declare class Album extends Audio {
+    static TAG: string;
+    static TYPE: string;
+    audienceRating?: number;
+    collections?: Collection[];
+    formats?: Format[];
+    genres?: Genre[];
+    guids?: Guid[];
+    labels?: Label[];
+    leafCount?: number;
+    loudnessAnalysisVersion?: number;
+    originallyAvailableAt?: Date;
+    /**
+     * Artist GUID
+     */
+    parentGuid?: string;
+    /**
+     * Artist Key
+     */
+    parentKey?: string;
+    /**
+     * Artist Rating Key
+     */
+    parentRatingKey?: number;
+    /**
+     * Artist Theme
+     */
+    parentTheme?: string;
+    /**
+     * Artist Thumb
+     */
+    parentThumb?: string;
+    /**
+     * Artist Title
+     */
+    parentTitle?: string;
+    rating?: number;
+    studio?: string;
+    styles?: Style[];
+    subformats?: Subformat[];
+    viewedLeafCount?: number;
+    constructor(server: PlexServer, data: any, initpath: string | undefined, parent: PlexObject | undefined);
+    /**
+     * Returns a list of Track objects in the album.
+     * @param options Additional fetch options.
+     */
+    tracks(options?: Record<string, string | number>): Promise<Track[]>;
+    /**
+     * Return the album's Artist.
+     */
+    artist(): Promise<Artist>;
+    /**
+     * Returns the default title for a sync item.
+     */
+    _defaultSyncTitle(): string;
+    /**
+     * Load attribute values from Plex XML response.
+     * @protected
+     */
+    _loadData(data: AlbumData): void;
+}