@lorenzopant/tmdb 1.19.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**
 
 ---