@ctrl/plex 3.12.1 → 4.0.0

package/dist/src/media.js

@@ -50,7 +50,7 @@ export class MediaPart extends PlexObject {
         const params = new URLSearchParams({ allParts: '1' });
         const streamId = typeof stream === 'number' ? stream : stream.id;
         params.set('audioStreamID', streamId.toString());
-        await this.server.query(`${key}?${params.toString()}`, 'put');
+        await this.server.query({ path: `${key}?${params.toString()}`, method: 'put' });
         return this;
     }
     /**
@@ -62,7 +62,7 @@ export class MediaPart extends PlexObject {
         const params = new URLSearchParams({ allParts: '1' });
         const streamId = typeof stream === 'number' ? stream : stream.id;
         params.set('subtitleStreamID', streamId.toString());
-        await this.server.query(`${key}?${params.toString()}`, 'put');
+        await this.server.query({ path: `${key}?${params.toString()}`, method: 'put' });
         return this;
     }
     /**
@@ -255,7 +255,7 @@ export class Optimized extends PlexObject {
      */
     async remove() {
         const key = `${this.key}/${this.id}`;
-        await this.server.query(key, 'delete');
+        await this.server.query({ path: key, method: 'delete' });
     }
     /**
      * Rename this Optimized item.
@@ -263,7 +263,7 @@ export class Optimized extends PlexObject {
      */
     async rename(title) {
         const key = `${this.key}/${this.id}?Item[title]=${encodeURIComponent(title)}`;
-        await this.server.query(key, 'put');
+        await this.server.query({ path: key, method: 'put' });
     }
     /**
      * Reprocess a removed Conversion item that is still a listed Optimize item.
@@ -271,7 +271,7 @@ export class Optimized extends PlexObject {
      */
     async reprocess(ratingKey) {
         const key = `${this.key}/${this.id}/${ratingKey}/enable`;
-        await this.server.query(key, 'put');
+        await this.server.query({ path: key, method: 'put' });
     }
     _loadData(data) {
         this.id = data.id;
@@ -312,7 +312,7 @@ class BaseResource extends PlexObject {
         const key = this.key.slice(0, -1);
         const params = new URLSearchParams();
         params.append('url', this.ratingKey);
-        return this.server.query(`${key}?${params.toString()}`, 'put');
+        return this.server.query({ path: `${key}?${params.toString()}`, method: 'put' });
     }
     resourceFilepath() {
         if (this.ratingKey.startsWith('media://')) {
@@ -437,7 +437,7 @@ export class Image extends PlexObject {
         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;
+        this.url = data.url ? this.server.url(data.url, { includeToken: true })?.toString() : undefined;
     }
 }
 /** Represents a single Field. */

package/dist/src/myplex.d.ts

@@ -9,12 +9,6 @@ import { PlexServer } from './server.js';
  * and return this object.
  */
 export declare class MyPlexAccount {
-    baseUrl: string | null;
-    username?: string;
-    password?: string;
-    token?: string;
-    timeout: number;
-    server?: PlexServer;
     static key: string;
     /**
      * This follows the outline described in https://forums.plex.tv/t/authenticating-with-plex/609370
@@ -28,7 +22,9 @@ export declare class MyPlexAccount {
      * Pass in the `webLogin` object obtained from `getWebLogin()` and this will poll Plex to see if
      * the user agreed. It returns a connected `MyPlexAccount` or throws an error.
      */
-    static webLoginCheck(webLogin: WebLogin, timeoutSeconds?: number): Promise<MyPlexAccount>;
+    static webLoginCheck(webLogin: WebLogin, { timeoutSeconds }?: {
+        timeoutSeconds?: number;
+    }): Promise<MyPlexAccount>;
     FRIENDINVITE: string;
     HOMEUSERCREATE: string;
     EXISTINGUSER: string;
@@ -86,16 +82,23 @@ export declare class MyPlexAccount {
     subscriptionFeatures?: string[];
     /** List of devices your allowed to use with this account */
     entitlements?: string[];
+    baseUrl: string | null;
+    username?: string;
+    password?: string;
+    token?: string;
+    timeout: number;
+    server?: PlexServer;
     /**
-     *
-     * @param username Your MyPlex username
-     * @param password Your MyPlex password
-     * @param token Token used to access this client.
-     * @param session Use your own session object if you want to cache the http responses from PMS
-     * @param timeout timeout in seconds on initial connect to myplex
-     * @param server not often available
+     * @param options Connection + auth options.
      */
-    constructor(baseUrl?: string | null, username?: string, password?: string, token?: string, timeout?: number, server?: PlexServer);
+    constructor({ baseUrl, username, password, token, timeout, server, }?: {
+        baseUrl?: string | null;
+        username?: string;
+        password?: string;
+        token?: string;
+        timeout?: number;
+        server?: PlexServer;
+    });
     /**
      * Returns a new :class:`~server.PlexServer` or :class:`~client.PlexClient` object.
      * Often times there is more than one address specified for a server or client.
@@ -124,11 +127,15 @@ export declare class MyPlexAccount {
      * ElementTree object. Returns None if no data exists in the response.
      * TODO: use headers
      * @param path
-     * @param method
-     * @param headers
-     * @param timeout
+     * @param options
      */
-    query<T = any>(url: string, method?: 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete', headers?: any, username?: string, password?: string): Promise<T>;
+    query<T = any>({ url, method, headers, username, password, }: {
+        url: string;
+        method?: 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
+        headers?: any;
+        username?: string;
+        password?: string;
+    }): Promise<T>;
     /**
      * Returns a str, a new "claim-token", which you can use to register your new Plex Server instance to your account.
      * @link https://hub.docker.com/r/plexinc/pms-docker/

package/dist/src/myplex.js

@@ -13,12 +13,6 @@ import { PlexServer } from './server.js';
  * and return this object.
  */
 export class MyPlexAccount {
-    baseUrl;
-    username;
-    password;
-    token;
-    timeout;
-    server;
     static key = 'https://plex.tv/api/v2/user';
     /**
      * This follows the outline described in https://forums.plex.tv/t/authenticating-with-plex/609370
@@ -50,7 +44,7 @@ export class MyPlexAccount {
      * Pass in the `webLogin` object obtained from `getWebLogin()` and this will poll Plex to see if
      * the user agreed. It returns a connected `MyPlexAccount` or throws an error.
      */
-    static async webLoginCheck(webLogin, timeoutSeconds = 60) {
+    static async webLoginCheck(webLogin, { timeoutSeconds = 60 } = {}) {
         const recheckMs = 3000;
         const clientIdentifier = BASE_HEADERS['X-Plex-Client-Identifier'];
         const uri = `https://plex.tv/api/v2/pins/${webLogin.id}`;
@@ -71,7 +65,7 @@ export class MyPlexAccount {
                     retryDelay: recheckMs,
                 });
                 if (tokenResponse.authToken) {
-                    const myPlexAccount = new MyPlexAccount(null, '', '', tokenResponse.authToken);
+                    const myPlexAccount = new MyPlexAccount({ token: tokenResponse.authToken });
                     return await myPlexAccount.connect();
                 }
                 await sleep(recheckMs);
@@ -97,16 +91,16 @@ export class MyPlexAccount {
     REQUESTS = 'https://plex.tv/api/invites/requests'; // get
     SIGNIN = 'https://plex.tv/users/sign_in.json'; // get with auth
     WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'; // get, post with data
+    baseUrl = null;
+    username;
+    password;
+    token;
+    timeout = TIMEOUT;
+    server;
     /**
-     *
-     * @param username Your MyPlex username
-     * @param password Your MyPlex password
-     * @param token Token used to access this client.
-     * @param session Use your own session object if you want to cache the http responses from PMS
-     * @param timeout timeout in seconds on initial connect to myplex
-     * @param server not often available
+     * @param options Connection + auth options.
      */
-    constructor(baseUrl = null, username, password, token, timeout = TIMEOUT, server) {
+    constructor({ baseUrl = null, username, password, token, timeout = TIMEOUT, server, } = {}) {
         this.baseUrl = baseUrl;
         this.username = username;
         this.password = password;
@@ -141,7 +135,7 @@ export class MyPlexAccount {
             this._loadData(data);
             return this;
         }
-        const data = await this.query(MyPlexAccount.key);
+        const data = await this.query({ url: MyPlexAccount.key });
         this._loadData(data);
         return this;
     }
@@ -157,7 +151,7 @@ export class MyPlexAccount {
         throw new Error(`Unable to find resource ${name}`);
     }
     async resources() {
-        const data = await this.query(MyPlexResource.key);
+        const data = await this.query({ url: MyPlexResource.key });
         return data.map(device => new MyPlexResource(this, device, this.baseUrl));
     }
     /**
@@ -176,7 +170,9 @@ export class MyPlexAccount {
      * Returns a list of all :class:`~plexapi.myplex.MyPlexDevice` objects connected to the server.
      */
     async devices() {
-        const response = await this.query(MyPlexDevice.key);
+        const response = await this.query({
+            url: MyPlexDevice.key,
+        });
         return response.MediaContainer.Device.map(data => new MyPlexDevice(this.server, data));
     }
     /**
@@ -185,16 +181,17 @@ export class MyPlexAccount {
      * ElementTree object. Returns None if no data exists in the response.
      * TODO: use headers
      * @param path
-     * @param method
-     * @param headers
-     * @param timeout
+     * @param options
      */
-    async query(url, method = 'get', headers, username, password) {
+    async query({ url, method = 'get', headers, username, password, }) {
         const requestHeaders = this._headers();
         if (username && password) {
             const credentials = Buffer.from(`${username}:${password}`).toString('base64');
             requestHeaders.Authorization = `Basic ${credentials}`;
         }
+        if (headers) {
+            Object.assign(requestHeaders, headers);
+        }
         if (!url.includes('xml')) {
             requestHeaders.accept = 'application/json';
         }
@@ -220,7 +217,7 @@ export class MyPlexAccount {
      */
     async claimToken() {
         const url = 'https://plex.tv/api/claim/token.json';
-        const response = await this.query(url, 'get');
+        const response = await this.query({ url });
         return response.token;
     }
     /**
@@ -250,7 +247,12 @@ export class MyPlexAccount {
         return headers;
     }
     async _signin(username, password) {
-        const data = await this.query(this.SIGNIN, 'post', undefined, username, password);
+        const data = await this.query({
+            url: this.SIGNIN,
+            method: 'post',
+            username,
+            password,
+        });
         return data.user;
     }
     _loadData(user) {
@@ -397,7 +399,7 @@ export class MyPlexDevice extends PlexObject {
      */
     async delete() {
         const key = `https://plex.tv/devices/${this.id}.xml`;
-        await this.server.query(key, 'delete');
+        await this.server.query({ path: key, method: 'delete' });
     }
     _loadData(data) {
         this.name = data.$.name;

package/dist/src/playlist.js

@@ -65,7 +65,7 @@ export class Playlist extends Playable {
             params.set('summary', options.summary);
         }
         const key = `/playlists/${ratingKey}?${params.toString()}`;
-        await server.query(key, 'put');
+        await server.query({ path: key, method: 'put' });
     }
     /** Create a smart playlist. */
     // private static _createSmart(server: PlexServer, title: string, options: CreatePlaylistOptions) {}
@@ -83,7 +83,7 @@ export class Playlist extends Playable {
             smart: '0',
         });
         const key = `/playlists?${params.toString()}`;
-        const data = await server.query(key, 'post');
+        const data = await server.query({ path: key, method: 'post' });
         return new Playlist(server, data.MediaContainer.Metadata[0], key);
     }
     TYPE = 'playlist';
@@ -92,7 +92,7 @@ export class Playlist extends Playable {
     async _edit(args) {
         const searchparams = new URLSearchParams(args);
         const key = `${this.key}?${searchparams.toString()}`;
-        await this.server.query(key, 'put');
+        await this.server.query({ path: key, method: 'put' });
     }
     async edit(changeObj) {
         await this._edit(changeObj);
@@ -130,7 +130,7 @@ export class Playlist extends Playable {
             uri: `${this.server._uriRoot()}/library/metadata/${ratingKeys.join(',')}`,
         });
         const key = `${this.key}/items?${params.toString()}`;
-        await this.server.query(key, 'put');
+        await this.server.query({ path: key, method: 'put' });
     }
     /** Remove an item from a playlist. */
     async removeItems(items) {
@@ -140,12 +140,12 @@ export class Playlist extends Playable {
         for (const item of items) {
             const playlistItemId = await this._getPlaylistItemID(item);
             const key = `${this.key}/items/${playlistItemId}`;
-            await this.server.query(key, 'delete');
+            await this.server.query({ path: key, method: 'delete' });
         }
     }
     /** Delete the playlist. */
     async delete() {
-        await this.server.query(this.key, 'delete');
+        await this.server.query({ path: this.key, method: 'delete' });
     }
     _loadData(data) {
         this.key = data.key.replace('/items', '');

package/dist/src/playqueue.js

@@ -32,7 +32,7 @@ export class PlayQueue extends PlexObject {
             params.set(key, value.toString());
         }
         const path = `/playQueues/${playQueueID}?${params.toString()}`;
-        const data = await server.query(path, 'get');
+        const data = await server.query({ path });
         const playQueue = new PlayQueue(server, data.MediaContainer, path);
         return playQueue;
     }
@@ -73,7 +73,7 @@ export class PlayQueue extends PlexObject {
             params.set(key, value.toString());
         }
         const path = `/playQueues?${params.toString()}`;
-        const data = await server.query(path, 'post');
+        const data = await server.query({ path, method: 'post' });
         const playQueue = new PlayQueue(server, data.MediaContainer, path);
         return playQueue;
     }
@@ -92,7 +92,7 @@ export class PlayQueue extends PlexObject {
             params.set(key, value.toString());
         }
         const path = `/playQueues?${params.toString()}`;
-        const data = await server.query(path, 'post');
+        const data = await server.query({ path, method: 'post' });
         const playQueue = new PlayQueue(server, data.MediaContainer, path);
         return playQueue;
     }
@@ -171,7 +171,7 @@ export class PlayQueue extends PlexObject {
             params.set(key, value.toString());
         }
         const path = `/playQueues/${this.playQueueID}?${params.toString()}`;
-        const data = await this.server.query(path, 'put');
+        const data = await this.server.query({ path, method: 'put' });
         this._invalidateCacheAndLoadData(data.MediaContainer);
         return this;
     }
@@ -204,7 +204,7 @@ export class PlayQueue extends PlexObject {
             }
             path += `?${params.toString()}`;
         }
-        const data = await this.server.query(path, 'put');
+        const data = await this.server.query({ path, method: 'put' });
         this._invalidateCacheAndLoadData(data.MediaContainer);
         return this;
     }
@@ -220,7 +220,7 @@ export class PlayQueue extends PlexObject {
             queueItem = this.getQueueItem(item);
         }
         const path = `/playQueues/${this.playQueueID}/items/${queueItem.playQueueItemID}`;
-        const data = await this.server.query(path, 'delete');
+        const data = await this.server.query({ path, method: 'delete' });
         this._invalidateCacheAndLoadData(data.MediaContainer);
         return this;
     }
@@ -229,7 +229,7 @@ export class PlayQueue extends PlexObject {
      */
     async clear() {
         const path = `/playQueues/${this.playQueueID}/items`;
-        const data = await this.server.query(path, 'delete');
+        const data = await this.server.query({ path, method: 'delete' });
         this._invalidateCacheAndLoadData(data.MediaContainer);
         return this;
     }
@@ -238,7 +238,7 @@ export class PlayQueue extends PlexObject {
      */
     async refresh() {
         const path = `/playQueues/${this.playQueueID}`;
-        const data = await this.server.query(path, 'get');
+        const data = await this.server.query({ path });
         this._invalidateCacheAndLoadData(data.MediaContainer);
     }
     _loadData(data) {

package/dist/src/server.d.ts

@@ -8,7 +8,7 @@ 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 { HistoryResult } from './server.types.js';
+import type { HistoryResult, HistoryOptions } from './server.types.js';
 import { Settings } from './settings.js';
 /**
  * This is the main entry point to interacting with a Plex server. It allows you to
@@ -162,35 +162,37 @@ export declare class PlexServer {
      * 'Arnold' you’ll get a result for the actor, but also the most recently added
      * movies he’s in.
      * @param query Query to use when searching your library.
-     * @param mediatype Optionally limit your search to the specified media type.
-     * @param limit Optionally limit to the specified number of results per Hub.
+     * @param options Search options.
      */
-    search(query: string, mediatype?: keyof typeof SEARCHTYPES, limit?: number): Promise<Hub[]>;
+    search(query: string, { mediatype, limit, }?: {
+        /** Optionally limit your search to the specified media type. */
+        mediatype?: keyof typeof SEARCHTYPES;
+        /** Optionally limit to the specified number of results per Hub. */
+        limit?: number;
+    }): Promise<Hub[]>;
     /**
      * Main method used to handle HTTPS requests to the Plex server. This method helps
      * by encoding the response to utf-8 and parsing the returned XML into and
      * ElementTree object. Returns None if no data exists in the response.
      * TODO: use headers
-     * @param path
-     * @param method
-     * @param headers
+     * @param options
      */
-    query<T = any>(path: string, method?: 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete', options?: {
+    query<T = any>({ path, method, headers, body, username, password, }: {
+        path: string;
+        method?: 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
         headers?: Record<string, string>;
         body?: Uint8Array;
-    }, username?: string, password?: string): Promise<T>;
+        username?: string;
+        password?: string;
+    }): Promise<T>;
     /**
      * Returns a list of media items from watched history. If there are many results, they will
      * be fetched from the server in batches of X_PLEX_CONTAINER_SIZE amounts. If you're only
-     * looking for the first <num> results, it would be wise to set the maxresults option to that
+     * looking for the first <num> results, it would be wise to set the maxResults option to that
      * amount so this functions doesn't iterate over all results on the server.
-     * @param maxresults Only return the specified number of results (optional).
-     * @param mindate Min datetime to return results from. This really helps speed up the result listing. For example: datetime.now() - timedelta(days=7)
-     * @param ratingKey request history for a specific ratingKey item.
-     * @param accountId request history for a specific account ID.
-     * @param librarySectionId request history for a specific library section ID.
+     * @param options Filter and paging options.
      */
-    history(maxresults?: number, mindate?: Date, ratingKey?: number | string, accountId?: number | string, librarySectionId?: number | string): Promise<HistoryResult[]>;
+    history({ maxResults, minDate, ratingKey, accountId, librarySectionId, }?: HistoryOptions): Promise<HistoryResult[]>;
     settings(): Promise<Settings>;
     /**
      * Creates and returns a new PlayQueue.
@@ -213,15 +215,22 @@ export declare class PlexServer {
      * Build a URL string with proper token argument. Token will be appended to the URL
      * if either includeToken is True or TODO: CONFIG.log.show_secrets is 'true'.
      */
-    url(key: string, includeToken?: boolean, params?: URLSearchParams): URL;
+    url(key: string, { includeToken, params, }?: {
+        includeToken?: boolean;
+        params?: URLSearchParams;
+    }): URL;
     /**
      * Build the Plex Web URL for the object.
-     * @param base The base URL before the fragment (``#!``).
-     *    Default is https://app.plex.tv/desktop.
-     * @param endpoint The Plex Web URL endpoint.
-     *    None for server, 'playlist' for playlists, 'details' for all other media types.
-     */
-    _buildWebURL(base?: string, endpoint?: string, params?: URLSearchParams): string;
+     * @param options Options for the URL.
+     */
+    _buildWebURL({ base, endpoint, params, }?: {
+        /** The base URL before the fragment (``#!``). Default is https://app.plex.tv/desktop. */
+        base?: string;
+        /** The Plex Web URL endpoint. None for server, 'playlist' for playlists, 'details' for all other media types. */
+        endpoint?: string;
+        /** URL parameters to append. */
+        params?: URLSearchParams;
+    }): string;
     _uriRoot(): string;
     private _headers;
     private _loadData;