tmdb-kit 0.1.0-beta.3 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isaced
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,26 @@
 # tmdb-kit
 
-A tiny, typed, zero-runtime-dependency TMDB SDK for Node.js, Bun, Deno, and edge runtimes.
+[![npm version](https://img.shields.io/npm/v/tmdb-kit)](https://www.npmjs.com/package/tmdb-kit)
+[![CI](https://img.shields.io/github/actions/workflow/status/isaced/tmdb-kit/ci.yml?branch=main)](https://github.com/isaced/tmdb-kit/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/tmdb-kit)](https://github.com/isaced/tmdb-kit/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/isaced/tmdb-kit/actions/workflows/ci.yml)
 
-This package intentionally does not generate code from OpenAPI. It ships a small hand-designed API surface for common TMDB workflows, plus a typed `request<T>()` escape hatch for endpoints that are not wrapped yet.
+A minimal, fully typed TMDB SDK with zero runtime dependencies. Built for Node.js, Bun, Deno, and edge runtimes.
+
+`tmdb-kit` covers the most common TMDB workflows — movies, TV shows, search, trending, people, genres, and more — with a small, hand-crafted API designed for day-to-day use.
 
 ## Features
 
-- Zero runtime dependencies.
-- Built with tsdown and published as ESM + CommonJS.
-- Uses only Web standard APIs: `fetch`, `Headers`, `URL`, and `AbortSignal`.
-- Works in Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and other fetch-compatible runtimes.
-- Typed resources for movies, TV, search, trending, people, genres, configuration, credits, videos, and images.
-- High-coverage unit tests with mocked fetch; no real TMDB requests in tests.
+- **Zero dependencies** — nothing to audit, nothing to conflict.
+- **Universal runtime** — uses only `fetch`, `Headers`, `URL`, and `AbortSignal`. Works on Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and any fetch-compatible environment.
+- **Strict TypeScript** — full type safety with autocomplete for request options, response shapes, image sizes, and error handling.
+- **ESM + CommonJS** — dual-format output via tsdown, ready for any module system.
+- **Typed resources** — first-class methods for movies, TV, search, trending, people, genres, configuration, and images.
+- **Injectable transport** — swap the HTTP layer for tests, caching, or instrumentation without mocking `fetch`.
+- **Image helpers** — build CDN / proxy / signed URLs with per-request transform overrides.
+- **Search type guards** — narrow `search.multi()` results to movies, TV, or people with runtime-checked helpers.
+- **100% test coverage** — comprehensive unit tests with mocked fetch; no real TMDB requests.
 
 ## Install
 
@@ -55,13 +64,15 @@ const tmdb = createTMDB({ accessToken: Deno.env.get('TMDB_ACCESS_TOKEN')! })
 
 ## Authentication
 
-The recommended option is TMDB's API Read Access Token:
+The SDK targets the **TMDB v3 API** (`api.themoviedb.org/3`). Two authentication methods are supported:
+
+**API Read Access Token** (recommended) — works with both v3 and v4:
 
 ```ts
 createTMDB({ accessToken: 'tmdb-read-access-token' })
 ```
 
-The legacy v3 `api_key` query parameter is also supported:
+**Legacy v3 API key** — sent as an `api_key` query parameter:
 
 ```ts
 createTMDB({ apiKey: 'tmdb-v3-api-key' })
@@ -69,6 +80,61 @@ createTMDB({ apiKey: 'tmdb-v3-api-key' })
 
 Exactly one of `accessToken` or `apiKey` is required.
 
+## Configuration
+
+The factory accepts a few options beyond authentication:
+
+```ts
+import { createTMDB } from 'tmdb-kit'
+
+const tmdb = createTMDB({
+  accessToken: 'tmdb-read-access-token',
+
+  // Defaults to https://api.themoviedb.org/3. Useful for tests or proxies.
+  baseUrl: 'https://api.themoviedb.org/3',
+
+  // Inject a fetch implementation. The SDK reads `globalThis.fetch` lazily
+  // on every request, so test-time mocks (vi.spyOn, etc.) are picked up
+  // automatically after the client has been constructed.
+  fetch: customFetch,
+
+  // Defaults applied to every request that supports them.
+  defaultLanguage: 'en-US',
+  defaultRegion: 'US',
+
+  // Custom image host. Defaults to https://image.tmdb.org/t/p.
+  imageBaseUrl: 'https://image.tmdb.org/t/p',
+
+  // Image URL transform applied by the ImagesHelper. See "Image URLs".
+  images: {
+    transform: (url) => url.replace('image.tmdb.org/t/p', 'img-proxy.example/tmdb'),
+  },
+
+  // Extra headers merged into every request before authentication.
+  headers: { 'X-Client': 'my-app' },
+})
+```
+
+### Injecting a custom transport
+
+For tests, caching, or instrumentation, you can swap the entire transport
+layer instead of mocking `fetch`:
+
+```ts
+import { createTMDB, type TMDBTransport } from 'tmdb-kit'
+
+const stub: TMDBTransport = {
+  defaults: { imageBaseUrl: 'https://image.tmdb.org/t/p' },
+  get: async (path, _options) => ({ results: [] }),
+}
+
+const tmdb = createTMDB({ accessToken: 'x', transport: stub })
+```
+
+`transport.get()` is called for every resource and for the `request()`
+escape hatch, so a single stub covers the whole surface area.
+`TMDBTransport` is exported as part of the public API.
+
 ## Supported Resources
 
 ```ts
@@ -93,6 +159,7 @@ tmdb.tv.images(1399)
 tmdb.tv.recommendations(1399)
 tmdb.tv.similar(1399)
 tmdb.tv.videos(1399)
+tmdb.tv.seasonDetails(1399, 1)
 
 tmdb.search.movies('Dune')
 tmdb.search.tv('Dark')
@@ -129,20 +196,157 @@ const response = await tmdb.request<{ results: unknown[] }>('/discover/movie', {
 })
 ```
 
+## Image URLs
+
+`tmdb.images.url(path, size)` builds a fully-qualified image URL. The
+helper returns `null` for nullish paths so UI code can branch naturally:
+
+```ts
+const posterUrl = tmdb.images.url(movie.poster_path, 'w500')
+```
+
+### Routing images through a CDN or proxy
+
+Pass a `transform` callback to rewrite the resolved URL. The most common
+use case is pointing TMDB image requests at a self-hosted proxy:
+
+```ts
+const tmdb = createTMDB({
+  accessToken: 'x',
+  images: {
+    transform: (url) => url.replace('https://image.tmdb.org/t/p', 'https://img-proxy.example/tmdb'),
+  },
+})
+
+tmdb.images.url('/abc.jpg', 'w500')
+// → 'https://img-proxy.example/tmdb/w500/abc.jpg'
+```
+
+You can also pass a one-off transform per call — useful for adding
+signed query parameters for selected sizes:
+
+```ts
+tmdb.images.url('/abc.jpg', 'original', {
+  transform: (url) => `${url}?signature=...`,
+})
+```
+
+The transform is never invoked for nullish paths, so `null` results stay
+`null`.
+
+`buildImageUrl(path, size, options)` is exported directly for callers
+that want to build URLs without a `TMDBClient` instance.
+
+## Search
+
+`search.multi()` returns a union of movie / TV / person results. Filter
+out media types you do not want and narrow the result type with the
+provided type guards:
+
+```ts
+import {
+  createTMDB,
+  isMovieSearchResult,
+  isTVSearchResult,
+  isPersonSearchResult,
+} from 'tmdb-kit'
+
+const { results } = await tmdb.search.multi('Inception', {
+  exclude: ['person'],
+})
+
+const movies = results.filter(isMovieSearchResult) // MovieMultiResult[]
+const tvShows = results.filter(isTVSearchResult) // TVMultiResult[]
+const people = results.filter(isPersonSearchResult) // PersonMultiResult[]
+```
+
+- `exclude` performs client-side filtering — the TMDB multi-search
+  endpoint has no server-side media_type filter. `total_results` reflects
+  the unfiltered payload; the filtered count is just `results.length`.
+- Short-name aliases `isMovie` / `isTV` / `isPerson` are also exported
+  for callers that prefer them.
+- The single-resource search methods (`search.movies`, `search.tv`,
+  `search.people`) already return the narrowed result type, so the
+  guards are only useful for `search.multi()` payloads.
+
+## Image Sizes
+
+The `ImageSize` type is intentionally permissive — TMDB has added new
+sizes in the past (e.g. `h632` for profile) without notice, and the SDK
+keeps the `(string & {})` escape hatch so any future size keeps
+working at runtime. If you need the canonical set of documented sizes,
+the SDK ships them as readonly constants:
+
+```ts
+import {
+  KNOWN_BACKDROP_SIZES,
+  KNOWN_LOGO_SIZES,
+  KNOWN_POSTER_SIZES,
+  KNOWN_PROFILE_SIZES,
+  KNOWN_STILL_SIZES,
+  KNOWN_IMAGE_SIZES,
+  isKnownBackdropSize,
+  isKnownImageSize,
+  // …plus one helper per type
+} from 'tmdb-kit'
+
+// Iterate to build a size picker
+for (const size of KNOWN_POSTER_SIZES) {
+  console.log(size) // 'w92' | 'w154' | 'w185' | 'w342' | 'w500' | 'w780' | 'original'
+}
+
+// Validate user-supplied sizes at runtime
+if (!isKnownPosterSize(userInput)) {
+  throw new Error(`Unknown TMDB poster size: ${userInput}`)
+}
+```
+
+`KnownBackdropSize` / `KnownPosterSize` / `KnownLogoSize` /
+`KnownProfileSize` / `KnownStillSize` / `KnownImageSize` are the
+matching TS literal-union types for callers that want strict typing
+without giving up forward-compatibility.
+
 ## Errors
 
 ```ts
-import { TMDBResponseError } from 'tmdb-kit'
+import {
+  TMDBRateLimitError,
+  TMDBRequestError,
+  TMDBResponseError,
+} from 'tmdb-kit'
 
 try {
   await tmdb.movies.popular()
 } catch (error) {
-  if (error instanceof TMDBResponseError) {
+  if (error instanceof TMDBRateLimitError) {
+    // 429 — TMDB asked the caller to back off. The SDK does NOT retry
+    // automatically; back off for `retryAfter` seconds (or use your own
+    // policy) and try again.
+    console.log('rate limited; retry in', error.retryAfter, 's')
+  } else if (error instanceof TMDBResponseError) {
     console.log(error.status, error.statusCode, error.statusMessage)
+  } else if (error instanceof TMDBRequestError) {
+    // Thrown when a request fails before receiving a response (e.g. network
+    // error, no fetch implementation found, or invalid client configuration).
+    console.log('request error:', error.message)
   }
 }
 ```
 
+`TMDBResponseError` exposes convenience getters for the most common
+status codes:
+
+| Getter | Status |
+| --- | --- |
+| `isUnauthorized` | 401 |
+| `isForbidden` | 403 |
+| `isNotFound` | 404 |
+| `isRateLimit` | 429 |
+| `isServerError` | 5xx |
+
+All errors are also instances of the base class `TMDBError`; use that
+when you want a single catch-all.
+
 ## Development
 
 ```bash