@ctrl/plex 3.3.0 → 3.5.0

package/README.md

@@ -105,7 +105,8 @@ npm run test-cleanup
 get a claim token from https://www.plex.tv/claim/
 export PLEX_CLAIM_TOKEN=claim-token
 
-```
+start plex container for testing
+```console
 docker run -d \
   --name=plex \
   --net=host \
@@ -132,7 +133,12 @@ docker run -d \
   lscr.io/linuxserver/plex:latest
 ```
 
-bootstrap media
+Pull latest plex container if needed
+```console
+docker pull lscr.io/linuxserver/plex:latest
 ```
-NODE_OPTIONS="--loader ts-node/esm" node scripts/bootstraptest.ts --no-docker --server-name=orbstack`
+
+bootstrap plex server with test media
+```console
+NODE_OPTIONS="--loader ts-node/esm" node scripts/bootstraptest.ts --no-docker --server-name=orbstack --password=$PLEX_PASSWORD --username=$PLEX_USERNAME
 ```

package/dist/src/alert.d.ts

@@ -1,6 +1,6 @@
 import WebSocket from 'ws';
-import { AlertTypes } from './alert.types.js';
-import { PlexServer } from './server.js';
+import type { AlertTypes } from './alert.types.js';
+import type { PlexServer } from './server.js';
 export declare class AlertListener {
     private readonly server;
     callback: (data: AlertTypes) => void;

package/dist/src/alert.js

@@ -8,7 +8,6 @@ export class AlertListener {
     async run() {
         const url = this.server.url(this.key, true).toString().replace('http', 'ws');
         this._ws = new WebSocket(url);
-        // eslint-disable-next-line @typescript-eslint/ban-types
         this._ws.on('message', (buffer) => {
             try {
                 const data = JSON.parse(buffer.toString());

package/dist/src/client.d.ts

@@ -1,6 +1,5 @@
-/// <reference types="node" resolution-mode="require"/>
 import { URL } from 'url';
-import { Player } from './client.types.js';
+import type { Player } from './client.types.js';
 export interface PlexOptions {
     /** (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional). */
     server?: any;

package/dist/src/library.d.ts

@@ -1,12 +1,12 @@
-import { Class } from 'type-fest';
+import type { Class } from 'type-fest';
 import { PartialPlexObject } from './base/partialPlexObject.js';
 import { PlexObject } from './base/plexObject.js';
-import { CollectionData, LibraryRootResponse, Location, SectionsDirectory } from './library.types.js';
+import type { 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 Agent, type SEARCHTYPES } from './search.js';
+import type { SearchResult } from './search.types.js';
 import type { PlexServer } from './server.js';
-import { Movie, Show, VideoType } from './video.js';
+import { Movie, Show, type VideoType } from './video.js';
 export type Section = MovieSection | ShowSection;
 export declare class Library {
     private readonly server;
@@ -364,7 +364,7 @@ export declare abstract class LibrarySection<SectionVideoType = VideoType> exten
     folders(): Promise<Folder[]>;
     genres(): Promise<FilterChoice[]>;
     /**
-     * Returns a list of available {@link FilteringFields} for a specified libtype.
+     * Returns a list of available {@link FilteringField} for a specified libtype.
      * This is the list of options in the custom filter dropdown menu
      */
     listFields(libtype?: Libtype): Promise<FilteringField[]>;

package/dist/src/library.js

@@ -213,7 +213,6 @@ export class Library {
         const results = [];
         const sections = await this.sections();
         for (const section of sections) {
-            // eslint-disable-next-line no-await-in-loop
             const items = await section.all();
             for (const item of items) {
                 results.push(item);
@@ -227,7 +226,6 @@ export class Library {
     async emptyTrash() {
         const sections = await this.sections();
         for (const section of sections) {
-            // eslint-disable-next-line no-await-in-loop
             await section.emptyTrash();
         }
     }
@@ -485,7 +483,7 @@ export class LibrarySection extends PlexObject {
         return fetchItems(this.server, key, undefined, FilterChoice);
     }
     /**
-     * Returns a list of available {@link FilteringFields} for a specified libtype.
+     * Returns a list of available {@link FilteringField} for a specified libtype.
      * This is the list of options in the custom filter dropdown menu
      */
     async listFields(libtype = this.type) {
@@ -496,7 +494,7 @@ export class LibrarySection extends PlexObject {
         const filter = filterTypes.find(f => f.type === libtype);
         if (!filter) {
             throw new NotFound(`Unknown libtype "${libtype}" for this library.
-        Available libtypes: ${filterTypes.join(', ')}`);
+        Available libtypes: ${filterTypes.map(f => f.type).join(', ')}`);
         }
         return filter;
     }

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

@@ -1,4 +1,4 @@
-import { ChapterSource, MarkerData, MediaTagData } from './video.types.js';
+import type { ChapterSource, MarkerData, MediaTagData } from './video.types.js';
 export interface LibraryRootResponse {
     size: number;
     allowSync: boolean;

package/dist/src/media.d.ts

@@ -1,5 +1,5 @@
 import { PlexObject } from './base/plexObject.js';
-import { ChapterData, MarkerData, MediaData, MediaPartData, MediaPartStreamData } from './video.types.js';
+import type { ChapterData, MarkerData, MediaData, MediaPartData, MediaPartStreamData } from './video.types.js';
 /**
  * Base class for media tags used for filtering and searching your library
  * items or navigating the metadata of media items in your library. Tags are

package/dist/src/myplex.d.ts

@@ -1,5 +1,5 @@
 import { PlexObject } from './base/plexObject.js';
-import { Connection, Device, ResourcesResponse } from './myplex.types.js';
+import type { Connection, Device, ResourcesResponse, WebLogin } from './myplex.types.js';
 import { PlexServer } from './server.js';
 /**
  * MyPlex account and profile information. This object represents the data found Account on
@@ -16,6 +16,19 @@ export declare class MyPlexAccount {
     timeout: number;
     server?: PlexServer;
     static key: string;
+    /**
+     * This follows the outline described in https://forums.plex.tv/t/authenticating-with-plex/609370
+     * to fetch a token and potentially compromise username and password. To use first call `getWebLogin()`
+     * and present the returned uri to a user to go to, then await `webLoginCheck()`. If you pass in a
+     * `forwardUrl`, then send the user to the returned uri, and when a request comes in on the passed in
+     * url, then await `webLoginCheck()`.
+     */
+    static getWebLogin(forwardUrl?: string | null): Promise<WebLogin>;
+    /**
+     * 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>;
     FRIENDINVITE: string;
     HOMEUSERCREATE: string;
     EXISTINGUSER: string;
@@ -136,7 +149,7 @@ export declare class MyPlexAccount {
  */
 export declare class MyPlexResource {
     readonly account: MyPlexAccount;
-    private baseUrl;
+    private readonly baseUrl;
     static key: string;
     TAG: string;
     /** Descriptive name of this resource */

package/dist/src/myplex.js

@@ -1,4 +1,4 @@
-import { URLSearchParams } from 'url';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { ofetch } from 'ofetch';
 import pAny from 'p-any';
 import { parseStringPromise } from 'xml2js';
@@ -14,6 +14,71 @@ import { PlexServer } from './server.js';
  */
 export class MyPlexAccount {
     static { this.key = 'https://plex.tv/api/v2/user'; }
+    /**
+     * This follows the outline described in https://forums.plex.tv/t/authenticating-with-plex/609370
+     * to fetch a token and potentially compromise username and password. To use first call `getWebLogin()`
+     * and present the returned uri to a user to go to, then await `webLoginCheck()`. If you pass in a
+     * `forwardUrl`, then send the user to the returned uri, and when a request comes in on the passed in
+     * url, then await `webLoginCheck()`.
+     */
+    static async getWebLogin(forwardUrl = null) {
+        const appName = BASE_HEADERS['X-Plex-Product'];
+        const clientIdentifier = BASE_HEADERS['X-Plex-Client-Identifier'];
+        const pin = await ofetch('https://plex.tv/api/v2/pins', {
+            method: 'post',
+            headers: {
+                Accept: 'application/json',
+            },
+            query: {
+                strong: 'true',
+                'X-Plex-Product': appName,
+                'X-Plex-Client-Identifier': clientIdentifier,
+            },
+        });
+        return {
+            ...pin,
+            uri: `https://app.plex.tv/auth#?clientID=${encodeURIComponent(clientIdentifier)}&code=${encodeURIComponent(pin.code)}&context%5Bdevice%5D%5Bproduct%5D=${encodeURIComponent(appName)}${forwardUrl ? '&forwardUrl=' + encodeURIComponent(forwardUrl) : ''}`,
+        };
+    }
+    /**
+     * 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) {
+        const recheckMs = 3000;
+        const clientIdentifier = BASE_HEADERS['X-Plex-Client-Identifier'];
+        const uri = `https://plex.tv/api/v2/pins/${webLogin.id}`;
+        const startTime = Date.now();
+        while (Date.now() < startTime + timeoutSeconds * 1000) {
+            try {
+                const tokenResponse = await ofetch(uri, {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'application/json',
+                    },
+                    query: {
+                        code: webLogin.code,
+                        'X-Plex-Client-Identifier': clientIdentifier,
+                    },
+                    timeout: recheckMs,
+                    retry: 5,
+                    retryDelay: recheckMs,
+                });
+                if (tokenResponse.authToken) {
+                    const myPlexAccount = new MyPlexAccount(null, '', '', tokenResponse.authToken);
+                    return await myPlexAccount.connect();
+                }
+                await sleep(recheckMs);
+            }
+            catch (err) {
+                if (err.message.includes('aborted')) {
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new Error('Failed to authenticate before timeout');
+    }
     /**
      *
      * @param username Your MyPlex username
@@ -68,7 +133,6 @@ export class MyPlexAccount {
             this._loadData(data);
             return this;
         }
-        // log('Logging in with token');
         const data = await this.query(MyPlexAccount.key);
         this._loadData(data);
         return this;

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

@@ -130,3 +130,8 @@ export interface Device {
         };
     }>;
 }
+export interface WebLogin {
+    id: number;
+    code: string;
+    uri: string;
+}

package/dist/src/playlist.d.ts

@@ -1,8 +1,8 @@
 import { Playable } from './base/playable.js';
 import type { Section } from './library.js';
-import { PlaylistResponse } from './playlist.types.js';
+import type { PlaylistResponse } from './playlist.types.js';
 import type { PlexServer } from './server.js';
-import { Episode, Movie, VideoType } from './video.js';
+import { Episode, Movie, type VideoType } from './video.js';
 interface CreateRegularPlaylistOptions {
     /** True to create a smart playlist */
     smart?: false;

package/dist/src/playlist.js

@@ -99,10 +99,8 @@ export class Playlist extends Playable {
             throw new BadRequest('Cannot remove items to a smart playlist.');
         }
         for (const item of items) {
-            // eslint-disable-next-line no-await-in-loop
             const playlistItemId = await this._getPlaylistItemID(item);
             const key = `${this.key}/items/${playlistItemId}`;
-            // eslint-disable-next-line no-await-in-loop
             await this.server.query(key, 'delete');
         }
     }

package/dist/src/search.d.ts

@@ -1,6 +1,6 @@
-import { ValueOf } from 'type-fest';
+import type { ValueOf } from 'type-fest';
 import { PlexObject } from './base/plexObject.js';
-import { MatchSearchResult } from './search.types.js';
+import type { MatchSearchResult } from './search.types.js';
 export declare class SearchResult extends PlexObject {
     static TAG: string;
     guid: string;

package/dist/src/server.d.ts

@@ -1,11 +1,10 @@
-/// <reference types="node" resolution-mode="require"/>
 import { URL, URLSearchParams } from 'url';
 import { PlexClient } from './client.js';
 import { Hub, Library } from './library.js';
 import { Optimized } from './media.js';
 import { MyPlexAccount } from './myplex.js';
 import { Agent, SEARCHTYPES } from './search.js';
-import { HistoryMetadatum } from './server.types.js';
+import type { HistoryMetadatum } 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

package/dist/src/server.js

@@ -156,7 +156,6 @@ export class PlexServer {
             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();
-            // eslint-disable-next-line no-await-in-loop
             raw = await this.query(key);
             results = results.concat(raw.MediaContainer.Metadata);
         }
@@ -185,7 +184,6 @@ export class PlexServer {
      * you're likley to recieve an authentication error calling this.
      */
     myPlexAccount() {
-        // eslint-disable-next-line logical-assignment-operators
         if (!this._myPlexAccount) {
             this._myPlexAccount = new MyPlexAccount(this.baseurl, undefined, undefined, this.token, this.timeout, this);
         }
@@ -205,7 +203,6 @@ export class PlexServer {
         }
         for (const server of response.MediaContainer.Server) {
             let { port } = server;
-            // eslint-disable-next-line logical-assignment-operators
             if (!port) {
                 // TODO: print warning about doing weird port stuff
                 port = Number(ports?.[server.machineIdentifier]);

package/dist/src/settings.js

@@ -55,7 +55,6 @@ export class Settings extends PlexObject {
     }
     _loadData(data) {
         this._data = data;
-        // eslint-disable-next-line logical-assignment-operators
         this._settings = this._settings ?? {};
         for (const elem of data) {
             const id = lowerFirst(elem.id);

package/dist/src/video.d.ts

@@ -1,9 +1,8 @@
-/// <reference types="node" resolution-mode="require"/>
-import { URL } from 'url';
+import type { URL } from 'url';
 import { Playable } from './base/playable.js';
-import { ExtrasData, FullShowData, MovieData, ShowData } from './library.types.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 { ChapterSource, EpisodeMetadata, FullMovieResponse } from './video.types.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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl/plex",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "plex api client in typescript",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "publishConfig": {
@@ -20,12 +20,12 @@
     "typescript"
   ],
   "scripts": {
-    "lint": "npm run lint:biome && npm run lint:eslint",
+    "lint": "pnpm run '/^(lint:biome|lint:eslint)$/'",
     "lint:biome": "biome check .",
-    "lint:eslint": "eslint --ext .ts,.tsx .",
-    "lint:fix": "npm run lint:biome:fix && npm run lint:eslint:fix",
-    "lint:eslint:fix": "eslint --ext .ts,.tsx . --fix",
-    "lint:biome:fix": "biome check . --apply",
+    "lint:eslint": "eslint .",
+    "lint:fix": "pnpm run '/^(lint:biome|lint:eslint):fix$/'",
+    "lint:eslint:fix": "eslint . --fix",
+    "lint:biome:fix": "biome check . --write",
     "prepare": "npm run build",
     "build": "tsc",
     "build:docs": "typedoc",
@@ -37,37 +37,32 @@
     "test-cleanup": "node --loader ts-node/esm scripts/test-cleanup.ts"
   },
   "dependencies": {
-    "@ctrl/mac-address": "^3.0.3",
-    "ofetch": "^1.3.4",
+    "@ctrl/mac-address": "^3.1.0",
+    "ofetch": "^1.4.1",
     "p-any": "^4.0.0",
-    "type-fest": "^4.18.1",
-    "ws": "^8.17.0",
+    "type-fest": "^4.40.1",
+    "ws": "^8.18.2",
     "xml2js": "^0.6.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "1.7.2",
-    "@ctrl/eslint-config-biome": "2.6.7",
-    "@sindresorhus/tsconfig": "5.0.0",
-    "@types/lodash": "4.17.1",
-    "@types/micromatch": "4.0.7",
-    "@types/node": "20.12.8",
-    "@types/ws": "8.5.10",
+    "@biomejs/biome": "1.9.4",
+    "@ctrl/eslint-config-biome": "4.4.0",
+    "@sindresorhus/tsconfig": "7.0.0",
+    "@types/node": "22.15.3",
+    "@types/ws": "8.18.1",
     "@types/xml2js": "0.4.14",
-    "@types/yargs": "17.0.32",
-    "@vitest/coverage-v8": "1.6.0",
-    "delay": "6.0.0",
-    "eslint": "8.57.0",
-    "execa": "8.0.1",
-    "glob": "10.3.12",
-    "globby": "14.0.1",
-    "lodash": "4.17.21",
+    "@types/yargs": "17.0.33",
+    "@vitest/coverage-v8": "3.1.2",
+    "eslint": "9.26.0",
+    "execa": "9.5.2",
+    "globby": "14.1.0",
     "make-dir": "5.0.0",
-    "ora": "8.0.1",
-    "p-retry": "6.2.0",
+    "ora": "8.2.0",
+    "p-retry": "6.2.1",
     "ts-node": "10.9.2",
-    "typedoc": "0.25.13",
-    "typescript": "5.4.5",
-    "vitest": "1.6.0",
+    "typedoc": "0.28.3",
+    "typescript": "5.8.3",
+    "vitest": "3.1.2",
     "yargs": "17.7.2"
   },
   "release": {
@@ -77,5 +72,6 @@
   },
   "engines": {
     "node": ">=18"
-  }
+  },
+  "packageManager": "pnpm@10.10.0"
 }