@ctrl/plex 3.7.0 → 3.9.0

package/dist/src/playqueue.js

@@ -0,0 +1,268 @@
+import { PlexObject } from './base/plexObject.js';
+import { findItems } from './baseFunctionality.js';
+import { BadRequest } from './exceptions.js';
+/**
+ * Control a PlayQueue.
+ *
+ * A PlayQueue is a linear list of media items that can be played in sequence.
+ * It represents the current playback queue and supports operations like adding,
+ * 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'; }
+    /**
+     * Retrieve an existing PlayQueue by identifier.
+     */
+    static async get(server, playQueueID, options = {}) {
+        const { own = false, center, window = 50, includeBefore = true, includeAfter = true } = options;
+        const args = {
+            own: own ? 1 : 0,
+            window,
+            includeBefore: includeBefore ? 1 : 0,
+            includeAfter: includeAfter ? 1 : 0,
+        };
+        if (center !== undefined) {
+            args.center = center;
+        }
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+            params.set(key, value.toString());
+        }
+        const path = `/playQueues/${playQueueID}?${params.toString()}`;
+        const data = await server.query(path, 'get');
+        const playQueue = new PlayQueue(server, data.MediaContainer, path);
+        return playQueue;
+    }
+    /**
+     * Create and return a new PlayQueue.
+     */
+    static async create(server, items, options = {}) {
+        const { startItem, shuffle = false, repeat = false, includeChapters = true, includeRelated = true, continuous = false, } = options;
+        const args = {
+            includeChapters: includeChapters ? 1 : 0,
+            includeRelated: includeRelated ? 1 : 0,
+            repeat: repeat ? 1 : 0,
+            shuffle: shuffle ? 1 : 0,
+            continuous: continuous ? 1 : 0,
+        };
+        if (Array.isArray(items)) {
+            const itemKeys = items.map(x => x.ratingKey).join(',');
+            const uriArgs = encodeURIComponent(`/library/metadata/${itemKeys}`);
+            args.uri = `library:///directory/${uriArgs}`;
+            args.type = items[0].listType;
+        }
+        else if (items.type === 'playlist') {
+            const playlist = items;
+            args.type = playlist.playlistType;
+            args.playlistID = playlist.ratingKey;
+        }
+        else {
+            const item = items;
+            args.type = item.listType;
+            const library = await server.library();
+            args.uri = `server://${server.machineIdentifier}/${library.identifier}${item.key}`;
+        }
+        if (startItem) {
+            args.key = startItem.key;
+        }
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+            params.set(key, value.toString());
+        }
+        const path = `/playQueues?${params.toString()}`;
+        const data = await server.query(path, 'post');
+        const playQueue = new PlayQueue(server, data.MediaContainer, path);
+        return playQueue;
+    }
+    /**
+     * Create and return a new PlayQueue from a station key.
+     * This is a convenience method for radio stations.
+     */
+    static async fromStationKey(server, key) {
+        const library = await server.library();
+        const args = {
+            type: 'audio',
+            uri: `server://${server.machineIdentifier}/${library.identifier}${key}`,
+        };
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+            params.set(key, value.toString());
+        }
+        const path = `/playQueues?${params.toString()}`;
+        const data = await server.query(path, 'post');
+        const playQueue = new PlayQueue(server, data.MediaContainer, path);
+        return playQueue;
+    }
+    /**
+     * Get items in the PlayQueue.
+     */
+    get items() {
+        if (this._items === null) {
+            this._items = findItems(this._data?.Metadata ?? [], {}, undefined, this.server, this);
+            // Set selectedItem based on the offset now that items are loaded
+            if (this.playQueueSelectedItemOffset >= 0 &&
+                this._items.length > this.playQueueSelectedItemOffset &&
+                !this.selectedItem) {
+                this.selectedItem = this._items[this.playQueueSelectedItemOffset];
+            }
+        }
+        return this._items;
+    }
+    /**
+     * Get item at specific index.
+     */
+    getItem(index) {
+        return this.items[index] || null;
+    }
+    /**
+     * Get the length of the PlayQueue.
+     */
+    get length() {
+        return this.playQueueTotalCount;
+    }
+    /**
+     * Check if the PlayQueue contains the provided media item.
+     */
+    contains(media) {
+        return this.items.some(x => x.playQueueItemID === media.playQueueItemID);
+    }
+    /**
+     * Get a similar object from this PlayQueue.
+     * Useful for looking up playQueueItemIDs using items from the Library.
+     */
+    getQueueItem(item) {
+        const matches = this.items.filter(x => x.ratingKey === item.ratingKey);
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        else if (matches.length > 1) {
+            throw new BadRequest(`${item.title} occurs multiple times in this PlayQueue, provide exact item`);
+        }
+        else {
+            throw new BadRequest(`${item.title} not valid for this PlayQueue`);
+        }
+    }
+    /**
+     * Append an item to the "Up Next" section of the PlayQueue.
+     */
+    async addItem(item, options = {}) {
+        const { playNext = false, refresh = true } = options;
+        if (refresh) {
+            await this.refresh();
+        }
+        const args = {};
+        if (item.type === 'playlist') {
+            const playlist = item;
+            args.playlistID = playlist.ratingKey;
+        }
+        else {
+            const playableItem = item;
+            const section = await playableItem.section();
+            args.uri = `library://${section.uuid}/item${playableItem.key}`;
+        }
+        if (playNext) {
+            args.next = 1;
+        }
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(args)) {
+            params.set(key, value.toString());
+        }
+        const path = `/playQueues/${this.playQueueID}?${params.toString()}`;
+        const data = await this.server.query(path, 'put');
+        this._invalidateCacheAndLoadData(data.MediaContainer);
+        return this;
+    }
+    /**
+     * Move an item to the beginning of the PlayQueue.
+     * If 'after' is provided, the item will be placed immediately after the specified item.
+     */
+    async moveItem(item, options = {}) {
+        const { after, refresh = true } = options;
+        if (refresh) {
+            await this.refresh();
+        }
+        const args = {};
+        let queueItem = item;
+        if (!this.contains(item)) {
+            queueItem = this.getQueueItem(item);
+        }
+        if (after) {
+            let afterItem = after;
+            if (!this.contains(after)) {
+                afterItem = this.getQueueItem(after);
+            }
+            args.after = afterItem.playQueueItemID;
+        }
+        let path = `/playQueues/${this.playQueueID}/items/${queueItem.playQueueItemID}/move`;
+        if (Object.keys(args).length > 0) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(args)) {
+                params.set(key, value.toString());
+            }
+            path += `?${params.toString()}`;
+        }
+        const data = await this.server.query(path, 'put');
+        this._invalidateCacheAndLoadData(data.MediaContainer);
+        return this;
+    }
+    /**
+     * Remove an item from the PlayQueue.
+     */
+    async removeItem(item, refresh = true) {
+        if (refresh) {
+            await this.refresh();
+        }
+        let queueItem = item;
+        if (!this.contains(item)) {
+            queueItem = this.getQueueItem(item);
+        }
+        const path = `/playQueues/${this.playQueueID}/items/${queueItem.playQueueItemID}`;
+        const data = await this.server.query(path, 'delete');
+        this._invalidateCacheAndLoadData(data.MediaContainer);
+        return this;
+    }
+    /**
+     * Remove all items from the PlayQueue.
+     */
+    async clear() {
+        const path = `/playQueues/${this.playQueueID}/items`;
+        const data = await this.server.query(path, 'delete');
+        this._invalidateCacheAndLoadData(data.MediaContainer);
+        return this;
+    }
+    /**
+     * Refresh the PlayQueue from the Plex server.
+     */
+    async refresh() {
+        const path = `/playQueues/${this.playQueueID}`;
+        const data = await this.server.query(path, 'get');
+        this._invalidateCacheAndLoadData(data.MediaContainer);
+    }
+    _loadData(data) {
+        this._data = data; // Store raw data for items access
+        this.identifier = data.identifier;
+        this.mediaTagPrefix = data.mediaTagPrefix;
+        this.mediaTagVersion = data.mediaTagVersion;
+        this.playQueueID = data.playQueueID;
+        this.playQueueLastAddedItemID = data.playQueueLastAddedItemID;
+        this.playQueueSelectedItemID = data.playQueueSelectedItemID;
+        this.playQueueSelectedItemOffset = data.playQueueSelectedItemOffset;
+        this.playQueueSelectedMetadataItemID = data.playQueueSelectedMetadataItemID;
+        this.playQueueShuffled = data.playQueueShuffled;
+        this.playQueueSourceURI = data.playQueueSourceURI;
+        this.playQueueTotalCount = data.playQueueTotalCount;
+        this.playQueueVersion = data.playQueueVersion;
+        this.size = data.size || this.playQueueTotalCount;
+        // selectedItem will be set lazily when accessing items
+    }
+    _invalidateCacheAndLoadData(data) {
+        this._items = null; // Clear cached items
+        this._loadData(data);
+    }
+}

