@ctrl/plex 3.12.0 → 4.0.0

package/dist/src/server.js

@@ -42,7 +42,7 @@ export class PlexServer {
         return fetchItems(this, key, undefined, Agent, this);
     }
     async connect() {
-        const data = await this.query(this.key);
+        const data = await this.query({ path: this.key });
         this._loadData(data.MediaContainer);
         // Attempt to prevent token from being logged accidentally
         if (this.token) {
@@ -60,12 +60,14 @@ export class PlexServer {
             return this._library;
         }
         try {
-            const data = await this.query(Library.key);
+            const data = await this.query({ path: Library.key });
             this._library = new Library(this, data.MediaContainer);
         }
         catch {
             // TODO: validate error type, also TODO figure out how this is used
-            const data = await this.query('/library/sections/');
+            const data = await this.query({
+                path: '/library/sections/',
+            });
             this._library = new Library(this, data.MediaContainer);
         }
         return this._library;
@@ -82,10 +84,9 @@ export 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.
      */
-    async search(query, mediatype, limit) {
+    async search(query, { mediatype, limit, } = {}) {
         const params = { query };
         if (mediatype) {
             params.section = SEARCHTYPES[mediatype].toString();
@@ -93,8 +94,9 @@ export class PlexServer {
         if (limit) {
             params.limit = limit.toString();
         }
-        const key = `/hubs/search?${new URLSearchParams(params).toString()}`;
-        const hubs = await fetchItems(this, key, undefined, Hub, this);
+        const url = new URL('/hubs/search', this.baseurl);
+        url.search = new URLSearchParams(params).toString();
+        const hubs = await fetchItems(this, url.pathname + url.search, undefined, Hub, this);
         return hubs;
     }
     /**
@@ -102,12 +104,10 @@ export class PlexServer {
      * 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
      */
-    async query(path, method = 'get', options = {}, username, password) {
-        const requestHeaders = this._headers();
+    async query({ path, method = 'get', headers, body, username, password, }) {
+        const requestHeaders = { ...this._headers(), ...headers };
         if (username && password) {
             const credentials = Buffer.from(`${username}:${password}`).toString('base64');
             requestHeaders.Authorization = `Basic ${credentials}`;
@@ -120,7 +120,7 @@ export class PlexServer {
             method,
             headers: requestHeaders,
             timeout: this.timeout ?? TIMEOUT,
-            body: options.body,
+            body,
             retry: 0,
             responseType: 'json',
         });
@@ -129,15 +129,11 @@ export class PlexServer {
     /**
      * 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.
      */
-    async history(maxresults = 9_999_999, mindate, ratingKey, accountId, librarySectionId) {
+    async history({ maxResults = 9_999_999, minDate, ratingKey, accountId, librarySectionId, } = {}) {
         const args = { sort: 'viewedAt:desc' };
         if (ratingKey !== undefined) {
             args.metadataItemID = ratingKey.toString();
@@ -148,24 +144,29 @@ export class PlexServer {
         if (librarySectionId !== undefined) {
             args.librarySectionID = librarySectionId.toString();
         }
-        if (mindate !== undefined) {
-            args['viewedAt>'] = Math.floor(mindate.getTime() / 1000).toString();
+        if (minDate !== undefined) {
+            args['viewedAt>'] = Math.floor(minDate.getTime() / 1000).toString();
         }
         args['X-Plex-Container-Start'] = '0';
-        args['X-Plex-Container-Size'] = Math.min(X_PLEX_CONTAINER_SIZE, maxresults).toString();
+        args['X-Plex-Container-Size'] = Math.min(X_PLEX_CONTAINER_SIZE, maxResults).toString();
         let results = [];
-        let key = `/status/sessions/history/all?${new URLSearchParams(args).toString()}`;
-        let raw = await this.query(key);
+        const url = new URL('/status/sessions/history/all', this.baseurl);
+        url.search = new URLSearchParams(args).toString();
+        let raw = await this.query({
+            path: url.pathname + url.search,
+        });
         const totalResults = raw.MediaContainer.totalSize;
         // Filter out null/undefined items from the metadata
         const validMetadata = raw.MediaContainer.Metadata?.filter(Boolean) ?? [];
         results.push(...validMetadata);
         while (results.length <= totalResults &&
             X_PLEX_CONTAINER_SIZE === raw.MediaContainer.size &&
-            maxresults > results.length) {
+            maxResults > results.length) {
             args['X-Plex-Container-Start'] = (Number(args['X-Plex-Container-Start']) + Number(args['X-Plex-Container-Size'])).toString();
-            key = `/status/sessions/history/all?${new URLSearchParams(args).toString()}`;
-            raw = await this.query(key);
+            url.search = new URLSearchParams(args).toString();
+            raw = await this.query({
+                path: url.pathname + url.search,
+            });
             // Filter out null/undefined items from the metadata
             const validMetadata = raw.MediaContainer.Metadata?.filter(item => item != null) ?? [];
             results.push(...validMetadata);
@@ -174,7 +175,9 @@ export class PlexServer {
     }
     async settings() {
         if (!this._settings) {
-            const data = await this.query(Settings.key);
+            const data = await this.query({
+                path: Settings.key,
+            });
             this._settings = new Settings(this, data.MediaContainer.Setting);
         }
         return this._settings;
@@ -206,14 +209,21 @@ export class PlexServer {
      */
     myPlexAccount() {
         if (!this._myPlexAccount) {
-            this._myPlexAccount = new MyPlexAccount(this.baseurl, undefined, undefined, this.token, this.timeout, this);
+            this._myPlexAccount = new MyPlexAccount({
+                baseUrl: this.baseurl,
+                token: this.token,
+                timeout: this.timeout,
+                server: this,
+            });
         }
         return this._myPlexAccount;
     }
     // Returns list of all :class:`~plexapi.client.PlexClient` objects connected to server.
     async clients() {
         const items = [];
-        const response = await this.query('/clients');
+        const response = await this.query({
+            path: '/clients',
+        });
         if (response.MediaContainer?.Server === undefined) {
             return [];
         }
@@ -243,7 +253,7 @@ export 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, includeToken = false, params) {
+    url(key, { includeToken = false, params, } = {}) {
         if (!this.baseurl) {
             throw new Error('PlexClient object missing baseurl.');
         }
@@ -254,20 +264,25 @@ export class PlexServer {
             url.search = searchParams.toString();
             return url;
         }
+        if (params) {
+            url.search = params.toString();
+        }
         return 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.
+     * @param options Options for the URL.
      */
-    _buildWebURL(base = 'https://app.plex.tv/desktop/', endpoint, params) {
+    _buildWebURL({ base = 'https://app.plex.tv/desktop/', endpoint, params, } = {}) {
+        const url = new URL(base);
+        const queryString = params?.toString() ? `?${params.toString()}` : '';
         if (endpoint) {
-            return `${base}#!/server/${this.machineIdentifier}/${endpoint}?${params?.toString()}`;
+            url.hash = `!/server/${this.machineIdentifier}/${endpoint}${queryString}`;
+        }
+        else {
+            url.hash = `!/media/${this.machineIdentifier}/com.plexapp.plugins.library${queryString}`;
         }
-        return `${base}#!/media/${this.machineIdentifier}/com.plexapp.plugins.library?${params?.toString()}`;
+        return url.toString();
     }
     _uriRoot() {
         return `server://${this.machineIdentifier}/com.plexapp.plugins.library`;

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

@@ -119,3 +119,15 @@ export interface ServerConnectionInfo {
     protocolVersion: string;
     protocolCapabilities: string;
 }
+export interface HistoryOptions {
+    /** Only return the specified number of results. */
+    maxResults?: number;
+    /** Min datetime to return results from. */
+    minDate?: Date;
+    /** Request history for a specific ratingKey item. */
+    ratingKey?: number | string;
+    /** Request history for a specific account ID. */
+    accountId?: number | string;
+    /** Request history for a specific library section ID. */
+    librarySectionId?: number | string;
+}

package/dist/src/settings.js

@@ -48,7 +48,7 @@ export class Settings extends PlexObject {
             }
         }
         const url = `${this.key}?${params.toString()}`;
-        await this.server.query(url, 'put');
+        await this.server.query({ path: url, method: 'put' });
     }
     _loadData(data) {
         this._data = data;

package/dist/src/util.d.ts

@@ -12,9 +12,10 @@ export declare function rsplit(str: string, sep: string, maxsplit: number): stri
  * Return the full agent identifier from a short identifier, name, or confirm full identifier.
  */
 export declare function getAgentIdentifier(section: Section, agent: string): Promise<string>;
-/**
- * Simple tag helper for editing a object.
- */
-export declare function tagHelper(tag: string, items: string[], locked?: boolean, remove?: boolean): Record<string, string | number>;
+/** Simple tag helper for editing a object. */
+export declare function tagHelper(tag: string, items: string[], { locked, remove }?: {
+    locked?: boolean;
+    remove?: boolean;
+}): Record<string, string | number>;
 export declare function ltrim(x: string, characters: string[]): string;
 export declare function lowerFirst(str: string): string;

package/dist/src/util.js

@@ -19,10 +19,8 @@ export async function getAgentIdentifier(section, agent) {
     }
     throw new Error(`Couldnt find "${agent}" in agents list (${agents.join(', ')})`);
 }
-/**
- * Simple tag helper for editing a object.
- */
-export function tagHelper(tag, items, locked = true, remove = false) {
+/** Simple tag helper for editing a object. */
+export function tagHelper(tag, items, { locked = true, remove = false } = {}) {
     const data = {};
     if (remove) {
         const tagname = `${tag}[].tag.tag-`;

package/dist/src/video.d.ts

@@ -62,7 +62,10 @@ declare abstract class Video extends Playable {
     /**
      * I haven't tested this yet. It may not work.
      */
-    uploadPoster(url?: string, file?: Uint8Array): Promise<void>;
+    uploadPoster({ url, file, }?: {
+        url?: string;
+        file?: Uint8Array;
+    }): Promise<void>;
     protected _loadData(data: MovieData | ShowData | EpisodeMetadata): void;
 }
 /**

package/dist/src/video.js

@@ -19,18 +19,18 @@ class Video extends Playable {
      */
     get thumbUrl() {
         const thumb = this.thumb ?? this.parentThumb ?? this.granparentThumb;
-        return this.server.url(thumb, true);
+        return this.server.url(thumb, { includeToken: true });
     }
     get artUrl() {
         const art = this.art ?? this.grandparentArt;
-        return this.server.url(art, true);
+        return this.server.url(art, { includeToken: true });
     }
     /**
      * Mark video as watched.
      */
     async markWatched() {
         const key = `/:/scrobble?key=${this.ratingKey}&identifier=com.plexapp.plugins.library`;
-        await this.server.query(key);
+        await this.server.query({ path: key });
         await this.reload();
     }
     /**
@@ -38,16 +38,16 @@ class Video extends Playable {
      */
     async markUnwatched() {
         const key = `/:/unscrobble?key=${this.ratingKey}&identifier=com.plexapp.plugins.library`;
-        await this.server.query(key);
+        await this.server.query({ path: key });
         await this.reload();
     }
     async rate(rate) {
         const key = `/:/rate?key=${this.ratingKey}&identifier=com.plexapp.plugins.library&rating=${rate}`;
-        await this.server.query(key);
+        await this.server.query({ path: key });
         await this.reload();
     }
     async extras() {
-        const data = await this.server.query(this._detailsKey);
+        const data = await this.server.query({ path: this._detailsKey });
         return findItems(data.MediaContainer.Metadata[0].Extras?.Metadata, undefined, Extra, this.server, this);
     }
     /**
@@ -67,14 +67,16 @@ class Video extends Playable {
     /**
      * I haven't tested this yet. It may not work.
      */
-    async uploadPoster(url, file) {
+    async uploadPoster({ url, file, } = {}) {
         if (url) {
             const key = `/library/metadata/${this.ratingKey}/posters?url=${encodeURIComponent(url)}`;
-            await this.server.query(key, 'post');
+            await this.server.query({ path: key, method: 'post' });
         }
         else if (file) {
             const key = `/library/metadata/${this.ratingKey}/posters`;
-            await this.server.query(key, 'post', {
+            await this.server.query({
+                path: key,
+                method: 'post',
                 body: file,
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl/plex",
-  "version": "3.12.0",
+  "version": "4.0.0",
   "description": "plex api client in typescript using ofetch",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "publishConfig": {