@lorenzopant/tmdb 1.20.0 → 1.20.1

package/README.md

@@ -20,122 +20,260 @@ npm install @lorenzopant/tmdb
 // or
 pnpm add @lorenzopant/tmdb
 // or
-yard add @lorenzopant/tmdb
+yarn add @lorenzopant/tmdb
 ```
 
 ---
 
-## Usage
+## Quick Start
 
 ```typescript
-import { TMDB } from "@lorenzopant/tmdb";
-
-const tmdb = new TMDB("your_access_token");
-
-async function searchMovies() {
-	try {
-		const movies = await tmdb.search.movies({ query: "Fight Club" });
-		console.log(movies);
-	} catch (error) {
-		if (error instanceof TMDBError) {
-			console.error("TMDB Error:", error.message);
-			console.error("HTTP Status:", error.http_status_code);
-			console.error("TMDB Status Code:", error.tmdb_status_code);
-		} else {
-			console.error("Unknown error:", error);
-		}
-	}
-}
+import { TMDB, TMDBError } from "@lorenzopant/tmdb";
+
+const tmdb = new TMDB(process.env.TMDB_ACCESS_TOKEN!);
 
-searchMovies();
+const movie = await tmdb.movies.details({ movie_id: 550 });
+console.log(movie.title); // "Fight Club"
 ```
 
 ---
 
-## API
+## Namespaces
+
+Every namespace maps directly to a TMDB API section. All methods are fully typed.
+
+| Namespace                | Description                                                       |
+| ------------------------ | ----------------------------------------------------------------- |
+| `tmdb.movies`            | Movie details, credits, images, videos, recommendations, and more |
+| `tmdb.movie_lists`       | Now Playing, Popular, Top Rated, Upcoming                         |
+| `tmdb.tv_series`         | TV series details, credits, seasons, episode groups               |
+| `tmdb.tv_lists`          | Airing Today, On The Air, Popular, Top Rated TV                   |
+| `tmdb.tv_seasons`        | Season details, credits, images                                   |
+| `tmdb.tv_episodes`       | Episode details, credits, images                                  |
+| `tmdb.tv_episode_groups` | Episode group details                                             |
+| `tmdb.search`            | Search movies, TV shows, people, collections, keywords            |
+| `tmdb.discover`          | Discover movies and TV shows by filter                            |
+| `tmdb.trending`          | Trending movies, TV, and people                                   |
+| `tmdb.people`            | Person details, credits, images, translations                     |
+| `tmdb.people_lists`      | Popular people                                                    |
+| `tmdb.collections`       | Collection details and images                                     |
+| `tmdb.companies`         | Company details, alternative names, images                        |
+| `tmdb.credits`           | Credit details                                                    |
+| `tmdb.genres`            | Movie and TV genre lists                                          |
+| `tmdb.keywords`          | Keyword details and associated movies                             |
+| `tmdb.certifications`    | Movie and TV certifications per region                            |
+| `tmdb.changes`           | Recent content changes                                            |
+| `tmdb.configuration`     | TMDB configuration, countries, languages, timezones               |
+| `tmdb.find`              | Find resources by external ID (IMDb, TVDB, etc.)                  |
+| `tmdb.networks`          | TV network details                                                |
+| `tmdb.watch_providers`   | Watch providers by region                                         |
+| `tmdb.lists`             | User-created list management                                      |
+| `tmdb.account`           | Account details and user lists                                    |
+| `tmdb.authentication`    | Token-based authentication flows                                  |
+| `tmdb.guest_sessions`    | Guest session rated movies/TV/episodes                            |
+| `tmdb.reviews`           | Review details                                                    |
+| `tmdb.images`            | Image URL builder (see below)                                     |
+| `tmdb.v4`                | TMDB API v4 (auth, account, lists — requires JWT)                 |
 
-### `TMDB`
+---
 
-The main client class. **Each API method supports all the parameters supported by TMDB API**, for example the search method supports: query, language, region, year, primary_release_year and so on...
+## Constructor Options
 
-#### Constructor
+```typescript
+const tmdb = new TMDB(accessToken, {
+	language: "en-US", // ISO 639-1: default language for all requests
+	region: "US", // ISO 3166-1: default region for all requests
+	timezone: "America/New_York", // default timezone for TV airing queries
+	logger: true, // enable built-in request/response logging
+	deduplication: true, // deduplicate concurrent identical requests (default: true)
+	rate_limit: true, // auto-queue requests to stay within TMDB rate limits
+	cache: true, // enable in-memory TTL-based response caching
+	images: {
+		secure_images_url: true,
+		default_image_sizes: { posters: "w500", backdrops: "w780" },
+	},
+});
+```
+
+### `logger`
 
 ```typescript