package/dist/src/playqueue.types.d.ts

@@ -0,0 +1,67 @@
+import type { Playable } from './base/playable.js';
+export interface PlayQueueResponse {
+    /** PlayQueue identifier */
+    identifier: string;
+    /** Media tag prefix path */
+    mediaTagPrefix: string;
+    /** Media tag version number */
+    mediaTagVersion: number;
+    /** Unique ID of the PlayQueue */
+    playQueueID: number;
+    /** ID of the last added item, defines where "Up Next" region starts */
+    playQueueLastAddedItemID?: number;
+    /** The queue item ID of the currently selected item */
+    playQueueSelectedItemID: number;
+    /** The offset of the selected item in the PlayQueue */
+    playQueueSelectedItemOffset: number;
+    /** ID of the currently selected item, matches ratingKey */
+    playQueueSelectedMetadataItemID: number;
+    /** True if the PlayQueue is shuffled */
+    playQueueShuffled: boolean;
+    /** Original URI used to create the PlayQueue */
+    playQueueSourceURI: string;
+    /** Total number of items in the PlayQueue */
+    playQueueTotalCount: number;
+    /** Version of the PlayQueue, increments on changes */
+    playQueueVersion: number;
+    /** Total size of the PlayQueue (alias for playQueueTotalCount) */
+    size: number;
+}
+export interface CreatePlayQueueOptions {
+    /** Media item in the PlayQueue where playback should begin */
+    startItem?: Playable;
+    /** Start the playqueue shuffled */
+    shuffle?: boolean;
+    /** Start the playqueue with repeat enabled */
+    repeat?: boolean;
+    /** Include chapters */
+    includeChapters?: boolean;
+    /** Include related content */
+    includeRelated?: boolean;
+    /** Include additional items after the initial item */
+    continuous?: boolean;
+}
+export interface GetPlayQueueOptions {
+    /** If server should transfer ownership */
+    own?: boolean;
+    /** The playQueueItemID of the center of the window */
+    center?: number;
+    /** Number of items to return from each side of the center item */
+    window?: number;
+    /** Include items before the center */
+    includeBefore?: boolean;
+    /** Include items after the center */
+    includeAfter?: boolean;
+}
+export interface AddPlayQueueItemOptions {
+    /** If true, add item to front of "Up Next" section */
+    playNext?: boolean;
+    /** Refresh the PlayQueue from server before updating */
+    refresh?: boolean;
+}
+export interface MovePlayQueueItemOptions {
+    /** Item to place the moved item after */
+    after?: Playable;
+    /** Refresh the PlayQueue from server before updating */
+    refresh?: boolean;
+}

