tmdb-lumosovich 0.8.0 → 0.9.0

package/README.md

@@ -6,7 +6,7 @@
 
 A small, typed Node.js wrapper for the TMDB API, including IMDb ID lookup through TMDB.
 
-**Lumosovich** is being built incrementally toward full TMDB v3 API coverage. It currently supports external-ID lookup, search, discovery, trending, movie and TV series catalogs and metadata, reviews, keywords, networks, collections, companies, configuration, people and credit resources, and TV seasons, episodes, and episode groups.
+**Lumosovich** is being built incrementally toward full TMDB v3 API coverage. It currently supports external-ID lookup, search, discovery, trending, movie and TV series catalogs and metadata, reviews, keywords, networks, collections, companies, configuration, people and credit resources, lists, guest-session ratings, watch-provider catalogs, and TV seasons, episodes, and episode groups.
 
 The name comes from **Lumos** — a spell for bringing light — with a little Russian-style `-ovich` treatment.
 
@@ -14,11 +14,11 @@ Light up the movie database.
 
 ## Current status
 
-Install [tmdb-lumosovich on npm](https://www.npmjs.com/package/tmdb-lumosovich), with source and issues on [GitHub](https://github.com/namipsg/lumosovich). Version `0.8.0` covers **121 of 152 TMDB v3 operations**, including all TV, person, and credit operations, measured against the official specification pinned on September 27, 2026. This is an early `0.x` library; full API coverage is still in progress. See the [coverage baseline](https://github.com/namipsg/lumosovich/blob/main/spec/README.md) for how coverage is checked.
+Install [tmdb-lumosovich on npm](https://www.npmjs.com/package/tmdb-lumosovich), with source and issues on [GitHub](https://github.com/namipsg/lumosovich). Version `0.9.0` covers **134 of 152 TMDB v3 operations**, including all TV, person, credit, list, guest-session rating, and watch-provider catalog operations, measured against the official specification pinned on September 27, 2026. This is an early `0.x` library; full API coverage is still in progress. See the [coverage baseline](https://github.com/namipsg/lumosovich/blob/main/spec/README.md) for how coverage is checked.
 
-The package moved from `lumosovich` to `tmdb-lumosovich` in version `0.7.1`; the public `Lumosovich` class kept its name. Previously published `lumosovich` versions remain installable, but new projects should use `tmdb-lumosovich`. The read-only live smoke test exercises all 111 public read operations. Account-state and rating methods require a TMDB session and are verified by offline request contracts.
+The package moved from `lumosovich` to `tmdb-lumosovich` in version `0.7.1`; the public `Lumosovich` class kept its name. Previously published `lumosovich` versions remain installable, but new projects should use `tmdb-lumosovich`. The live smoke test exercises all 119 public read routes without changing account data. A new, unrated guest session currently receives HTTP 404 from TMDB on its rated-content routes. List mutations, account-state methods, and ratings require a TMDB session and are verified by offline request contracts.
 
-The release passes 196 offline tests and TypeScript declaration checks. See the [changelog](https://github.com/namipsg/lumosovich/blob/main/CHANGELOG.md) for earlier releases.
+The release passes 245 offline tests and TypeScript declaration checks. See the [changelog](https://github.com/namipsg/lumosovich/blob/main/CHANGELOG.md) for earlier releases.
 
 ## Installation
 
@@ -372,6 +372,47 @@ const changes = await tmdb.people.changes(personId);
 
 The three credit collections return `cast` and `crew` arrays with TMDB's original fields; `combinedCredits()` includes both movie and TV roles. `taggedImages()` has paginated image records, including episode stills, while `images()` has portrait profiles. TMDB can report `page: 0` for tagged images even when page 1 is requested. `changeList()` and `changes()` accept optional `startDate`, `endDate`, and `page`; dates use `YYYY-MM-DD`. `popular()` and `taggedImages()` accept a positive page. Credit details, popular people, and the three credit collections support a `language` override. `latest()` can be incomplete while a new person record is being edited on TMDB.
 
+## Lists, guest sessions, and watch providers
+
+Public lists use numeric TMDB list IDs. Reading list details and checking whether a movie is present require no user session:
+
+```js
+const list = await tmdb.lists.get(1, { page: 1 });
+const status = await tmdb.lists.itemStatus(1, 550);
+console.log(list.name, status.item_present);
+```
+
+Creating or changing a list requires an existing TMDB **user** session. Supply `sessionId` explicitly for each write; a guest session cannot manage lists.
+
+```js
+const sessionId = process.env.TMDB_SESSION_ID;
+if (!sessionId) throw new Error('Set TMDB_SESSION_ID first');
+const created = await tmdb.lists.create({
+  name: 'Movies to watch', description: 'My picks', language: 'en', sessionId,
+});
+await tmdb.lists.addMovie(created.list_id, 550, { sessionId });
+await tmdb.lists.removeMovie(created.list_id, 550, { sessionId });
+await tmdb.lists.clear(created.list_id, { sessionId, confirm: true });
+await tmdb.lists.delete(created.list_id, { sessionId });
+```
+
+`clear()` requires an explicit boolean `confirm`; deleting a list and removing an item are separate operations. TMDB can return list IDs as strings in read responses, so inspect the returned `id` rather than assuming its runtime type. List writes are contract-tested offline; the live smoke test does not alter an account.
+
+```js
+const guestId = process.env.TMDB_GUEST_SESSION_ID;
+if (guestId) {
+  const ratedMovies = await tmdb.guestSessions.ratedMovies(guestId);
+  const ratedShows = await tmdb.guestSessions.ratedTv(guestId);
+  const ratedEpisodes = await tmdb.guestSessions.ratedTvEpisodes(guestId);
+}
+
+const regions = await tmdb.watchProviders.regions();
+const movieProviders = await tmdb.watchProviders.movies({ watchRegion: 'US' });
+const tvProviders = await tmdb.watchProviders.tv({ watchRegion: 'US' });
+```
+
+Guest rating lists accept `language`, positive `page`, and `sortBy: 'created_at.asc' | 'created_at.desc'`. A new unrated guest session may receive HTTP 404. Provider catalogs return a `results` array; movie and TV catalogs accept `watchRegion`, while the regions catalog accepts only `language`. Guest-session creation is part of the upcoming authentication group.
+
 ## Image URLs
 
 TMDB detail responses contain image paths. Build a safe public image URL with:
@@ -459,12 +500,14 @@ TMDB_API_KEY=... npm run test:live
 ```
 
 The credential is read from the environment, never from a tracked file. This checks
-all 111 public read operations. Account-state and rating methods require a TMDB
-session and are covered by offline contracts; the live test makes read-only requests.
+all 119 public read routes. The test creates a temporary guest session for the
+three rated-content routes and accepts TMDB's HTTP 404 for an unrated session.
+List and account mutations require a user session and are covered by offline
+contracts; the live test does not change account data.
 
 ## Roadmap
 
-Lists, authentication, and the remaining TMDB resources will expand coverage in future releases. The [coverage ledger](https://github.com/namipsg/lumosovich/blob/main/spec/coverage.json) tracks implemented and remaining operations.
+Account resources, authentication, and the final parity audit will complete coverage in future releases. The [coverage ledger](https://github.com/namipsg/lumosovich/blob/main/spec/coverage.json) tracks implemented and remaining operations.
 
 The goal is to cover the TMDB API while keeping the library:
 

package/dist/guest-session-types.d.ts

@@ -0,0 +1,26 @@
+import type { FindEpisodeHit, MovieSearchHit, SearchPage, TvSearchHit } from './types.js';
+export interface GuestSessionRatedOptions {
+    language?: string;
+    page?: number;
+    sortBy?: 'created_at.asc' | 'created_at.desc';
+}
+export interface GuestRatedMovie extends MovieSearchHit {
+    title: string;
+    rating: number;
+}
+export interface GuestRatedTv extends TvSearchHit {
+    name: string;
+    rating: number;
+}
+export interface GuestRatedEpisode extends FindEpisodeHit {
+    name: string;
+    show_id: number;
+    season_number: number;
+    episode_number: number;
+    rating: number;
+}
+export interface GuestSessionMethods {
+    ratedMovies(guestSessionId: string, options?: GuestSessionRatedOptions): Promise<SearchPage<GuestRatedMovie>>;
+    ratedTv(guestSessionId: string, options?: GuestSessionRatedOptions): Promise<SearchPage<GuestRatedTv>>;
+    ratedTvEpisodes(guestSessionId: string, options?: GuestSessionRatedOptions): Promise<SearchPage<GuestRatedEpisode>>;
+}

package/dist/guest-session-types.js

@@ -0,0 +1 @@
+export {};

package/dist/guest-sessions.d.ts

@@ -0,0 +1,3 @@
+import { TmdbHttpClient } from './http.js';
+import type { GuestSessionMethods } from './guest-session-types.js';
+export declare function createGuestSessionMethods(http: TmdbHttpClient): GuestSessionMethods;

package/dist/guest-sessions.js

@@ -0,0 +1,37 @@
+import { pathId } from './ids.js';
+import { invalidResponse, validateSearchPage } from './validation.js';
+function parameters(options) {
+    if (options.page !== undefined && (!Number.isSafeInteger(options.page) || options.page < 1)) {
+        throw new TypeError('page must be a positive integer');
+    }
+    if (options.sortBy !== undefined && !['created_at.asc', 'created_at.desc'].includes(options.sortBy)) {
+        throw new TypeError('sortBy must be created_at.asc or created_at.desc');
+    }
+    return { language: options.language, page: options.page, sort_by: options.sortBy };
+}
+function validateRatedPage(value, nameField, episodes = false) {
+    const page = validateSearchPage(value);
+    if (!page.results.every((item) => typeof item[nameField] === 'string' &&
+        typeof item.rating === 'number' && Number.isFinite(item.rating) &&
+        item.rating >= 0.5 && item.rating <= 10 && Number.isInteger(item.rating * 2) &&
+        (!episodes || (Number.isSafeInteger(item.show_id) && Number(item.show_id) > 0 &&
+            Number.isSafeInteger(item.season_number) && Number(item.season_number) >= 0 &&
+            Number.isSafeInteger(item.episode_number) && Number(item.episode_number) >= 0)))) {
+        invalidResponse();
+    }
+    return page;
+}
+export function createGuestSessionMethods(http) {
+    const path = (id) => `guest_session/${encodeURIComponent(pathId(id, 'guestSessionId'))}/rated`;
+    return {
+        async ratedMovies(guestSessionId, options = {}) {
+            return validateRatedPage(await http.get(`${path(guestSessionId)}/movies`, parameters(options)), 'title');
+        },
+        async ratedTv(guestSessionId, options = {}) {
+            return validateRatedPage(await http.get(`${path(guestSessionId)}/tv`, parameters(options)), 'name');
+        },
+        async ratedTvEpisodes(guestSessionId, options = {}) {
+            return validateRatedPage(await http.get(`${path(guestSessionId)}/tv/episodes`, parameters(options)), 'name', true);
+        },
+    };
+}

package/dist/http.d.ts

@@ -13,7 +13,7 @@ export declare class TmdbHttpClient {
     private readonly fetchRequest;
     constructor(options: LumosovichOptions);
     get(path: string, parameters?: QueryParameters, options?: GetOptions): Promise<unknown>;
-    post(path: string, parameters: QueryParameters, body: Record<string, unknown>): Promise<unknown>;
+    post(path: string, parameters: QueryParameters, body?: Record<string, unknown>): Promise<unknown>;
     delete(path: string, parameters: QueryParameters): Promise<unknown>;
     private request;
 }

package/dist/index.cjs

@@ -423,11 +423,11 @@ function catalogOptions(options) {
   }
   return { ...pagedLanguage(options), region: options.region?.trim() };
 }
-function sessionParameters(session) {
-  if (!session || typeof session !== "object") {
+function sessionParameters(session2) {
+  if (!session2 || typeof session2 !== "object") {
     throw new TypeError("Supply a sessionId or guestSessionId");
   }
-  const { sessionId, guestSessionId } = session;
+  const { sessionId, guestSessionId } = session2;
   if (Boolean(sessionId) === Boolean(guestSessionId) || sessionId !== void 0 && (typeof sessionId !== "string" || !sessionId.trim()) || guestSessionId !== void 0 && (typeof guestSessionId !== "string" || !guestSessionId.trim())) {
     throw new TypeError("Supply exactly one nonempty sessionId or guestSessionId");
   }
@@ -465,11 +465,11 @@ function createMovieCatalogMethods(http) {
     async upcoming(options = {}) {
       return validateCatalogPage(await http.get("movie/upcoming", catalogOptions(options)), true);
     },
-    async accountStates(id, session) {
+    async accountStates(id, session2) {
       const validId = positiveId(id);
       return validateAccountStates(await http.get(
         `movie/${validId}/account_states`,
-        sessionParameters(session),
+        sessionParameters(session2),
         { includeLanguage: false }
       ), validId);
     },
@@ -495,13 +495,13 @@ function createMovieCatalogMethods(http) {
       const validId = positiveId(id);
       return validateSearchPage(await http.get(`movie/${validId}/similar`, pagedLanguage(options)));
     },
-    async rate(id, value, session) {
+    async rate(id, value, session2) {
       const validId = positiveId(id);
-      return validateRatingResponse(await http.post(`movie/${validId}/rating`, sessionParameters(session), { value: ratingValue(value) }));
+      return validateRatingResponse(await http.post(`movie/${validId}/rating`, sessionParameters(session2), { value: ratingValue(value) }));
     },
-    async deleteRating(id, session) {
+    async deleteRating(id, session2) {
       const validId = positiveId(id);
-      return validateRatingResponse(await http.delete(`movie/${validId}/rating`, sessionParameters(session)));
+      return validateRatingResponse(await http.delete(`movie/${validId}/rating`, sessionParameters(session2)));
     }
   };
 }
@@ -531,11 +531,11 @@ function createTvCatalogMethods(http) {
     async topRated(options = {}) {
       return validateSearchPage(await http.get("tv/top_rated", pagedLanguage(options)));
     },
-    async accountStates(id, session) {
+    async accountStates(id, session2) {
       const validId = positiveId(id);
       return validateAccountStates(await http.get(
         `tv/${validId}/account_states`,
-        sessionParameters(session),
+        sessionParameters(session2),
         { includeLanguage: false }
       ), validId);
     },
@@ -558,15 +558,15 @@ function createTvCatalogMethods(http) {
       const validId = positiveId(id);
       return validateSearchPage(await http.get(`tv/${validId}/similar`, pagedLanguage(options)));
     },
-    async rate(id, value, session) {
+    async rate(id, value, session2) {
       const validId = positiveId(id);
-      return validateRatingResponse(await http.post(`tv/${validId}/rating`, sessionParameters(session), {
+      return validateRatingResponse(await http.post(`tv/${validId}/rating`, sessionParameters(session2), {
         value: ratingValue(value)
       }));
     },
-    async deleteRating(id, session) {
+    async deleteRating(id, session2) {
       const validId = positiveId(id);
-      return validateRatingResponse(await http.delete(`tv/${validId}/rating`, sessionParameters(session)));
+      return validateRatingResponse(await http.delete(`tv/${validId}/rating`, sessionParameters(session2)));
     }
   };
 }
@@ -763,11 +763,11 @@ function episodePath(seriesId, seasonNumber, episodeNumber) {
 // src/tv-season-resources.ts
 function createTvSeasonResourceMethods(http) {
   return {
-    async accountStates(seriesId, seasonNumber, session) {
+    async accountStates(seriesId, seasonNumber, session2) {
       const path = seasonPath(seriesId, seasonNumber);
       return validateSeasonAccountStates(await http.get(
         `${path}/account_states`,
-        sessionParameters(session),
+        sessionParameters(session2),
         { includeLanguage: false }
       ));
     },
@@ -839,11 +839,11 @@ function createTvSeasonResourceMethods(http) {
 // src/tv-episode-resources.ts
 function createTvEpisodeResourceMethods(http) {
   return {
-    async accountStates(seriesId, seasonNumber, episodeNumber, session) {
+    async accountStates(seriesId, seasonNumber, episodeNumber, session2) {
       const path = episodePath(seriesId, seasonNumber, episodeNumber);
       return validateAccountStateShape(await http.get(
         `${path}/account_states`,
-        sessionParameters(session),
+        sessionParameters(session2),
         { includeLanguage: false }
       ));
     },
@@ -900,17 +900,17 @@ function createTvEpisodeResourceMethods(http) {
         videoParameters(options)
       ), { results: metadataChecks.videos });
     },
-    async rate(seriesId, seasonNumber, episodeNumber, value, session) {
+    async rate(seriesId, seasonNumber, episodeNumber, value, session2) {
       const path = episodePath(seriesId, seasonNumber, episodeNumber);
       return validateRatingResponse(await http.post(
         `${path}/rating`,
-        sessionParameters(session),
+        sessionParameters(session2),
         { value: ratingValue(value) }
       ));
     },
-    async deleteRating(seriesId, seasonNumber, episodeNumber, session) {
+    async deleteRating(seriesId, seasonNumber, episodeNumber, session2) {
       const path = episodePath(seriesId, seasonNumber, episodeNumber);
-      return validateRatingResponse(await http.delete(`${path}/rating`, sessionParameters(session)));
+      return validateRatingResponse(await http.delete(`${path}/rating`, sessionParameters(session2)));
     }
   };
 }
@@ -1191,25 +1191,25 @@ var TmdbHttpClient = class {
       throw new TypeError("fetch must be a function");
     }
   }
-  async get(path, parameters2 = {}, options = {}) {
-    return this.request("GET", path, parameters2, options);
+  async get(path, parameters4 = {}, options = {}) {
+    return this.request("GET", path, parameters4, options);
   }
-  async post(path, parameters2, body) {
-    return this.request("POST", path, parameters2, { includeLanguage: false }, body);
+  async post(path, parameters4, body) {
+    return this.request("POST", path, parameters4, { includeLanguage: false }, body);
   }
-  async delete(path, parameters2) {
-    return this.request("DELETE", path, parameters2, { includeLanguage: false });
+  async delete(path, parameters4) {
+    return this.request("DELETE", path, parameters4, { includeLanguage: false });
   }
-  async request(method, path, parameters2, options, body) {
+  async request(method, path, parameters4, options, body) {
     const url = new URL(path, API_BASE_URL);
     if (options.includeLanguage !== false) {
-      const language = parameters2.language ?? this.language;
+      const language = parameters4.language ?? this.language;
       if (typeof language !== "string" || !language.trim()) {
         throw new TypeError("language must not be empty");
       }
       url.searchParams.set("language", language);
     }
-    for (const [key, value] of Object.entries(parameters2)) {
+    for (const [key, value] of Object.entries(parameters4)) {
       if (key !== "language" && value !== void 0) {
         url.searchParams.set(key, String(value));
       }
@@ -1541,12 +1541,12 @@ function region(value) {
   return value;
 }
 function commonParameters(query, options) {
-  const parameters2 = pageParameters(query, options);
+  const parameters4 = pageParameters(query, options);
   if (options.includeAdult !== void 0 && typeof options.includeAdult !== "boolean") {
     throw new TypeError("includeAdult must be a boolean");
   }
   return {
-    ...parameters2,
+    ...parameters4,
     language: options.language,
     include_adult: options.includeAdult
   };
@@ -1577,9 +1577,9 @@ function createSearchMethods(http) {
       return validateSearchPage(payload);
     },
     async movies(query, options = {}) {
-      const parameters2 = commonParameters(query, options);
+      const parameters4 = commonParameters(query, options);
       const payload = await http.get("search/movie", {
-        ...parameters2,
+        ...parameters4,
         year: year(options.year, "year"),
         primary_release_year: year(
           options.primaryReleaseYear,
@@ -1611,6 +1611,165 @@ function createSearchMethods(http) {
   };
 }
 
+// src/list-validation.ts
+function positive2(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function count3(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function nullableString(value) {
+  return value === null || typeof value === "string";
+}
+function movie2(value) {
+  return isRecord(value) && positive2(value.id) && ["title", "original_title", "original_language", "overview", "release_date"].every((key) => typeof value[key] === "string") && typeof value.adult === "boolean" && typeof value.video === "boolean" && Array.isArray(value.genre_ids) && value.genre_ids.every(positive2) && finite(value.popularity) && nullableString(value.poster_path) && nullableString(value.backdrop_path) && finite(value.vote_average) && count3(value.vote_count) && (value.media_type === void 0 || value.media_type === "movie");
+}
+function validateListDetails(value, expectedId) {
+  if (!isRecord(value) || !(value.id === expectedId || value.id === String(expectedId)) || !["created_by", "description", "iso_639_1", "name"].every((key) => typeof value[key] === "string") || !count3(value.favorite_count) || !count3(value.item_count) || !nullableString(value.poster_path) || !Array.isArray(value.items) || !value.items.every(movie2)) {
+    invalidResponse();
+  }
+  return value;
+}
+function validateListItemStatus(value, expectedId) {
+  if (!isRecord(value) || !(value.id === expectedId || value.id === String(expectedId)) || typeof value.item_present !== "boolean") {
+    invalidResponse();
+  }
+  return value;
+}
+function validateListMutation(value) {
+  if (!isRecord(value) || !positive2(value.status_code) || typeof value.status_message !== "string" || value.success !== void 0 && typeof value.success !== "boolean") {
+    invalidResponse();
+  }
+  return value;
+}
+function validateCreateList(value) {
+  const response = validateListMutation(value);
+  if (typeof response.success !== "boolean" || !positive2(response.list_id)) invalidResponse();
+  return response;
+}
+
+// src/lists.ts
+function nonempty(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} must not be empty`);
+  return value;
+}
+function optionalLanguage(value) {
+  return value === void 0 ? void 0 : nonempty(value, "language");
+}
+function session(options) {
+  if (!isRecord(options)) throw new TypeError("sessionId is required");
+  return nonempty(options.sessionId, "sessionId");
+}
+function createListMethods(http) {
+  return {
+    async create(input) {
+      const sessionId = session(input);
+      const name = nonempty(input.name, "name");
+      if (input.description !== void 0 && typeof input.description !== "string") {
+        throw new TypeError("description must be a string");
+      }
+      const language = optionalLanguage(input.language);
+      return validateCreateList(await http.post("list", { session_id: sessionId }, {
+        name,
+        ...input.description === void 0 ? {} : { description: input.description },
+        ...language === void 0 ? {} : { language }
+      }));
+    },
+    async get(listId, options = {}) {
+      positiveId(listId);
+      if (!isRecord(options)) throw new TypeError("options must be an object");
+      if (options.page !== void 0 && (typeof options.page !== "number" || !Number.isSafeInteger(options.page) || options.page < 1)) {
+        throw new TypeError("page must be a positive integer");
+      }
+      return validateListDetails(await http.get(`list/${listId}`, {
+        language: optionalLanguage(options.language),
+        page: options.page
+      }), listId);
+    },
+    async itemStatus(listId, movieId, options = {}) {
+      positiveId(listId);
+      positiveId(movieId);
+      if (!isRecord(options)) throw new TypeError("options must be an object");
+      return validateListItemStatus(await http.get(`list/${listId}/item_status`, {
+        movie_id: movieId,
+        language: optionalLanguage(options.language)
+      }), listId);
+    },
+    async addMovie(listId, movieId, options) {
+      positiveId(listId);
+      positiveId(movieId);
+      return validateListMutation(await http.post(`list/${listId}/add_item`, {
+        session_id: session(options)
+      }, { media_id: movieId }));
+    },
+    async removeMovie(listId, movieId, options) {
+      positiveId(listId);
+      positiveId(movieId);
+      return validateListMutation(await http.post(`list/${listId}/remove_item`, {
+        session_id: session(options)
+      }, { media_id: movieId }));
+    },
+    async clear(listId, options) {
+      positiveId(listId);
+      const sessionId = session(options);
+      if (typeof options.confirm !== "boolean") throw new TypeError("confirm must be a boolean");
+      return validateListMutation(await http.post(`list/${listId}/clear`, {
+        session_id: sessionId,
+        confirm: options.confirm
+      }));
+    },
+    async delete(listId, options) {
+      positiveId(listId);
+      return validateListMutation(await http.delete(`list/${listId}`, { session_id: session(options) }));
+    }
+  };
+}
+
+// src/guest-sessions.ts
+function parameters2(options) {
+  if (options.page !== void 0 && (!Number.isSafeInteger(options.page) || options.page < 1)) {
+    throw new TypeError("page must be a positive integer");
+  }
+  if (options.sortBy !== void 0 && !["created_at.asc", "created_at.desc"].includes(options.sortBy)) {
+    throw new TypeError("sortBy must be created_at.asc or created_at.desc");
+  }
+  return { language: options.language, page: options.page, sort_by: options.sortBy };
+}
+function validateRatedPage(value, nameField, episodes = false) {
+  const page3 = validateSearchPage(value);
+  if (!page3.results.every((item) => typeof item[nameField] === "string" && typeof item.rating === "number" && Number.isFinite(item.rating) && item.rating >= 0.5 && item.rating <= 10 && Number.isInteger(item.rating * 2) && (!episodes || Number.isSafeInteger(item.show_id) && Number(item.show_id) > 0 && Number.isSafeInteger(item.season_number) && Number(item.season_number) >= 0 && Number.isSafeInteger(item.episode_number) && Number(item.episode_number) >= 0))) {
+    invalidResponse();
+  }
+  return page3;
+}
+function createGuestSessionMethods(http) {
+  const path = (id) => `guest_session/${encodeURIComponent(pathId(id, "guestSessionId"))}/rated`;
+  return {
+    async ratedMovies(guestSessionId, options = {}) {
+      return validateRatedPage(
+        await http.get(`${path(guestSessionId)}/movies`, parameters2(options)),
+        "title"
+      );
+    },
+    async ratedTv(guestSessionId, options = {}) {
+      return validateRatedPage(
+        await http.get(`${path(guestSessionId)}/tv`, parameters2(options)),
+        "name"
+      );
+    },
+    async ratedTvEpisodes(guestSessionId, options = {}) {
+      return validateRatedPage(
+        await http.get(`${path(guestSessionId)}/tv/episodes`, parameters2(options)),
+        "name",
+        true
+      );
+    }
+  };
+}
+
 // src/reference-validation.ts
 function strings(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
@@ -1651,6 +1810,37 @@ function validateGenres(value) {
   return value;
 }
 
+// src/watch-providers.ts
+function parameters3(options) {
+  if (options.watchRegion !== void 0 && (typeof options.watchRegion !== "string" || !options.watchRegion.trim())) {
+    throw new TypeError("watchRegion must not be empty");
+  }
+  return { language: options.language, watch_region: options.watchRegion };
+}
+function count4(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function validateProviders(value) {
+  if (!isRecord(value) || !Array.isArray(value.results) || !value.results.every((item) => isRecord(item) && count4(item.provider_id) && item.provider_id > 0 && typeof item.provider_name === "string" && typeof item.logo_path === "string" && count4(item.display_priority) && isRecord(item.display_priorities) && Object.values(item.display_priorities).every(count4))) invalidResponse();
+  return value;
+}
+function createWatchProviderMethods(http) {
+  return {
+    async regions(options = {}) {
+      const value = await http.get("watch/providers/regions", { language: options.language });
+      if (!isRecord(value)) invalidResponse();
+      validateCountries(value.results);
+      return value;
+    },
+    async movies(options = {}) {
+      return validateProviders(await http.get("watch/providers/movie", parameters3(options)));
+    },
+    async tv(options = {}) {
+      return validateProviders(await http.get("watch/providers/tv", parameters3(options)));
+    }
+  };
+}
+
 // src/reference.ts
 function createConfigurationMethods(http) {
   return {
@@ -1710,6 +1900,9 @@ var Lumosovich = class {
   tv;
   people;
   credits;
+  lists;
+  guestSessions;
+  watchProviders;
   images;
   configuration;
   certifications;
@@ -1752,6 +1945,9 @@ var Lumosovich = class {
     this.tv = createTvMethods(http);
     this.people = createPersonMethods(http);
     this.credits = createCreditMethods(http);
+    this.lists = createListMethods(http);
+    this.guestSessions = createGuestSessionMethods(http);
+    this.watchProviders = createWatchProviderMethods(http);
     this.images = createImageMethods();
     this.configuration = createConfigurationMethods(http);
     this.certifications = createCertificationMethods(http);

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import type { CreditMethods } from './person-types.js';
+import type { ListMethods } from './list-types.js';
+import type { GuestSessionMethods } from './guest-session-types.js';
+import type { WatchProviderMethods } from './watch-provider-types.js';
 import type { CertificationMethods, ConfigurationMethods, GenreMethods } from './reference-types.js';
 import type { ExternalIdSource, FindOptions, FindResponse, LumosovichOptions, SearchMethods } from './types.js';
 import type { MovieMethods, PersonMethods, TvMethods } from './detail-types.js';
@@ -7,6 +10,9 @@ import type { CollectionMethods, CompanyMethods } from './metadata-types.js';
 import type { DiscoverMethods, KeywordMethods, NetworkMethods, ReviewMethods, TrendingMethods } from './catalog-types.js';
 export { TmdbError } from './errors.js';
 export type { TmdbErrorCode } from './errors.js';
+export type { ClearListOptions, CreateListInput, CreateListResponse, ListDetails, ListDetailsOptions, ListItemStatus, ListMethods, ListMovie, ListMutationResponse, ListSessionOptions, } from './list-types.js';
+export type { GuestRatedEpisode, GuestRatedMovie, GuestRatedTv, GuestSessionMethods, GuestSessionRatedOptions, } from './guest-session-types.js';
+export type { WatchProviderEntry, WatchProviderListResponse, WatchProviderMethods, WatchProviderOptions, WatchProviderRegionsResponse, } from './watch-provider-types.js';
 export type { CreditDetails, CreditMethods, PersonChangeListOptions, PersonChangeListPage, PersonChangesOptions, PersonChangesResponse, PersonCreditsResponse, PersonExternalIdsResponse, PersonImagesResponse, PersonPopularHit, PersonPopularPage, PersonResourceMethods, PersonTaggedImage, PersonTaggedImagesPage, PersonTranslationsResponse, } from './person-types.js';
 export type { ImageMethods, ImageSize } from './images.js';
 export type { DiscoverMethods, DiscoverCommonOptions, KeywordDetails, KeywordMethods, KeywordMoviesPage, MovieAccountStates, MovieCatalogMethods, MovieCatalogOptions, MovieCatalogPage, MovieChangeListOptions, MovieChangeListPage, MovieDiscoverOptions, MovieListHit, MovieListPage, NetworkAlternativeNamesResponse, NetworkDetails, NetworkImagesResponse, NetworkMethods, RatingResponse, RatingSession, ReviewDetails, ReviewMethods, ReviewPage, ReviewSummary, TrendingMethods, TrendingWindow, TvDiscoverOptions, } from './catalog-types.js';
@@ -33,6 +39,9 @@ export declare class Lumosovich {
     readonly tv: TvMethods;
     readonly people: PersonMethods;
     readonly credits: CreditMethods;
+    readonly lists: ListMethods;
+    readonly guestSessions: GuestSessionMethods;
+    readonly watchProviders: WatchProviderMethods;
     readonly images: ImageMethods;
     readonly configuration: ConfigurationMethods;
     readonly certifications: CertificationMethods;

package/dist/index.js

@@ -6,6 +6,9 @@ import { createDiscoverMethods } from './discover.js';
 import { createKeywordMethods, createNetworkMethods, createReviewMethods, createTrendingMethods, } from './explore.js';
 import { createSearchMethods } from './search.js';
 import { createCreditMethods } from './person-resources.js';
+import { createListMethods } from './lists.js';
+import { createGuestSessionMethods } from './guest-sessions.js';
+import { createWatchProviderMethods } from './watch-providers.js';
 import { createCertificationMethods, createConfigurationMethods, createGenreMethods } from './reference.js';
 import { validateFindResponse } from './validation.js';
 export { TmdbError } from './errors.js';
@@ -24,6 +27,9 @@ export class Lumosovich {
     tv;
     people;
     credits;
+    lists;
+    guestSessions;
+    watchProviders;
     images;
     configuration;
     certifications;
@@ -58,6 +64,9 @@ export class Lumosovich {
         this.tv = createTvMethods(http);
         this.people = createPersonMethods(http);
         this.credits = createCreditMethods(http);
+        this.lists = createListMethods(http);
+        this.guestSessions = createGuestSessionMethods(http);
+        this.watchProviders = createWatchProviderMethods(http);
         this.images = createImageMethods();
         this.configuration = createConfigurationMethods(http);
         this.certifications = createCertificationMethods(http);

package/dist/list-types.d.ts

@@ -0,0 +1,74 @@
+import type { LanguageOptions } from './reference-types.js';
+import type { PageOptions, TmdbId } from './types.js';
+/** Lists require a user session; guest sessions cannot manage lists. */
+export interface ListSessionOptions {
+    sessionId: string;
+}
+export interface CreateListInput extends ListSessionOptions {
+    name: string;
+    description?: string;
+    /** Language stored on the list, separate from the client's response language. */
+    language?: string;
+}
+export interface ListDetailsOptions extends PageOptions, LanguageOptions {
+}
+export interface ClearListOptions extends ListSessionOptions {
+    /** TMDB requires an explicit confirmation query parameter. */
+    confirm: boolean;
+}
+export interface ListMovie {
+    id: TmdbId;
+    title: string;
+    original_title: string;
+    original_language: string;
+    overview: string;
+    adult: boolean;
+    video: boolean;
+    genre_ids: number[];
+    popularity: number;
+    poster_path: string | null;
+    backdrop_path: string | null;
+    release_date: string;
+    vote_average: number;
+    vote_count: number;
+    media_type?: 'movie';
+    [key: string]: unknown;
+}
+export interface ListDetails {
+    /** TMDB's v3 list details example returns the identifier as a string. */
+    id: string | TmdbId;
+    created_by: string;
+    description: string;
+    favorite_count: number;
+    items: ListMovie[];
+    item_count: number;
+    iso_639_1: string;
+    name: string;
+    poster_path: string | null;
+    [key: string]: unknown;
+}
+export interface ListItemStatus {
+    /** TMDB may serialize this list identifier as a string. */
+    id: string | TmdbId;
+    item_present: boolean;
+    [key: string]: unknown;
+}
+export interface ListMutationResponse {
+    status_code: number;
+    status_message: string;
+    success?: boolean;
+    [key: string]: unknown;
+}
+export interface CreateListResponse extends ListMutationResponse {
+    success: boolean;
+    list_id: TmdbId;
+}
+export interface ListMethods {
+    create(input: CreateListInput): Promise<CreateListResponse>;
+    get(listId: TmdbId, options?: ListDetailsOptions): Promise<ListDetails>;
+    itemStatus(listId: TmdbId, movieId: TmdbId, options?: LanguageOptions): Promise<ListItemStatus>;
+    addMovie(listId: TmdbId, movieId: TmdbId, options: ListSessionOptions): Promise<ListMutationResponse>;
+    removeMovie(listId: TmdbId, movieId: TmdbId, options: ListSessionOptions): Promise<ListMutationResponse>;
+    clear(listId: TmdbId, options: ClearListOptions): Promise<ListMutationResponse>;
+    delete(listId: TmdbId, options: ListSessionOptions): Promise<ListMutationResponse>;
+}

package/dist/list-types.js

@@ -0,0 +1 @@
+export {};

package/dist/list-validation.d.ts

@@ -0,0 +1,5 @@
+import type { CreateListResponse, ListDetails, ListItemStatus, ListMutationResponse } from './list-types.js';
+export declare function validateListDetails(value: unknown, expectedId: number): ListDetails;
+export declare function validateListItemStatus(value: unknown, expectedId: number): ListItemStatus;
+export declare function validateListMutation(value: unknown): ListMutationResponse;
+export declare function validateCreateList(value: unknown): CreateListResponse;

package/dist/list-validation.js

@@ -0,0 +1,54 @@
+import { invalidResponse, isRecord } from './validation.js';
+function positive(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function nullableString(value) {
+    return value === null || typeof value === 'string';
+}
+function movie(value) {
+    return isRecord(value) && positive(value.id) &&
+        ['title', 'original_title', 'original_language', 'overview', 'release_date']
+            .every((key) => typeof value[key] === 'string') &&
+        typeof value.adult === 'boolean' && typeof value.video === 'boolean' &&
+        Array.isArray(value.genre_ids) && value.genre_ids.every(positive) &&
+        finite(value.popularity) && nullableString(value.poster_path) &&
+        nullableString(value.backdrop_path) && finite(value.vote_average) &&
+        count(value.vote_count) && (value.media_type === undefined || value.media_type === 'movie');
+}
+export function validateListDetails(value, expectedId) {
+    if (!isRecord(value) ||
+        !(value.id === expectedId || value.id === String(expectedId)) ||
+        !['created_by', 'description', 'iso_639_1', 'name'].every((key) => typeof value[key] === 'string') ||
+        !count(value.favorite_count) || !count(value.item_count) ||
+        !nullableString(value.poster_path) || !Array.isArray(value.items) || !value.items.every(movie)) {
+        invalidResponse();
+    }
+    return value;
+}
+export function validateListItemStatus(value, expectedId) {
+    if (!isRecord(value) ||
+        !(value.id === expectedId || value.id === String(expectedId)) ||
+        typeof value.item_present !== 'boolean') {
+        invalidResponse();
+    }
+    return value;
+}
+export function validateListMutation(value) {
+    if (!isRecord(value) || !positive(value.status_code) || typeof value.status_message !== 'string' ||
+        (value.success !== undefined && typeof value.success !== 'boolean')) {
+        invalidResponse();
+    }
+    return value;
+}
+export function validateCreateList(value) {
+    const response = validateListMutation(value);
+    if (typeof response.success !== 'boolean' || !positive(response.list_id))
+        invalidResponse();
+    return response;
+}

package/dist/lists.d.ts

@@ -0,0 +1,3 @@
+import { TmdbHttpClient } from './http.js';
+import type { ListMethods } from './list-types.js';
+export declare function createListMethods(http: TmdbHttpClient): ListMethods;

package/dist/lists.js

@@ -0,0 +1,80 @@
+import { positiveId } from './ids.js';
+import { validateCreateList, validateListDetails, validateListItemStatus, validateListMutation } from './list-validation.js';
+import { isRecord } from './validation.js';
+function nonempty(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(`${label} must not be empty`);
+    return value;
+}
+function optionalLanguage(value) {
+    return value === undefined ? undefined : nonempty(value, 'language');
+}
+function session(options) {
+    if (!isRecord(options))
+        throw new TypeError('sessionId is required');
+    return nonempty(options.sessionId, 'sessionId');
+}
+export function createListMethods(http) {
+    return {
+        async create(input) {
+            const sessionId = session(input);
+            const name = nonempty(input.name, 'name');
+            if (input.description !== undefined && typeof input.description !== 'string') {
+                throw new TypeError('description must be a string');
+            }
+            const language = optionalLanguage(input.language);
+            return validateCreateList(await http.post('list', { session_id: sessionId }, {
+                name,
+                ...(input.description === undefined ? {} : { description: input.description }),
+                ...(language === undefined ? {} : { language }),
+            }));
+        },
+        async get(listId, options = {}) {
+            positiveId(listId);
+            if (!isRecord(options))
+                throw new TypeError('options must be an object');
+            if (options.page !== undefined && (typeof options.page !== 'number' || !Number.isSafeInteger(options.page) || options.page < 1)) {
+                throw new TypeError('page must be a positive integer');
+            }
+            return validateListDetails(await http.get(`list/${listId}`, {
+                language: optionalLanguage(options.language), page: options.page,
+            }), listId);
+        },
+        async itemStatus(listId, movieId, options = {}) {
+            positiveId(listId);
+            positiveId(movieId);
+            if (!isRecord(options))
+                throw new TypeError('options must be an object');
+            return validateListItemStatus(await http.get(`list/${listId}/item_status`, {
+                movie_id: movieId, language: optionalLanguage(options.language),
+            }), listId);
+        },
+        async addMovie(listId, movieId, options) {
+            positiveId(listId);
+            positiveId(movieId);
+            return validateListMutation(await http.post(`list/${listId}/add_item`, {
+                session_id: session(options),
+            }, { media_id: movieId }));
+        },
+        async removeMovie(listId, movieId, options) {
+            positiveId(listId);
+            positiveId(movieId);
+            return validateListMutation(await http.post(`list/${listId}/remove_item`, {
+                session_id: session(options),
+            }, { media_id: movieId }));
+        },
+        async clear(listId, options) {
+            positiveId(listId);
+            const sessionId = session(options);
+            if (typeof options.confirm !== 'boolean')
+                throw new TypeError('confirm must be a boolean');
+            return validateListMutation(await http.post(`list/${listId}/clear`, {
+                session_id: sessionId, confirm: options.confirm,
+            }));
+        },
+        async delete(listId, options) {
+            positiveId(listId);
+            return validateListMutation(await http.delete(`list/${listId}`, { session_id: session(options) }));
+        },
+    };
+}

package/dist/watch-provider-types.d.ts

@@ -0,0 +1,22 @@
+import type { WatchProvider } from './metadata-types.js';
+import type { Country, LanguageOptions } from './reference-types.js';
+export interface WatchProviderOptions extends LanguageOptions {
+    watchRegion?: string;
+}
+export interface WatchProviderEntry extends WatchProvider {
+    display_priority: number;
+    display_priorities: Record<string, number>;
+}
+export interface WatchProviderRegionsResponse {
+    results: Country[];
+    [key: string]: unknown;
+}
+export interface WatchProviderListResponse {
+    results: WatchProviderEntry[];
+    [key: string]: unknown;
+}
+export interface WatchProviderMethods {
+    regions(options?: LanguageOptions): Promise<WatchProviderRegionsResponse>;
+    movies(options?: WatchProviderOptions): Promise<WatchProviderListResponse>;
+    tv(options?: WatchProviderOptions): Promise<WatchProviderListResponse>;
+}

package/dist/watch-provider-types.js

@@ -0,0 +1 @@
+export {};

package/dist/watch-providers.d.ts

@@ -0,0 +1,3 @@
+import { TmdbHttpClient } from './http.js';
+import type { WatchProviderMethods } from './watch-provider-types.js';
+export declare function createWatchProviderMethods(http: TmdbHttpClient): WatchProviderMethods;

package/dist/watch-providers.js

@@ -0,0 +1,37 @@
+import { validateCountries } from './reference-validation.js';
+import { invalidResponse, isRecord } from './validation.js';
+function parameters(options) {
+    if (options.watchRegion !== undefined &&
+        (typeof options.watchRegion !== 'string' || !options.watchRegion.trim())) {
+        throw new TypeError('watchRegion must not be empty');
+    }
+    return { language: options.language, watch_region: options.watchRegion };
+}
+function count(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function validateProviders(value) {
+    if (!isRecord(value) || !Array.isArray(value.results) || !value.results.every((item) => isRecord(item) && count(item.provider_id) && item.provider_id > 0 &&
+        typeof item.provider_name === 'string' && typeof item.logo_path === 'string' &&
+        count(item.display_priority) && isRecord(item.display_priorities) &&
+        Object.values(item.display_priorities).every(count)))
+        invalidResponse();
+    return value;
+}
+export function createWatchProviderMethods(http) {
+    return {
+        async regions(options = {}) {
+            const value = await http.get('watch/providers/regions', { language: options.language });
+            if (!isRecord(value))
+                invalidResponse();
+            validateCountries(value.results);
+            return value;
+        },
+        async movies(options = {}) {
+            return validateProviders(await http.get('watch/providers/movie', parameters(options)));
+        },
+        async tv(options = {}) {
+            return validateProviders(await http.get('watch/providers/tv', parameters(options)));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmdb-lumosovich",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Typed Node.js client for the TMDB API with IMDb ID lookup for movies, TV shows, and people",
   "keywords": [
     "tmdb",