tmdb-kit 0.1.0-beta.3 → 1.0.0

package/dist/index.d.ts

@@ -8,10 +8,15 @@ interface JsonObject {
 }
 /** Escape hatch for append_to_response payloads and future TMDB fields. */
 type TMDBObject = Record<string, unknown>;
+/** Date string in TMDB format (typically `YYYY-MM-DD`). */
 type TMDBDateString = string;
+/** ISO 639-1 language code (e.g. `"en"`, `"zh"`). */
 type LanguageCode = string;
+/** ISO 3166-1 country/region code (e.g. `"US"`, `"CN"`). */
 type RegionCode = string;
+/** Supported media types for multi-search results. */
 type MediaType = 'movie' | 'tv' | 'person';
+/** Time window for trending endpoints: `"day"` or `"week"`. */
 type TrendingTimeWindow = 'day' | 'week';
 interface PagedResponse<T> {
   page: number;
@@ -220,6 +225,16 @@ type SearchMultiResult = (MovieSummary & {
 }) | (PersonSummary & {
   media_type: 'person';
 });
+/** A single multi-search result narrowed to a specific media type. */
+type MovieMultiResult = MovieSummary & {
+  media_type: 'movie';
+};
+type TVMultiResult = TVSummary & {
+  media_type: 'tv';
+};
+type PersonMultiResult = PersonSummary & {
+  media_type: 'person';
+};
 type TrendingResult = SearchMultiResult;
 interface CreditCastMember {
   adult?: boolean;
@@ -324,6 +339,41 @@ type PosterSize = 'w92' | 'w154' | 'w185' | 'w342' | 'w500' | 'w780' | 'original
 type ProfileSize = 'w45' | 'w185' | 'h632' | 'original' | (string & {});
 type StillSize = 'w92' | 'w185' | 'w300' | 'original' | (string & {});
 type ImageSize = BackdropSize | LogoSize | PosterSize | ProfileSize | StillSize;
+/**
+ * Public set of image sizes TMDB currently documents. The SDK does not
+ * pin to a static copy of the TMDB docs — TMDB has added new sizes in
+ * the past (e.g. `h632` for profile) without notice — but exposing the
+ * canonical list lets callers:
+ *
+ * - iterate over the set to build a size picker
+ * - validate user-supplied sizes with `isKnownBackdropSize(...)` etc.
+ * - type a variable as a "known" size without giving up the
+ *   `(string & {})` escape hatch for forward-compatibility
+ *
+ * If TMDB publishes a new size, the SDK will still accept it at runtime
+ * (every helper is `(string & {})` permissive), but you will need to
+ * add the literal to these constants to get autocomplete on it.
+ */
+declare const KNOWN_BACKDROP_SIZES: readonly ['w300', 'w780', 'w1280', 'original'];
+declare const KNOWN_LOGO_SIZES: readonly ['w45', 'w92', 'w154', 'w185', 'w300', 'w500', 'original'];
+declare const KNOWN_POSTER_SIZES: readonly ['w92', 'w154', 'w185', 'w342', 'w500', 'w780', 'original'];
+declare const KNOWN_PROFILE_SIZES: readonly ['w45', 'w185', 'h632', 'original'];
+declare const KNOWN_STILL_SIZES: readonly ['w92', 'w185', 'w300', 'original'];
+type KnownBackdropSize = (typeof KNOWN_BACKDROP_SIZES)[number];
+type KnownLogoSize = (typeof KNOWN_LOGO_SIZES)[number];
+type KnownPosterSize = (typeof KNOWN_POSTER_SIZES)[number];
+type KnownProfileSize = (typeof KNOWN_PROFILE_SIZES)[number];
+type KnownStillSize = (typeof KNOWN_STILL_SIZES)[number];
+type KnownImageSize = KnownBackdropSize | KnownLogoSize | KnownPosterSize | KnownProfileSize | KnownStillSize;
+/** Union of every documented image size. */
+declare const KNOWN_IMAGE_SIZES: readonly KnownImageSize[];
+declare function isKnownBackdropSize(value: string): value is KnownBackdropSize;
+declare function isKnownLogoSize(value: string): value is KnownLogoSize;
+declare function isKnownPosterSize(value: string): value is KnownPosterSize;
+declare function isKnownProfileSize(value: string): value is KnownProfileSize;
+declare function isKnownStillSize(value: string): value is KnownStillSize;
+/** True if `value` is in any documented size set. */
+declare function isKnownImageSize(value: string): value is KnownImageSize;
 type MovieAppendToResponse = 'account_states' | 'alternative_titles' | 'changes' | 'credits' | 'external_ids' | 'images' | 'keywords' | 'lists' | 'recommendations' | 'release_dates' | 'reviews' | 'similar' | 'translations' | 'videos' | 'watch/providers' | (string & {});
 type TVAppendToResponse = 'account_states' | 'aggregate_credits' | 'alternative_titles' | 'changes' | 'content_ratings' | 'credits' | 'episode_groups' | 'external_ids' | 'images' | 'keywords' | 'recommendations' | 'reviews' | 'screened_theatrically' | 'similar' | 'translations' | 'videos' | 'watch/providers' | (string & {});
 interface ListOptions {
@@ -352,21 +402,36 @@ interface TVSearchOptions extends Omit<ListOptions, 'region'> {
 }
 interface MultiSearchOptions extends Omit<ListOptions, 'region'> {
   includeAdult?: boolean;
+  /**
+   * Media types to exclude from a `search.multi()` response. Filtering is
+   * performed client-side because the TMDB multi-search endpoint does not
+   * support a server-side media_type filter.
+   */
+  exclude?: ReadonlyArray<MediaType>;
 }
 interface ImageQueryOptions extends LanguageOptions {
   includeImageLanguage?: string | readonly string[];
 }
 //#endregion
 //#region src/query.d.ts
+/** Primitives allowed as query parameter values. */
 type QueryPrimitive = string | number | boolean;
+/** A single query parameter value: primitive, array, or nullish. */
 type QueryValue = QueryPrimitive | readonly QueryPrimitive[] | null | undefined;
+/** Key-value map of query parameters for API requests. */
 type QueryParams = Record<string, QueryValue>;
+/** Default query parameters inherited from the client configuration. */
 interface QueryDefaults {
   language?: LanguageCode;
   region?: RegionCode;
 }
 interface BuildImageUrlOptions {
   baseUrl?: string;
+  /**
+   * Transform the resolved TMDB image URL before returning it. Use this to
+   * route requests through a CDN, image proxy, or to add signatures.
+   */
+  transform?: (url: string) => string;
 }
 /**
  * Build a full TMDB image URL from the path returned by API payloads.
@@ -374,7 +439,28 @@ interface BuildImageUrlOptions {
  */
 declare function buildImageUrl(path: string | null | undefined, size?: ImageSize, options?: BuildImageUrlOptions): string | null;
 //#endregion
+//#region src/resources/images.d.ts
+/** Function that transforms a TMDB image URL (e.g. for CDN proxying). */
+type ImageUrlTransform = (url: string) => string;
+/**
+ * Helper for constructing TMDB image URLs from API path values.
+ *
+ * Obtained via `client.images`. Supports optional URL transforms for
+ * routing image requests through a CDN or proxy.
+ */
+declare class ImagesHelper {
+  #private;
+  constructor(transport: TMDBTransport, transform?: ImageUrlTransform);
+  url(path: string | null | undefined, size?: ImageSize, options?: {
+    transform?: ImageUrlTransform;
+  }): string | null;
+}
+//#endregion
 //#region src/http.d.ts
+/**
+ * A minimal fetch-like function signature. Any runtime's native `fetch`
+ * or a test double conforming to this shape can be used.
+ */
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 interface TMDBAccessTokenAuth {
   /** TMDB API Read Access Token. Sent as an Authorization Bearer header. */
@@ -387,28 +473,52 @@ interface TMDBApiKeyAuth {
   accessToken?: never;
 }
 type TMDBAuth = TMDBAccessTokenAuth | TMDBApiKeyAuth;
+/** Internal defaults resolved during client construction. */
 interface TMDBClientDefaults extends QueryDefaults {
   imageBaseUrl: string;
 }
+interface TMDBImagesOptions {
+  /**
+   * Default transform applied to every URL produced by the ImagesHelper.
+   * Use this to route TMDB image requests through a CDN, image proxy, or
+   * to add signed query parameters. Individual calls can still override it
+   * via ImagesHelper.url(path, size, { transform }).
+   */
+  transform?: ImageUrlTransform;
+}
 type TMDBClientOptions = TMDBAuth & {
   /** Defaults to https://api.themoviedb.org/3. Useful for tests or proxies. */baseUrl?: string; /** Inject a fetch implementation for tests, custom runtimes, or instrumentation. */
   fetch?: FetchLike; /** Default language for endpoints that accept a language query parameter. */
   defaultLanguage?: LanguageCode; /** Default region for movie list/search endpoints that accept a region query parameter. */
   defaultRegion?: RegionCode; /** Custom image host. Defaults to https://image.tmdb.org/t/p. */
-  imageBaseUrl?: string; /** Additional headers merged into every request before authentication is applied. */
+  imageBaseUrl?: string; /** Image-helper configuration: host overrides and URL transforms. */
+  images?: TMDBImagesOptions; /** Additional headers merged into every request before authentication is applied. */
   headers?: HeadersInit;
 };
+/** Per-request overrides applied when making a single API call. */
 interface TMDBRequestOptions {
   headers?: HeadersInit;
   query?: QueryParams;
   signal?: AbortSignal;
 }
+/**
+ * Transport abstraction for making HTTP requests to the TMDB API.
+ *
+ * The built-in {@link TMDBHttpClient} implements this interface. You can
+ * provide a custom implementation via {@link TMDBFactoryOptions.transport}
+ * for testing, caching, or instrumentation.
+ */
 interface TMDBTransport {
   readonly defaults: TMDBClientDefaults;
   get<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
 }
 //#endregion
 //#region src/resources/configuration.d.ts
+/**
+ * Access TMDB configuration data (image sizes, countries, languages, etc.).
+ *
+ * Obtained via `client.configuration`.
+ */
 declare class ConfigurationResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -421,6 +531,11 @@ declare class ConfigurationResource {
 }
 //#endregion
 //#region src/resources/genres.d.ts
+/**
+ * Access TMDB genre lists for movies and TV shows.
+ *
+ * Obtained via `client.genres`.
+ */
 declare class GenresResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -428,14 +543,12 @@ declare class GenresResource {
   tv(options?: LanguageOptions): Promise<GenresResponse>;
 }
 //#endregion
-//#region src/resources/images.d.ts
-declare class ImagesHelper {
-  #private;
-  constructor(transport: TMDBTransport);
-  url(path: string | null | undefined, size?: ImageSize): string | null;
-}
-//#endregion
 //#region src/resources/movies.d.ts
+/**
+ * Access TMDB movie endpoints (popular, top-rated, details, credits, etc.).
+ *
+ * Obtained via `client.movies`.
+ */
 declare class MoviesResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -452,6 +565,11 @@ declare class MoviesResource {
 }
 //#endregion
 //#region src/resources/people.d.ts
+/**
+ * Access TMDB person (actor, director, etc.) endpoints.
+ *
+ * Obtained via `client.people`.
+ */
 declare class PeopleResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -460,6 +578,11 @@ declare class PeopleResource {
 }
 //#endregion
 //#region src/resources/search.d.ts
+/**
+ * Search TMDB for movies, TV shows, people, or all media types.
+ *
+ * Obtained via `client.search`.
+ */
 declare class SearchResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -470,6 +593,11 @@ declare class SearchResource {
 }
 //#endregion
 //#region src/resources/trending.d.ts
+/**
+ * Access TMDB trending content (movies, TV, people) for day/week windows.
+ *
+ * Obtained via `client.trending`.
+ */
 declare class TrendingResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -486,6 +614,11 @@ declare class TrendingResource {
 }
 //#endregion
 //#region src/resources/tv.d.ts
+/**
+ * Access TMDB TV show endpoints (popular, top-rated, details, seasons, etc.).
+ *
+ * Obtained via `client.tv`.
+ */
 declare class TVResource {
   #private;
   constructor(transport: TMDBTransport);
@@ -503,6 +636,16 @@ declare class TVResource {
 }
 //#endregion
 //#region src/client.d.ts
+/**
+ * Options accepted by {@link createTMDB} and the {@link TMDBClient} constructor.
+ *
+ * Extends {@link TMDBClientOptions} with an optional {@link TMDBTransport} so
+ * callers can plug in a custom transport (typically for tests, caching, or
+ * instrumentation) without having to mock `fetch` or the factory itself.
+ */
+type TMDBFactoryOptions = TMDBClientOptions & {
+  transport?: TMDBTransport;
+};
 /**
  * Main SDK entry point.
  *
@@ -520,12 +663,36 @@ declare class TMDBClient {
   readonly search: SearchResource;
   readonly trending: TrendingResource;
   readonly tv: TVResource;
-  constructor(options: TMDBClientOptions);
+  constructor(options: TMDBFactoryOptions);
+  /**
+   * Make a raw GET request to any TMDB endpoint.
+   *
+   * This is an escape hatch for endpoints not covered by the typed resource
+   * helpers. The `path` should be relative to the API base URL (e.g.
+   * `/movie/{id}/credits`). Response is parsed as JSON and cast to `T`.
+   *
+   * @param path - API path relative to the base URL (e.g. `/movie/123`)
+   * @param options - Optional request-level overrides (headers, query, signal)
+   * @returns Parsed JSON response typed as `T`
+   */
   request<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
 }
-declare function createTMDB(options: TMDBClientOptions): TMDBClient;
+/**
+ * Create a new {@link TMDBClient} instance.
+ *
+ * @example
+ * ```ts
+ * const tmdb = createTMDB({ accessToken: 'YOUR_TOKEN' })
+ * const { results } = await tmdb.search.movies('Inception')
+ * ```
+ *
+ * @param options - Authentication and configuration options
+ * @returns A configured TMDBClient ready to make API calls
+ */
+declare function createTMDB(options: TMDBFactoryOptions): TMDBClient;
 //#endregion
 //#region src/errors.d.ts
+/** Options for constructing a {@link TMDBResponseError} or its subclasses. */
 interface TMDBResponseErrorOptions {
   body: JsonValue | undefined;
   headers: Headers;
@@ -552,7 +719,65 @@ declare class TMDBResponseError extends TMDBError {
   readonly statusText: string;
   readonly url: string;
   constructor(message: string, options: TMDBResponseErrorOptions);
+  /** True when TMDB has asked the caller to back off (HTTP 429). */
+  get isRateLimit(): boolean;
+  /** True when the resource was not found (HTTP 404). */
+  get isNotFound(): boolean;
+  /** True when the request was rejected as unauthenticated (HTTP 401). */
+  get isUnauthorized(): boolean;
+  /** True when the request was rejected as forbidden (HTTP 403). */
+  get isForbidden(): boolean;
+  /** True when the upstream returned a 5xx server error. */
+  get isServerError(): boolean;
+}
+interface TMDBRateLimitErrorOptions extends TMDBResponseErrorOptions {
+  /** Seconds to wait before retrying. Parsed from the `Retry-After` header. */
+  retryAfter: number;
 }
+/**
+ * Thrown when TMDB returns HTTP 429.
+ *
+ * The SDK does NOT retry automatically — that decision is left to the
+ * caller, since retry policies vary widely. Inspect `retryAfter` to
+ * implement your own backoff.
+ */
+declare class TMDBRateLimitError extends TMDBResponseError {
+  readonly retryAfter: number;
+  constructor(message: string, options: TMDBRateLimitErrorOptions);
+}
+//#endregion
+//#region src/search-guards.d.ts
+/**
+ * Type guard that narrows a `search.multi()` result to a movie entry.
+ *
+ * The `media_type` field is required on every `/search/multi` payload by
+ * TMDB, so this check is safe at runtime and produces a strictly typed
+ * MovieSummary on the narrowed branch.
+ */
+declare function isMovieSearchResult(result: SearchMultiResult): result is MovieMultiResult;
+declare function isMovieSearchResult(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a `search.multi()` result to a TV entry. */
+declare function isTVSearchResult(result: SearchMultiResult): result is TVMultiResult;
+declare function isTVSearchResult(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a `search.multi()` result to a person entry. */
+declare function isPersonSearchResult(result: SearchMultiResult): result is PersonMultiResult;
+declare function isPersonSearchResult(result: unknown): result is PersonMultiResult;
+/**
+ * Convenience alias: `isMovieSearchResult` works on a `search.movies()`
+ * result (which already has the narrow type but is also tagged with
+ * `media_type?: 'movie'`), as well as on multi-search results.
+ */
+declare function isMovie(result: MovieSearchResult | SearchMultiResult): result is MovieMultiResult;
+declare function isMovie(result: SearchMultiResult): result is MovieMultiResult;
+declare function isMovie(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a search result to a TV entry. */
+declare function isTV(result: TVSearchResult | SearchMultiResult): result is TVMultiResult;
+declare function isTV(result: SearchMultiResult): result is TVMultiResult;
+declare function isTV(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a search result to a person entry. */
+declare function isPerson(result: PersonSearchResult | SearchMultiResult): result is PersonMultiResult;
+declare function isPerson(result: SearchMultiResult): result is PersonMultiResult;
+declare function isPerson(result: unknown): result is PersonMultiResult;
 //#endregion
-export { type BackdropSize, type CollectionSummary, type Configuration, type ConfigurationImages, type Country, type CreditCastMember, type CreditCrewMember, type CreditsResponse, type EpisodeGuestStar, type EpisodeSummary, type FetchLike, type Genre, type GenresResponse, type ImageItem, type ImageQueryOptions, type ImageSize, type ImagesResponse, type JobDepartment, type Language, type LanguageCode, type LanguageOptions, type ListOptions, type LogoSize, type MediaType, type MovieAppendToResponse, type MovieDetails, type MovieDetailsOptions, type MovieSearchOptions, type MovieSearchResult, type MovieSummary, type MultiSearchOptions, type Network, type PagedResponse, type PersonDetails, type PersonKnownFor, type PersonKnownForMovie, type PersonKnownForTV, type PersonSearchResult, type PersonSummary, type PosterSize, type ProductionCompany, type ProductionCountry, type ProfileSize, type RegionCode, type SearchMultiResult, type SeasonSummary, type SpokenLanguage, type StillSize, type TMDBAccessTokenAuth, type TMDBApiKeyAuth, type TMDBAuth, TMDBClient, type TMDBClientOptions, type TMDBDateString, TMDBError, type TMDBObject, TMDBRequestError, type TMDBRequestOptions, TMDBResponseError, type TVAppendToResponse, type TVDetails, type TVDetailsOptions, type TVSearchOptions, type TVSearchResult, type TVSeasonAppendToResponse, type TVSeasonDetails, type TVSeasonDetailsOptions, type TVSummary, type Timezone, type TrendingResult, type TrendingTimeWindow, type Video, type VideosResponse, buildImageUrl, createTMDB };
+export { type BackdropSize, type CollectionSummary, type Configuration, type ConfigurationImages, type Country, type CreditCastMember, type CreditCrewMember, type CreditsResponse, type EpisodeGuestStar, type EpisodeSummary, type FetchLike, type Genre, type GenresResponse, type ImageItem, type ImageQueryOptions, type ImageSize, type ImageUrlTransform, type ImagesResponse, type JobDepartment, KNOWN_BACKDROP_SIZES, KNOWN_IMAGE_SIZES, KNOWN_LOGO_SIZES, KNOWN_POSTER_SIZES, KNOWN_PROFILE_SIZES, KNOWN_STILL_SIZES, type KnownBackdropSize, type KnownImageSize, type KnownLogoSize, type KnownPosterSize, type KnownProfileSize, type KnownStillSize, type Language, type LanguageCode, type LanguageOptions, type ListOptions, type LogoSize, type MediaType, type MovieAppendToResponse, type MovieDetails, type MovieDetailsOptions, type MovieMultiResult, type MovieSearchOptions, type MovieSearchResult, type MovieSummary, type MultiSearchOptions, type Network, type PagedResponse, type PersonDetails, type PersonKnownFor, type PersonKnownForMovie, type PersonKnownForTV, type PersonMultiResult, type PersonSearchResult, type PersonSummary, type PosterSize, type ProductionCompany, type ProductionCountry, type ProfileSize, type RegionCode, type SearchMultiResult, type SeasonSummary, type SpokenLanguage, type StillSize, type TMDBAccessTokenAuth, type TMDBApiKeyAuth, type TMDBAuth, TMDBClient, type TMDBClientOptions, type TMDBDateString, TMDBError, type TMDBFactoryOptions, type TMDBImagesOptions, type TMDBObject, TMDBRateLimitError, TMDBRequestError, type TMDBRequestOptions, TMDBResponseError, type TMDBTransport, type TVAppendToResponse, type TVDetails, type TVDetailsOptions, type TVMultiResult, type TVSearchOptions, type TVSearchResult, type TVSeasonAppendToResponse, type TVSeasonDetails, type TVSeasonDetailsOptions, type TVSummary, type Timezone, type TrendingResult, type TrendingTimeWindow, type Video, type VideosResponse, buildImageUrl, createTMDB, isKnownBackdropSize, isKnownImageSize, isKnownLogoSize, isKnownPosterSize, isKnownProfileSize, isKnownStillSize, isMovie, isMovieSearchResult, isPerson, isPersonSearchResult, isTV, isTVSearchResult };
 //# sourceMappingURL=index.d.ts.map