package/dist/src/playqueue.types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/server.d.ts

@@ -1,8 +1,12 @@
 import { URL, URLSearchParams } from 'url';
+import { Playable } from './base/playable.js';
 import { PlexClient } from './client.js';
 import { Hub, Library } from './library.js';
 import { Optimized } from './media.js';
 import { MyPlexAccount } from './myplex.js';
+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 { Settings } from './settings.js';
@@ -188,6 +192,14 @@ export declare class PlexServer {
      */
     history(maxresults?: number, mindate?: Date, ratingKey?: number | string, accountId?: number | string, librarySectionId?: number | string): Promise<HistoryMetadatum[]>;
     settings(): Promise<Settings>;
+    /**
+     * Creates and returns a new PlayQueue.
+     *
+     * @param item Media item or playlist to add to PlayQueue
+     * @param options Creation options for the PlayQueue
+     * @returns New PlayQueue instance
+     */
+    createPlayQueue(item: Playable | Playable[] | Playlist, options?: CreatePlayQueueOptions): Promise<PlayQueue>;
     /**
      * Returns a :class:`~plexapi.myplex.MyPlexAccount` object using the same
      * token to access this server. If you are not the owner of this PlexServer

package/dist/src/server.js

@@ -6,6 +6,7 @@ import { BASE_HEADERS, TIMEOUT, X_PLEX_CONTAINER_SIZE } from './config.js';
 import { Hub, Library } from './library.js';
 import { Optimized } from './media.js';
 import { MyPlexAccount } from './myplex.js';
+import { PlayQueue } from './playqueue.js';
 import { Agent, SEARCHTYPES } from './search.js';
 import { Settings } from './settings.js';
 /**
@@ -178,6 +179,16 @@ export class PlexServer {
     //   const data = this.query('/playlists');
     //   console.log(JSON.stringify(data));
     // }
+    /**
+     * Creates and returns a new PlayQueue.
+     *
+     * @param item Media item or playlist to add to PlayQueue
+     * @param options Creation options for the PlayQueue
+     * @returns New PlayQueue instance
+     */
+    async createPlayQueue(item, options = {}) {
+        return PlayQueue.create(this, item, options);
+    }
     /**
      * Returns a :class:`~plexapi.myplex.MyPlexAccount` object using the same
      * token to access this server. If you are not the owner of this PlexServer

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.9.0",
+  "description": "plex api client in typescript using ofetch",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "publishConfig": {
     "access": "public"