@ctrl/plex 1.5.3 → 2.0.0

package/dist/{library.js → src/library.js}

@@ -1,14 +1,13 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Collections = exports.Folder = exports.Hub = exports.ShowSection = exports.MovieSection = exports.LibrarySection = exports.Library = void 0;
-const url_1 = require("url");
-const plexObject_1 = require("./base/plexObject");
-const video_1 = require("./video");
-const baseFunctionality_1 = require("./baseFunctionality");
-const search_1 = require("./search");
-const playlist_1 = require("./playlist");
-const partialPlexObject_1 = require("./base/partialPlexObject");
-class Library {
+import { URLSearchParams } from 'url';
+import { PartialPlexObject } from './base/partialPlexObject.js';
+import { PlexObject } from './base/plexObject.js';
+import { fetchItem, fetchItems, findItems } from './baseFunctionality.js';
+import { NotFound } from './exceptions.js';
+import { Playlist } from './playlist.js';
+import { searchType } from './search.js';
+import { Movie, Show } from './video.js';
+export class Library {
+    static { this.key = '/library'; }
     constructor(server, data) {
         this.server = server;
         this._loadData(data);
@@ -41,8 +40,9 @@ class Library {
         return section;
     }
     async sectionByID(sectionId) {
+        const sectionIdStr = sectionId.toString();
         const sections = await this.sections();
-        const section = sections.find(s => s.key);
+        const section = sections.find(s => s.key === sectionIdStr);
         if (!section) {
             throw new Error(`Invalid library section id: ${sectionId}`);
         }
@@ -193,7 +193,7 @@ class Library {
      *       46:United Kingdom, 47:United States, 48:Uruguay, 49:Venezuela.
      */
     async add(name, type, agent, scanner, location, language = 'en', extra = {}) {
-        const search = new url_1.URLSearchParams({
+        const search = new URLSearchParams({
             name,
             type,
             agent,
@@ -239,6 +239,30 @@ class Library {
     async optimize() {
         await this.server.query('/library/optimize?async=1', 'put');
     }
+    /**
+     * Validates a filter field and values are available as a custom filter for the library.
+     * Returns the validated field and values as a URL encoded parameter string.
+     */
+    // _validateFilterField(field: string): string {
+    //   const match = /(?:([a-zA-Z]*)\.)?([a-zA-Z]+)([!<>=&]*)/.test(field);
+    //   if (!match) {
+    //     throw new Error('Invalid filter field: ' + field);
+    //   }
+    // }
+    /**
+     * Returns the validated and formatted search query API key
+     * (``/library/sections/<sectionKey>/all?<params>``).
+     */
+    // _buildSearchKey(kwargs: Record<string, string>) {
+    //   const args: Record<string, string> = {};
+    //   const filterArgs = [];
+    //   for (const [field, values] of Object.entries(kwargs)) {
+    //     if (!(field.split('__')[-1] in OPERATORS)) {
+    //       filterArgs.push(this._validateFilterField(field, values, libtype));
+    //       delete kwargs[field];
+    //     }
+    //   }
+    // }
     _loadData(data) {
         this.identifier = data.identifier;
         this.mediaTagPrefix = data.mediaTagPrefix;
@@ -246,45 +270,95 @@ class Library {
         this.title2 = data.title2;
     }
 }
-exports.Library = Library;
-Library.key = '/library';
 /**
  * Base class for a single library section.
  */
-class LibrarySection extends plexObject_1.PlexObject {
+export class LibrarySection extends PlexObject {
+    static { this.ALLOWED_FILTERS = []; }
+    static { this.ALLOWED_SORT = []; }
+    static { this.BOOLEAN_FILTERS = ['unwatched', 'duplicate']; }
     async all(sort = '') {
         let sortStr = '';
         if (sort) {
             sortStr = `?sort=${sort}`;
         }
         const key = `/library/sections/${this.key}/all${sortStr}`;
-        const items = await baseFunctionality_1.fetchItems(this.server, key);
+        const items = await fetchItems(this.server, key);
         return items;
     }
     async agents() {
-        return this.server.agents(search_1.searchType(this.type));
+        return this.server.agents(searchType(this.type));
     }
     /**
      * @param title Title of the item to return.
      * @returns the media item with the specified title.
      */
     async get(title) {
-        const key = `/library/sections/${this.key}/all?title=${title}`;
-        const data = await baseFunctionality_1.fetchItem(this.server, key, { title__iexact: title });
+        const key = `/library/sections/${this.key}/all?includeGuids=1&title=${title}`;
+        const data = await fetchItem(this.server, key, { title__iexact: title });
         return new this.VIDEO_TYPE(this.server, data, key, this);
     }
     /**
-     * Searching within a library section is much more powerful. It seems certain
-     * attributes on the media objects can be targeted to filter this search down
-     * a bit, but I havent found the documentation for it.
+     * Returns the media item with the specified external IMDB, TMDB, or TVDB ID.
+     * Note: This search uses a PlexAPI operator so performance may be slow. All items from the
+     * entire Plex library need to be retrieved for each guid search. It is recommended to create
+     * your own lookup dictionary if you are searching for a lot of external guids.
+     *
+     * @param guid The external guid of the item to return.
+     *  Examples: IMDB ``imdb://tt0944947``, TMDB ``tmdb://1399``, TVDB ``tvdb://121361``.
+     *
+     *
+     * Example:
+     *
+     * 		.. code-block:: python
+     *
+     * 				# This will retrieve all items in the entire library 3 times
+     * 				result1 = library.getGuid('imdb://tt0944947')
+     * 				result2 = library.getGuid('tmdb://1399')
+     * 				result3 = library.getGuid('tvdb://121361')
+     *
+     * 				# This will only retrieve all items in the library once to create a lookup dictionary
+     * 				guidLookup = {guid.id: item for item in library.all() for guid in item.guids}
+     * 				result1 = guidLookup['imdb://tt0944947']
+     * 				result2 = guidLookup['tmdb://1399']
+     * 				result3 = guidLookup['tvdb://121361']
+     */
+    async getGuid(guid) {
+        const key = `/library/sections/${this.key}/all?includeGuids=1`;
+        return fetchItem(this.server, key, { Guid__id__iexact: guid });
+    }
+    /**
+     * Returns the Plex Web URL for the library.
+     *
+     * @param base The base URL before the fragment (``#!``).
+     *    Default is https://app.plex.tv/desktop.
+     * @param tab The library tab (recommended, library, collections, playlists, timeline).
+     * @param key A hub key.
+     */
+    getWebURL(base, tab, key) {
+        const params = new URLSearchParams();
+        params.append('source', this.key);
+        if (tab) {
+            params.append('pivot', tab);
+        }
+        if (key) {
+            params.append('key', key);
+            params.append('pageType', 'list');
+        }
+        return this.server._buildWebURL(base, undefined, params);
+    }
+    /**
+     * Search the library. The http requests will be batched in container_size. If you are only looking for the
+     * first <num> results, it would be wise to set the maxresults option to that amount so the search doesn't iterate
+     * over all results on the server.
      *
      * Example: "studio=Comedy%20Central" or "year=1999" "title=Kung Fu" all work. Other items
      * such as actor=<id> seem to work, but require you already know the id of the actor.
      * TLDR: This is untested but seems to work. Use library section search when you can.
      * @param args Search using a number of different attributes
      */
-    async search(args = {}, libtype, Cls = this.VIDEO_TYPE) {
-        const params = new url_1.URLSearchParams();
+    async search(args = {}, Cls = this.VIDEO_TYPE) {
+        const params = new URLSearchParams();
         for (const [key, value] of Object.entries(args)) {
             let strValue;
             if (typeof value === 'string') {
@@ -298,11 +372,11 @@ class LibrarySection extends plexObject_1.PlexObject {
             }
             params.append(key, strValue);
         }
-        if (libtype) {
-            params.append('type', search_1.searchType(libtype).toString());
+        if (args.libtype) {
+            params.append('type', searchType(args.libtype).toString());
         }
-        const key = `/library/all/?${params.toString()}`;
-        const data = await baseFunctionality_1.fetchItems(this.server, key, undefined, Cls, this);
+        const key = `/library/sections/${this.key}/all?${params.toString()}`;
+        const data = await fetchItems(this.server, key, undefined, Cls, this);
         return data;
     }
     /**
@@ -368,7 +442,7 @@ class LibrarySection extends plexObject_1.PlexObject {
      * @param kwargs object of settings to edit
      */
     async edit(kwargs) {
-        const params = new url_1.URLSearchParams(kwargs);
+        const params = new URLSearchParams(kwargs);
         const part = `/library/sections/${this.key}?${params.toString()}`;
         await this.server.query(part, 'put');
         const library = await this.server.library();
@@ -382,7 +456,7 @@ class LibrarySection extends plexObject_1.PlexObject {
     }
     async hubs() {
         const key = `/hubs/sections/${this.key}`;
-        const hubs = await baseFunctionality_1.fetchItems(this.server, key, undefined, Hub, this);
+        const hubs = await fetchItems(this.server, key, undefined, Hub, this);
         return hubs;
     }
     /**
@@ -390,10 +464,10 @@ class LibrarySection extends plexObject_1.PlexObject {
      */
     async playlists() {
         const key = `/playlists?type=15&playlistType=${this.CONTENT_TYPE}&sectionID=${this.key}`;
-        return baseFunctionality_1.fetchItems(this.server, key, undefined, playlist_1.Playlist, this);
+        return fetchItems(this.server, key, undefined, Playlist, this);
     }
     async collections(args = {}) {
-        const collections = await this.search(args, 'collection', Collections);
+        const collections = await this.search({ ...args, libtype: 'collection' }, Collections);
         collections.forEach(collection => {
             collection.VIDEO_TYPE = this.VIDEO_TYPE;
         });
@@ -404,7 +478,71 @@ class LibrarySection extends plexObject_1.PlexObject {
      */
     async folders() {
         const key = `/library/sections/${this.key}/folder`;
-        return baseFunctionality_1.fetchItems(this.server, key, undefined, Folder);
+        return fetchItems(this.server, key, undefined, Folder);
+    }
+    async genres() {
+        const key = `/library/sections/${this.key}/genre`;
+        return fetchItems(this.server, key, undefined, FilterChoice);
+    }
+    /**
+     * Returns a list of available {@link FilteringFields} for a specified libtype.
+     * This is the list of options in the custom filter dropdown menu
+     */
+    async listFields(libtype = this.type) {
+        return (await this.getFilterType(libtype)).fields;
+    }
+    async getFilterType(libtype = this.type) {
+        const filterTypes = await this.filterTypes();
+        const filter = filterTypes.find(f => f.type === libtype);
+        if (!filter) {
+            throw new NotFound(`Unknown libtype "${libtype}" for this library.
+        Available libtypes: ${filterTypes.join(', ')}`);
+        }
+        return filter;
+    }
+    /**
+     * @param fieldType The data type for the field (tag, integer, string, boolean, date,
+                      subtitleLanguage, audioLanguage, resolution).
+     */
+    async getFieldType(fieldType) {
+        const fieldTypes = await this.fieldTypes();
+        const fType = fieldTypes.find(f => f.type === fieldType);
+        if (!fType) {
+            const availableFieldTypes = fieldTypes.map(f => f.type);
+            throw new NotFound(`Unknown field type "${fieldType}" for this library. Available field types: ${availableFieldTypes.join(', ')}`);
+        }
+        return fType;
+    }
+    /**
+     * @param libtype The library type to filter (movie, show, season, episode,
+     *                 artist, album, track, photoalbum, photo, collection).
+     *
+     * @example
+     * ```ts
+     * const availableFilters = (await library.listFilters()).map(f => f.filter)
+     * ```
+     */
+    async listFilters(libtype) {
+        return (await this.getFilterType(libtype)).filters;
+    }
+    /**
+     * @param fieldType The data type for the field (tag, integer, string, boolean, date,
+     *                 subtitleLanguage, audioLanguage, resolution).
+     */
+    async listOperators(fieldType) {
+        return (await this.getFieldType(fieldType)).operators;
+    }
+    async filterTypes() {
+        if (this._filterTypes === null) {
+            await this._loadFilters();
+        }
+        return this._filterTypes;
+    }
+    async fieldTypes() {
+        if (this._fieldTypes === null) {
+            await this._loadFilters();
+        }
+        return this._fieldTypes;
     }
     _loadData(data) {
         this.uuid = data.uuid;
@@ -425,61 +563,99 @@ class LibrarySection extends plexObject_1.PlexObject {
         this.createdAt = new Date(data.createdAt * 1000);
         this.scannedAt = new Date(data.scannedAt * 1000);
     }
+    async _loadFilters() {
+        const key = `/library/sections/${this.key}/all?includeMeta=1&includeAdvanced=1&X-Plex-Container-Start=0&X-Plex-Container-Size=0`;
+        const data = await this.server.query(key);
+        // rtag='Meta'
+        this._filterTypes = findItems(data, undefined, FilteringType);
+    }
 }
-exports.LibrarySection = LibrarySection;
-LibrarySection.ALLOWED_FILTERS = [];
-LibrarySection.ALLOWED_SORT = [];
-LibrarySection.BOOLEAN_FILTERS = ['unwatched', 'duplicate'];
-class MovieSection extends LibrarySection {
+export class MovieSection extends LibrarySection {
     constructor() {
         super(...arguments);
         this.METADATA_TYPE = 'movie';
         this.CONTENT_TYPE = 'video';
-        this.VIDEO_TYPE = video_1.Movie;
-    }
+        this.VIDEO_TYPE = Movie;
+    }
+    static { this.TYPE = 'movie'; }
+    static { this.ALLOWED_FILTERS = [
+        'unwatched',
+        'duplicate',
+        'year',
+        'decade',
+        'genre',
+        'contentRating',
+        'collection',
+        'director',
+        'actor',
+        'country',
+        'studio',
+        'resolution',
+        'guid',
+        'label',
+        'writer',
+        'producer',
+        'subtitleLanguage',
+        'audioLanguage',
+        'lastViewedAt',
+        'viewCount',
+        'addedAt',
+    ]; }
+    static { this.ALLOWED_SORT = [
+        'addedAt',
+        'originallyAvailableAt',
+        'lastViewedAt',
+        'titleSort',
+        'rating',
+        'mediaHeight',
+        'duration',
+    ]; }
+    static { this.TAG = 'Directory'; }
 }
-exports.MovieSection = MovieSection;
-MovieSection.TYPE = 'movie';
-MovieSection.ALLOWED_FILTERS = [
-    'unwatched',
-    'duplicate',
-    'year',
-    'decade',
-    'genre',
-    'contentRating',
-    'collection',
-    'director',
-    'actor',
-    'country',
-    'studio',
-    'resolution',
-    'guid',
-    'label',
-    'writer',
-    'producer',
-    'subtitleLanguage',
-    'audioLanguage',
-    'lastViewedAt',
-    'viewCount',
-    'addedAt',
-];
-MovieSection.ALLOWED_SORT = [
-    'addedAt',
-    'originallyAvailableAt',
-    'lastViewedAt',
-    'titleSort',
-    'rating',
-    'mediaHeight',
-    'duration',
-];
-MovieSection.TAG = 'Directory';
-class ShowSection extends LibrarySection {
+export class ShowSection extends LibrarySection {
     constructor() {
         super(...arguments);
         this.METADATA_TYPE = 'episode';
         this.CONTENT_TYPE = 'video';
-        this.VIDEO_TYPE = video_1.Show;
-    }
+        this.VIDEO_TYPE = Show;
+    }
+    static { this.TYPE = 'show'; }
+    static { this.ALLOWED_FILTERS = [
+        'unwatched',
+        'year',
+        'genre',
+        'contentRating',
+        'network',
+        'collection',
+        'guid',
+        'duplicate',
+        'label',
+        'show.title',
+        'show.year',
+        'show.userRating',
+        'show.viewCount',
+        'show.lastViewedAt',
+        'show.actor',
+        'show.addedAt',
+        'episode.title',
+        'episode.originallyAvailableAt',
+        'episode.resolution',
+        'episode.subtitleLanguage',
+        'episode.unwatched',
+        'episode.addedAt',
+        'episode.userRating',
+        'episode.viewCount',
+        'episode.lastViewedAt',
+    ]; }
+    static { this.ALLOWED_SORT = [
+        'addedAt',
+        'lastViewedAt',
+        'originallyAvailableAt',
+        'titleSort',
+        'rating',
+        'unwatched',
+    ]; }
+    static { this.TAG = 'Directory'; }
     // TODO: figure out how to return episode objects
     // /**
     //  * Search for an episode. See :func:`~plexapi.library.LibrarySection.search` for usage.
@@ -496,46 +672,9 @@ class ShowSection extends LibrarySection {
         return this.search({ libtype, maxresults, sort: 'episode.addedAt:desc', ...args });
     }
 }
-exports.ShowSection = ShowSection;
-ShowSection.TYPE = 'show';
-ShowSection.ALLOWED_FILTERS = [
-    'unwatched',
-    'year',
-    'genre',
-    'contentRating',
-    'network',
-    'collection',
-    'guid',
-    'duplicate',
-    'label',
-    'show.title',
-    'show.year',
-    'show.userRating',
-    'show.viewCount',
-    'show.lastViewedAt',
-    'show.actor',
-    'show.addedAt',
-    'episode.title',
-    'episode.originallyAvailableAt',
-    'episode.resolution',
-    'episode.subtitleLanguage',
-    'episode.unwatched',
-    'episode.addedAt',
-    'episode.userRating',
-    'episode.viewCount',
-    'episode.lastViewedAt',
-];
-ShowSection.ALLOWED_SORT = [
-    'addedAt',
-    'lastViewedAt',
-    'originallyAvailableAt',
-    'titleSort',
-    'rating',
-    'unwatched',
-];
-ShowSection.TAG = 'Directory';
 /** Represents a single Hub (or category) in the PlexServer search */
-class Hub extends plexObject_1.PlexObject {
+export class Hub extends PlexObject {
+    static { this.TAG = 'Hub'; }
     _loadData(data) {
         this.hubIdentifier = data.hubIdentifier;
         this.size = data.size;
@@ -545,33 +684,31 @@ class Hub extends plexObject_1.PlexObject {
         this.Metadata = data.Metadata;
     }
 }
-exports.Hub = Hub;
-Hub.TAG = 'Hub';
 /**
  * Represents a Folder inside a library.
  */
-class Folder extends plexObject_1.PlexObject {
+export class Folder extends PlexObject {
     /**
      * Returns a list of available Folders for this folder.
      * Continue down subfolders until a mediaType is found.
      */
     async subfolders() {
         if (this.key.startsWith('/library/metadata')) {
-            return baseFunctionality_1.fetchItems(this.server, this.key);
+            return fetchItems(this.server, this.key);
         }
-        return baseFunctionality_1.fetchItems(this.server, this.key, undefined, Folder);
+        return fetchItems(this.server, this.key, undefined, Folder);
     }
     _loadData(data) {
         this.key = data.key;
         this.title = data.title;
     }
 }
-exports.Folder = Folder;
-class Collections extends partialPlexObject_1.PartialPlexObject {
+export class Collections extends PartialPlexObject {
     constructor() {
         super(...arguments);
         this.TYPE = 'collection';
     }
+    static { this.TAG = 'Directory'; }
     // Alias for childCount
     get size() {
         return this.childCount;
@@ -582,10 +719,12 @@ class Collections extends partialPlexObject_1.PartialPlexObject {
     async items() {
         const key = `/library/metadata/${this.ratingKey}/children`;
         const data = await this.server.query(key);
-        return data.MediaContainer.Metadata.map(data => new this.VIDEO_TYPE(this.server, data, undefined, this));
+        return (data.MediaContainer.Metadata?.map(d => new this.VIDEO_TYPE(this.server, d, undefined, this)) ?? []);
+    }
+    _loadFullData(data) {
+        this._loadData(data);
     }
     _loadData(data) {
-        var _a, _b;
         this.key = data.key;
         this.title = data.title;
         this.ratingKey = data.ratingKey;
@@ -601,14 +740,91 @@ class Collections extends partialPlexObject_1.PartialPlexObject {
         this.thumb = data.thumb;
         this.addedAt = data.addedAt;
         this.updatedAt = data.updatedAt;
-        this.childCount = parseInt((_b = (_a = data.childCount) !== null && _a !== void 0 ? _a : data.size) !== null && _b !== void 0 ? _b : 0, 10);
+        this.childCount = Number(data.childCount ?? data.size ?? '0');
         this.maxYear = data.maxYear;
         this.minYear = data.minYear;
         this.art = data.art;
     }
-    _loadFullData(data) {
-        this._loadData(data);
+}
+export class FilterChoice extends PlexObject {
+    static { this.TAG = 'Directory'; }
+    _loadData(data) {
+        this.key = data.key;
+        this.title = data.title;
+        this.type = data.type;
+        this.thumb = data.thumb;
+    }
+}
+export class FilteringType extends PlexObject {
+    static { this.TAG = 'Type'; }
+    _loadData(data) {
+        this.active = data.active;
+        this.fields = findItems(data, undefined, FilteringField);
+        this.filters = findItems(data, undefined, FilteringFilter);
+        this.key = data.key;
+        this.sorts = findItems(data, undefined, FilteringSort);
+        this.title = data.title;
+        this.type = data.type;
+    }
+}
+/**
+ * Represents a single Filter object for a {@link FilteringType}
+ */
+export class FilteringFilter extends PlexObject {
+    static { this.TAG = 'Filter'; }
+    _loadData(data) {
+        this.filter = data.filter;
+        this.filterType = data.filterType;
+        this.key = data.key;
+        this.title = data.title;
+        this.type = data.type;
+    }
+}
+/**
+ * Represents a single Sort object for a {@link FilteringType}
+ */
+export class FilteringSort extends PlexObject {
+    static { this.TAG = 'Sort'; }
+    _loadData(data) {
+        this.active = data.active;
+        this.activeDirection = data.activeDirection;
+        this.default = data.default;
+        this.defaultDirection = data.defaultDirection;
+        this.descKey = data.descKey;
+        this.firstCharacterKey = data.firstCharacterKey;
+        this.key = data.key;
+        this.title = data.title;
+    }
+}
+/**
+ * Represents a single Field object for a {@link FilteringType}
+ */
+export class FilteringField extends PlexObject {
+    static { this.TAG = 'Field'; }
+    _loadData(data) {
+        this.key = data.key;
+        this.title = data.title;
+        this.type = data.type;
+        this.subType = data.subType;
+    }
+}
+/**
+ * Represents a single FieldType for library filtering.
+ */
+export class FilteringFieldType extends PlexObject {
+    static { this.TAG = 'FieldType'; }
+    _loadData(data) {
+        this.type = data.type;
+        this.operators = findItems(data, undefined, FilteringOperator);
+    }
+}
+/**
+ * Represents a single FilterChoice for library filtering.
+ */
+export class FilteringOperator extends PlexObject {
+    static { this.TAG = 'Operator'; }
+    _loadData(data) {
+        this.key = data.key;
+        this.type = data.type;
     }
 }
-exports.Collections = Collections;
-Collections.TAG = 'Directory';