@ctrl/plex 1.5.2 → 2.0.0

package/dist/src/exceptions.d.ts

@@ -0,0 +1,20 @@
+export declare class BadRequest extends Error {
+    message: string;
+    constructor(message: string);
+}
+export declare class NotFound extends Error {
+    message: string;
+    constructor(message: string);
+}
+export declare class UnknownType extends Error {
+    message: string;
+    constructor(message: string);
+}
+export declare class Unsupported extends Error {
+    message: string;
+    constructor(message: string);
+}
+export declare class Unauthorized extends Error {
+    message: string;
+    constructor(message: string);
+}

package/dist/src/exceptions.js

@@ -0,0 +1,40 @@
+export class BadRequest extends Error {
+    constructor(message) {
+        super(message);
+        this.message = 'An invalid request, generally a user error.';
+        this.name = 'BadRequest';
+        this.message = message;
+    }
+}
+export class NotFound extends Error {
+    constructor(message) {
+        super(message);
+        this.message = 'Request media item or device is not found.';
+        this.name = 'NotFound';
+        this.message = message;
+    }
+}
+export class UnknownType extends Error {
+    constructor(message) {
+        super(message);
+        this.message = 'Unknown library type.';
+        this.name = 'UnknownType';
+        this.message = message;
+    }
+}
+export class Unsupported extends Error {
+    constructor(message) {
+        super(message);
+        this.message = 'Unsupported client request.';
+        this.name = 'Unsupported';
+        this.message = message;
+    }
+}
+export class Unauthorized extends Error {
+    constructor(message) {
+        super(message);
+        this.message = 'Invalid username or password.';
+        this.name = 'Unauthorized';
+        this.message = message;
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export * from './alert.js';
+export type { AlertTypes } from './alert.types.js';
+export * from './client.js';
+export * from './exceptions.js';
+export * from './library.js';
+export * from './media.js';
+export * from './myplex.js';
+export * from './playlist.js';
+export * from './server.js';
+export * from './video.js';
+export { X_PLEX_IDENTIFIER } from './config.js';
+export { SearchResult, Agent, SEARCHTYPES } from './search.js';

package/dist/src/index.js

@@ -0,0 +1,11 @@
+export * from './alert.js';
+export * from './client.js';
+export * from './exceptions.js';
+export * from './library.js';
+export * from './media.js';
+export * from './myplex.js';
+export * from './playlist.js';
+export * from './server.js';
+export * from './video.js';
+export { X_PLEX_IDENTIFIER } from './config.js';
+export { SearchResult, Agent, SEARCHTYPES } from './search.js';

package/dist/{library.d.ts → src/library.d.ts}

@@ -1,13 +1,13 @@
 import { Class } from 'type-fest';
-import type { PlexServer } from './server';
-import { LibraryRootResponse, SectionsDirectory, Location, CollectionData } from './library.types';
-import { PlexObject } from './base/plexObject';
-import { Movie, VideoType, Show } from './video';
-import { SearchResult } from './search.types';
-import { Agent, SEARCHTYPES } from './search';
-import { Playlist } from './playlist';
-import { PartialPlexObject } from './base/partialPlexObject';
-export declare type Section = MovieSection | ShowSection;
+import { PartialPlexObject } from './base/partialPlexObject.js';
+import { PlexObject } from './base/plexObject.js';
+import { CollectionData, LibraryRootResponse, Location, SectionsDirectory } from './library.types.js';
+import { Playlist } from './playlist.js';
+import { Agent, SEARCHTYPES } from './search.js';
+import { SearchResult } from './search.types.js';
+import type { PlexServer } from './server.js';
+import { Movie, Show, VideoType } from './video.js';
+export type Section = MovieSection | ShowSection;
 export declare class Library {
     private readonly server;
     static key: string;
@@ -186,8 +186,38 @@ export declare class Library {
      * library, you may like to optimize the database.
      */
     optimize(): Promise<void>;
+    /**
+     * 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.
+     */
+    /**
+     * Returns the validated and formatted search query API key
+     * (``/library/sections/<sectionKey>/all?<params>``).
+     */
     protected _loadData(data: LibraryRootResponse): void;
 }
+type Libtype = keyof typeof SEARCHTYPES;
+interface SearchArgs {
+    [key: string]: number | string | boolean | string[];
+    /** General string query to search for. Partial string matches are allowed. */
+    title: string;
+    /** A string of comma separated sort fields or a list of sort fields in the format ``column:dir``. */
+    sort: string | string[];
+    /** Only return the specified number of results. */
+    maxresults: number;
+    /** Default 0 */
+    container_start: number;
+    /** Default 100 (X_PLEX_CONTAINER_SIZE) */
+    container_size: number;
+    /** Limit the number of results from the filter. */
+    limit: number;
+    /**
+     * Return results of a specific type (movie, show, season, episode,
+     * artist, album, track, photoalbum, photo, collection) (e.g. ``libtype='movie'`` will only
+     * return {@link Movie} objects)
+     */
+    libtype: Libtype;
+}
 /**
  * Base class for a single library section.
  */
@@ -205,8 +235,6 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
     composite: string;
     /** Unknown */
     filters: boolean;
-    /** Key (or ID) of this library section. */
-    key: string;
     /** Language represented in this section (en, xn, etc). */
     language: string;
     /** Paths on disk where section content is stored. */
@@ -230,6 +258,8 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
     uuid: string;
     CONTENT_TYPE: string;
     readonly VIDEO_TYPE: Class<SectionVideoType>;
+    _filterTypes?: FilteringType[];
+    _fieldTypes?: FilteringFieldType[];
     all(sort?: string): Promise<any[]>;
     agents(): Promise<Agent[]>;
     /**
@@ -238,16 +268,51 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
      */
     get(title: string): Promise<SectionVideoType>;
     /**
-     * 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']
+     */
+    getGuid(guid: string): Promise<SectionVideoType>;
+    /**
+     * 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?: string, tab?: string, key?: string): string;
+    /**
+     * 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
      */
-    search<T = SectionVideoType>(args?: Record<string, number | string | boolean>, libtype?: keyof typeof SEARCHTYPES, Cls?: any): Promise<T[]>;
+    search<T = SectionVideoType>(args?: Partial<SearchArgs>, Cls?: any): Promise<T[]>;
     /**
      * Run an analysis on all of the items in this library section.
      * See :func:`~plexapi.base.PlexPartialObject.analyze` for more details.
@@ -297,7 +362,37 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
      * Returns a list of available Folders for this library section.
      */
     folders(): Promise<Folder[]>;
+    genres(): Promise<FilterChoice[]>;
+    /**
+     * Returns a list of available {@link FilteringFields} for a specified libtype.
+     * This is the list of options in the custom filter dropdown menu
+     */
+    listFields(libtype?: Libtype): Promise<FilteringField[]>;
+    getFilterType(libtype?: Libtype): Promise<FilteringType>;
+    /**
+     * @param fieldType The data type for the field (tag, integer, string, boolean, date,
+                      subtitleLanguage, audioLanguage, resolution).
+     */
+    getFieldType(fieldType: string): Promise<FilteringFieldType>;
+    /**
+     * @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)
+     * ```
+     */
+    listFilters(libtype?: Libtype): Promise<FilteringFilter[]>;
+    /**
+     * @param fieldType The data type for the field (tag, integer, string, boolean, date,
+     *                 subtitleLanguage, audioLanguage, resolution).
+     */
+    listOperators(fieldType: string): Promise<FilteringOperator[]>;
+    filterTypes(): Promise<FilteringType[]>;
+    fieldTypes(): Promise<FilteringFieldType[]>;
     protected _loadData(data: SectionsDirectory): void;
+    private _loadFilters;
 }
 export declare class MovieSection extends LibrarySection<Movie> {
     static TYPE: string;
@@ -339,7 +434,6 @@ export declare class Hub extends PlexObject {
  * Represents a Folder inside a library.
  */
 export declare class Folder extends PlexObject {
-    key: string;
     title: string;
     /**
      * Returns a list of available Folders for this folder.
@@ -351,12 +445,8 @@ export declare class Folder extends PlexObject {
 export declare class Collections<CollectionVideoType = VideoType> extends PartialPlexObject {
     static TAG: string;
     TYPE: string;
-    ratingKey: string;
     guid: string;
-    type: string;
-    title: string;
     librarySectionTitle: string;
-    librarySectionID: number;
     librarySectionKey: string;
     contentRating: string;
     subtype: string;
@@ -375,6 +465,102 @@ export declare class Collections<CollectionVideoType = VideoType> extends Partia
      * Returns a list of all items in the collection.
      */
     items(): Promise<CollectionVideoType[]>;
-    protected _loadData(data: CollectionData): void;
     protected _loadFullData(data: any): void;
+    protected _loadData(data: CollectionData): void;
+}
+export declare class FilterChoice extends PlexObject {
+    static TAG: string;
+    /**
+     * API URL path to quickly list all items with this filter choice.
+     * (/library/sections/<section>/all?genre=<key>)
+     */
+    fastKey: string;
+    /** Thumbnail URL for the filter choice. */
+    thumb?: string;
+    /** The title of the filter choice. */
+    title: string;
+    /** The filter type (genre, contentRating, etc). */
+    type: string;
+    protected _loadData(data: CollectionData): void;
+}
+export declare class FilteringType extends PlexObject {
+    static TAG: string;
+    /** The libtype for the filter. */
+    type: string;
+    /** True if this filter type is currently active. */
+    active: boolean;
+    fields: FilteringField[];
+    filters: FilteringFilter[];
+    /** List of sort objects. */
+    sorts: any;
+    /** The title for the libtype filter. */
+    title: string;
+    _loadData(data: any): void;
+}
+/**
+ * Represents a single Filter object for a {@link FilteringType}
+ */
+export declare class FilteringFilter extends PlexObject {
+    static TAG: string;
+    /** The key for the filter. */
+    filter: string;
+    /** The :class:`~plexapi.library.FilteringFieldType` type (string, boolean, integer, date, etc). */
+    filterType: string;
+    /** The title of the filter. */
+    title: string;
+    /** 'filter' */
+    type: string;
+    _loadData(data: any): void;
+}
+/**
+ * Represents a single Sort object for a {@link FilteringType}
+ */
+export declare class FilteringSort extends PlexObject {
+    static TAG: string;
+    /** True if the sort is currently active. */
+    active: boolean;
+    /** The currently active sorting direction. */
+    activeDirection: string;
+    /** The currently active default sorting direction. */
+    default: string;
+    /** The default sorting direction. */
+    defaultDirection: string;
+    /** The URL key for sorting with desc. */
+    descKey: string;
+    /** API URL path for first character endpoint. */
+    firstCharacterKey: string;
+    /** The title of the sorting. */
+    title: string;
+    _loadData(data: any): void;
+}
+/**
+ * Represents a single Field object for a {@link FilteringType}
+ */
+export declare class FilteringField extends PlexObject {
+    static TAG: string;
+    type: string;
+    title: string;
+    /** The subtype of the filter (decade, rating, etc) */
+    subType: string;
+    _loadData(data: any): void;
+}
+/**
+ * Represents a single FieldType for library filtering.
+ */
+export declare class FilteringFieldType extends PlexObject {
+    static TAG: string;
+    /** The filtering data type (string, boolean, integer, date, etc). */
+    type: string;
+    operators: FilteringOperator[];
+    _loadData(data: any): void;
+}
+/**
+ * Represents a single FilterChoice for library filtering.
+ */
+export declare class FilteringOperator extends PlexObject {
+    static TAG: string;
+    /** The libtype for the filter. */
+    type: string;
+    _loadData(data: any): void;
 }
+export {};