tmdb-lumosovich 0.7.1 → 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, movie, TV, and person details, 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.7.1` covers **109 of 152 TMDB v3 operations**, including all 48 TV 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.
 
-Version `0.7.1` moves the npm package from `lumosovich` to `tmdb-lumosovich`; the public `Lumosovich` class and TMDB API coverage are unchanged. Previously published `lumosovich` versions remain installable, but new projects should use `tmdb-lumosovich`. The read-only live smoke test exercises all 99 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 180 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
 
@@ -348,6 +348,71 @@ const group = groups.results[0]
 
 `changeList()` reports changed series IDs. Episode-group IDs are strings supplied by TMDB. The methods return TMDB's original response fields and preserve empty collections.
 
+## People and credits
+
+Use numeric TMDB person IDs for people resources. Credit details use the string `credit_id` returned in a person's cast or crew record.
+
+```js
+const personId = 31;
+const popularPeople = await tmdb.people.popular({ page: 1 });
+const movieCredits = await tmdb.people.movieCredits(personId);
+const tvCredits = await tmdb.people.tvCredits(personId);
+const combinedCredits = await tmdb.people.combinedCredits(personId);
+const creditId = movieCredits.cast[0]?.credit_id;
+const credit = creditId ? await tmdb.credits.get(creditId) : undefined;
+
+const externalIds = await tmdb.people.externalIds(personId);
+const portraits = await tmdb.people.images(personId);
+const tagged = await tmdb.people.taggedImages(personId, { page: 1 });
+const translations = await tmdb.people.translations(personId);
+const latestPerson = await tmdb.people.latest();
+const changedPeople = await tmdb.people.changeList({ page: 1 });
+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:
@@ -435,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 99 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
 
-People, 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/detail-types.d.ts

@@ -1,4 +1,5 @@
 import type { TmdbId } from './types.js';
+import type { PersonResourceMethods } from './person-types.js';
 import type { MovieMetadataMethods } from './metadata-types.js';
 import type { MovieCatalogMethods } from './catalog-types.js';
 import type { TvCatalogMethods, TvMetadataMethods } from './tv-types.js';
@@ -87,6 +88,7 @@ export interface TvContentRatingsResponse {
 }
 export interface PersonCredit {
     id: TmdbId;
+    credit_id?: string;
     media_type?: 'movie' | 'tv';
     title?: string;
     name?: string;
@@ -251,6 +253,6 @@ export interface TvMethods extends TvMetadataMethods, TvCatalogMethods, TvSeries
         get(seriesId: TmdbId, seasonNumber: number, episodeNumber: number, options?: EpisodeDetailOptions): Promise<TvEpisodeDetails>;
     };
 }
-export interface PersonMethods {
+export interface PersonMethods extends PersonResourceMethods {
     get(id: TmdbId, options?: PersonDetailOptions): Promise<PersonDetails>;
 }

package/dist/details.js

@@ -5,6 +5,7 @@ import { createTvMetadataMethods } from './tv-metadata.js';
 import { createTvSeriesResourceMethods, createTvEpisodeGroupMethods } from './tv-series-resources.js';
 import { createTvSeasonResourceMethods } from './tv-season-resources.js';
 import { createTvEpisodeResourceMethods } from './tv-episode-resources.js';
+import { createPersonResourceMethods } from './person-resources.js';
 import { positiveId, slotNumber } from './ids.js';
 import { validateDetailResponse, validateEpisodeResponse, validateSeasonResponse, } from './validation.js';
 const MOVIE_APPEND = [
@@ -104,6 +105,7 @@ export function createTvMethods(http) {
 }
 export function createPersonMethods(http) {
     return {
+        ...createPersonResourceMethods(http),
         async get(id, options = {}) {
             const validId = positiveId(id);
             const payload = await http.get(`person/${validId}`, detailParameters(options, PERSON_APPEND));

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;
 }