@ctrl/plex 3.7.0 → 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
 
@@ -110,7 +109,7 @@ npm run test-cleanup
 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 \
@@ -145,8 +144,8 @@ Pull latest plex container if needed
 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;
+}