-const tmdb = new TMDB(accessToken: string, options?: TMDBOptions);
+// Built-in console logger
+const tmdb = new TMDB(token, { logger: true });
+
+// Custom logger function
+const tmdb = new TMDB(token, {
+	logger: (entry) => {
+		if (entry.type === "response") {
+			console.log(`[TMDB] ${entry.endpoint} → ${entry.status} (${entry.durationMs}ms)`);
+		}
+	},
+});
 ```
 
-- `accessToken`: **required**. Your TMDB API v4 access token.
-- `options.logger`: Enable debug logging for all network requests.
+### `rate_limit`
 
-Example:
+Automatically queues requests to stay within TMDB's API limits (~40 req/s). Useful for bulk scripts.
 
 ```typescript
-const tmdb = new TMDB("your_access_token", { logger: true });
+// Default limits
+const tmdb = new TMDB(token, { rate_limit: true });
+
+// Custom budget
+const tmdb = new TMDB(token, { rate_limit: { max_requests: 30, per_ms: 1_000 } });
 ```
 
-Custom logger:
+### `cache`
+
+In-memory TTL-based caching for GET requests. Entries expire lazily on access.
 
 ```typescript
-const tmdb = new TMDB("your_access_token", {
-	logger: (entry) => {
-		if (entry.type === "response") {
-			console.log("TMDB:", entry.endpoint, entry.status, entry.durationMs);
-		}
+// 5-minute TTL, no size limit (defaults)
+const tmdb = new TMDB(token, { cache: true });
+
+// Custom TTL and bounded size
+const tmdb = new TMDB(token, {
+	cache: {
+		ttl: 60_000, // 60 seconds
+		max_size: 500, // evict oldest entry when limit is reached
+		excluded_endpoints: ["/trending", /\/discover\//],
+	},
+});
+
+// Runtime cache controls
+tmdb.cache?.invalidate("/movie/now_playing"); // remove one entry
+tmdb.cache?.clear(); // remove all entries
+console.log(tmdb.cache?.size); // number of cached entries
+```
+
+### `interceptors`
+
+Hook into every request or response globally.
+
+```typescript
+const tmdb = new TMDB(token, {
+	interceptors: {
+		request: (ctx) => {
+			// Inject a param into every request
+			return { ...ctx, params: { ...ctx.params, include_adult: false } };
+		},
+		response: {
+			onSuccess: (data) => {
+				myAnalytics.track("tmdb_response", data);
+			},
+			onError: (error) => {
+				Sentry.captureException(error);
+			},
+		},
 	},
 });
 ```
 
 ---
 
-### `Search`
+## Examples
 
-Search for movies:
+### Movie details
 
 ```typescript
-tmdb.search.movies({ query: "Fight Club" });
+const movie = await tmdb.movies.details({ movie_id: 550 });
+console.log(movie.title); // "Fight Club"
+console.log(movie.release_date); // "1999-10-15"
 ```
 
-Returns a **typed response** containing movies.
+### `append_to_response` — typed overloads
 
----
+Fetch related data in a single request. The return type is automatically extended with the appended fields.
+
+```typescript
+const movie = await tmdb.movies.details({
+	movie_id: 550,
+	append_to_response: ["credits", "videos"],
+});
 
-### `Movie Lists`
+// TypeScript knows these are present:
+console.log(movie.credits.cast[0].name);
+console.log(movie.videos.results[0].key);
+```
 
-Now Playing, Popular, Top Rated and Upcoming movies:
+### Search
 
 ```typescript
-tmdb.movie_lists.now_playing();
-tmdb.movie_lists.top_rated();
-tmdb.movie_lists.popular();
-tmdb.movie_lists.upcoming();
+const results = await tmdb.search.movies({ query: "Inception", language: "en-US" });
+console.log(results.results[0].title); // "Inception"
 ```
 
-Returns a **typed response** containing movies.
+### TV series
 
----
+```typescript
+const show = await tmdb.tv_series.details({ series_id: 1396 });
+console.log(show.name); // "Breaking Bad"
 
-### `Movie`
+const season = await tmdb.tv_seasons.details({ series_id: 1396, season_number: 1 });
+console.log(season.episodes.length);
+```
 
-Details, alternative titles, changes, credits, external IDs and more:
+### Discover
 
 ```typescript
-tmdb.movie.details({ movie_id: 550 });
-tmdb.movie.alternative_titles({ movie_id: 550 });
-tmdb.movie.changes({ movie_id: 550 });
-tmdb.movie.credits({ movie_id: 550 });
-tmdb.movie.external_ids({ movie_id: 550 });
+const action = await tmdb.discover.movies({
+	with_genres: "28",
+	sort_by: "vote_average.desc",
+	"vote_count.gte": 1000,
+});
+```
 
-...and more
+### Trending
+
+```typescript
+const trending = await tmdb.trending.movies({ time_window: "week" });
 ```
 
-Returns a **typed response** containing movies.
+### Image URLs
+
+```typescript
+const movie = await tmdb.movies.details({ movie_id: 550 });
+
+// Build a full URL from a path
+const posterUrl = tmdb.images.poster(movie.poster_path!, "w500");
+const backdropUrl = tmdb.images.backdrop(movie.backdrop_path!, "w1280");
+
+// Or enable auto-enrichment so all image paths in every response are resolved automatically
+const tmdb = new TMDB(token, {
+	images: { autocomplete_images: true, secure_images_url: true },
+});
+```
+
+### Error handling
+
+```typescript
+import { TMDB, TMDBError } from "@lorenzopant/tmdb";
+
+try {
+	const movie = await tmdb.movies.details({ movie_id: 0 });
+} catch (error) {
+	if (error instanceof TMDBError) {
+		console.error(error.message); // human-readable message
+		console.error(error.http_status_code); // e.g. 404
+		console.error(error.tmdb_status_code); // TMDB-specific status code
+	}
+}
+```
+
+### TMDB API v4 (requires JWT access token)
+
+```typescript
+const tmdb = new TMDB(jwtAccessToken);
+
+const lists = await tmdb.v4.lists.list({ account_id: "me" });
+```
 
 ---
 
 ## Requirements
 
-- Node.js 18+ recommended
-- Works on frontend (React, Vue) but **don't expose sensitive access tokens** to users!
+- Node.js 18+
+- Works in frontend frameworks (React, Vue, Next.js) — **never expose your access token to the browser in production**
 
 ---
 

package/dist/index.d.mts

@@ -522,6 +522,43 @@ declare class TMDBError extends Error {
   constructor(message: string, http_status: number, tmdb_status_code?: number);
 }
 //#endregion
+//#region src/utils/cache.d.ts
+type CacheOptions = {
+  /**
+   * How long (in milliseconds) each cached entry remains valid.
+   * @default 300_000 (5 minutes)
+   */
+  ttl?: number;
+  /**
+   * Maximum number of entries to hold in memory.
+   * When the store is full the oldest entry is evicted before a new one is inserted.
+   * Defaults to unlimited.
+   */
+  max_size?: number;
+  /**
+   * Endpoints that should never be cached.
+   *
+   * Each pattern is matched against the full cache key (`endpoint?param=value&…`).
+   * - A `string` is matched with `key.startsWith(pattern)`.
+   * - A `RegExp` is tested with `pattern.test(key)`.
+   *
+   * `RegExp` patterns with the global (`g`) or sticky (`y`) flag are automatically
+   * normalized by stripping those flags. Stateful `lastIndex` mutations would otherwise
+   * cause flaky cache behaviour across repeated calls.
+   *
+   * @example
+   * ```ts
+   * // Never cache trending or any discover endpoint
+   * const tmdb = new TMDB(token, {
+   *   cache: {
+   *     excluded_endpoints: ["/trending", /\/discover\//],
+   *   },
+   * });
+   * ```
+   */
+  excluded_endpoints?: (string | RegExp)[];
+};
+//#endregion
 //#region src/utils/logger.d.ts
 type TMDBLoggerEntry = {
   type: "request" | "response" | "error";
@@ -1474,6 +1511,28 @@ type TMDBOptions = {
    * ```
    */
   rate_limit?: boolean | RateLimitOptions;
+  /**
+   * Enables in-memory TTL-based caching for GET requests.
+   *
+   * - `true` — uses the default TTL of 5 minutes with no size limit.
+   * - Pass a {@link CacheOptions} object to customize `ttl` and/or `max_size`.
+   *
+   * Cached responses are served immediately without hitting the network.
+   * Entries expire lazily on access once the TTL has elapsed.
+   * Only `GET` requests are cached; mutations are never cached.
+   *
+   * @default false (disabled)
+   *
+   * @example
+   * ```ts
+   * // Enable with defaults (5-minute TTL)
+   * const tmdb = new TMDB(token, { cache: true });
+   *
+   * // Custom TTL and bounded size
+   * const tmdb = new TMDB(token, { cache: { ttl: 60_000, max_size: 500 } });
+   * ```
+   */
+  cache?: boolean | CacheOptions;
 };
 //#endregion
 //#region src/types/common/certifications.d.ts
@@ -3684,12 +3743,14 @@ declare class ApiClient {
   private onSuccessInterceptor?;
   private onErrorInterceptor?;
   private imageApi?;
+  private responseCache?;
   constructor(accessToken: string, options?: {
     /** @internal API version to target. Used by TMDBv4 — not exposed in TMDBOptions. */version?: 3 | 4;
     logger?: boolean | TMDBLoggerFn;
     deduplication?: boolean;
     images?: ImagesConfig;
     rate_limit?: boolean | RateLimitOptions;
+    cache?: boolean | CacheOptions;
     interceptors?: {
       request?: RequestInterceptor | RequestInterceptor[];
       response?: {
@@ -3723,6 +3784,20 @@ declare class ApiClient {
    * `TMDBOptions.deduplication = false`.
    */
   request<T>(endpoint: string, params?: Record<string, unknown | undefined>): Promise<T>;
+  /**
+   * Removes a single entry from the response cache.
+   *
+   * The key is built from `endpoint` + `params` using the same deterministic algorithm
+   * as the cache itself, so the arguments must match exactly what was used in the original
+   * request (including parameter values and casing).
+   *
+   * @returns `true` if an entry was found and removed, `false` if it was not cached.
+   */
+  invalidateCache(endpoint: string, params?: Record<string, unknown>): boolean;
+  /** Removes all entries from the response cache. */
+  clearCache(): void;
+  /** Returns the number of entries currently held in the response cache. */
+  get cacheSize(): number;
   /**
    * Runs all registered request interceptors in order, threading the context through each one.
    * If an interceptor returns a new context, it replaces the current context for the next interceptor.
@@ -3752,6 +3827,10 @@ declare class ApiClient {
   /**
    * Shared fetch + response-parsing pipeline used by both `request` and `mutate`.
    * Handles URL construction, auth, logging, error mapping, and null sanitisation.
+   *
+   * When called from `request()`, interceptors have already been applied and
+   * `endpoint`/`params` are the effective (post-interceptor) values — interceptors
+   * are skipped. When called from `mutate()`, interceptors run here as normal.
    */
   private execute;
 }
@@ -5696,11 +5775,8 @@ declare class V4ListsAPI extends TMDBAPIBase {
  */
 declare class TMDBv4 {
   private client;
-  /** v4 authentication — request token → access token → logout. */
   auth: V4AuthAPI;
-  /** v4 account — details, lists, favorites, watchlist, rated. */
   account: V4AccountAPI;
-  /** v4 lists — full CRUD for user-created lists. */
   lists: V4ListsAPI;
   constructor(accessToken: string, options?: TMDBOptions);
 }
@@ -5745,6 +5821,27 @@ declare class TMDB {
    */
   get v4(): TMDBv4;
   private _v4;
+  /**
+   * Response cache controls. Only available when `cache` was set in the constructor options.
+   *
+   * - `clear()` — remove all cached entries (e.g. after a user signs out or state resets).
+   * - `invalidate(endpoint, params?)` — remove a single entry by endpoint + params.
+   * - `size` — number of entries currently held in memory.
+   *
+   * @example
+   * ```ts
+   * // Invalidate now_playing after a mutation
+   * tmdb.cache?.invalidate("/movie/now_playing");
+   *
+   * // Clear everything
+   * tmdb.cache?.clear();
+   * ```
+   */
+  get cache(): {
+    clear(): void;
+    invalidate(endpoint: string, params?: Record<string, unknown>): boolean;
+    readonly size: number;
+  } | undefined;
   /**
    * Creates a new TMDB instance.
    * @param accessToken The TMDB API access token.