tmdb-kit 1.0.0 → 1.2.0

package/dist/client.d.cts

@@ -0,0 +1,71 @@
+import { type TMDBClientOptions, type TMDBRequestOptions, type TMDBTransport } from './http.cjs';
+import { ConfigurationResource } from './resources/configuration.cjs';
+import { GenresResource } from './resources/genres.cjs';
+import { ImagesHelper } from './resources/images.cjs';
+import { MoviesResource } from './resources/movies.cjs';
+import { PeopleResource } from './resources/people.cjs';
+import { SearchResource } from './resources/search.cjs';
+import { TrendingResource } from './resources/trending.cjs';
+import { TVResource } from './resources/tv.cjs';
+/**
+ * Options accepted when the caller supplies a custom transport.
+ *
+ * The transport owns authentication, so credentials are not required.
+ */
+export type TMDBTransportOptions = Omit<TMDBClientOptions, 'accessToken' | 'apiKey'> & {
+    transport: TMDBTransport;
+};
+/**
+ * Options accepted by {@link createTMDB} and the {@link TMDBClient} constructor.
+ *
+ * Either provide credentials for the built-in transport, or pass a custom
+ * {@link TMDBTransport} (typically for tests, caching, or instrumentation)
+ * without credentials.
+ */
+export type TMDBFactoryOptions = (TMDBClientOptions & {
+    transport?: TMDBTransport;
+}) | TMDBTransportOptions;
+/**
+ * Main SDK entry point.
+ *
+ * Resource properties are intentionally small and explicit. The SDK focuses on
+ * common TMDB workflows first, while request<T>() keeps uncommon endpoints easy
+ * to call without waiting for a generated surface area.
+ */
+export declare class TMDBClient {
+    #private;
+    readonly configuration: ConfigurationResource;
+    readonly genres: GenresResource;
+    readonly images: ImagesHelper;
+    readonly movies: MoviesResource;
+    readonly people: PeopleResource;
+    readonly search: SearchResource;
+    readonly trending: TrendingResource;
+    readonly tv: TVResource;
+    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>;
+}
+/**
+ * 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
+ */
+export declare function createTMDB(options: TMDBFactoryOptions): TMDBClient;

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+import { type TMDBClientOptions, type TMDBRequestOptions, type TMDBTransport } from './http.js';
+import { ConfigurationResource } from './resources/configuration.js';
+import { GenresResource } from './resources/genres.js';
+import { ImagesHelper } from './resources/images.js';
+import { MoviesResource } from './resources/movies.js';
+import { PeopleResource } from './resources/people.js';
+import { SearchResource } from './resources/search.js';
+import { TrendingResource } from './resources/trending.js';
+import { TVResource } from './resources/tv.js';
+/**
+ * Options accepted when the caller supplies a custom transport.
+ *
+ * The transport owns authentication, so credentials are not required.
+ */
+export type TMDBTransportOptions = Omit<TMDBClientOptions, 'accessToken' | 'apiKey'> & {
+    transport: TMDBTransport;
+};
+/**
+ * Options accepted by {@link createTMDB} and the {@link TMDBClient} constructor.
+ *
+ * Either provide credentials for the built-in transport, or pass a custom
+ * {@link TMDBTransport} (typically for tests, caching, or instrumentation)
+ * without credentials.
+ */
+export type TMDBFactoryOptions = (TMDBClientOptions & {
+    transport?: TMDBTransport;
+}) | TMDBTransportOptions;
+/**
+ * Main SDK entry point.
+ *
+ * Resource properties are intentionally small and explicit. The SDK focuses on
+ * common TMDB workflows first, while request<T>() keeps uncommon endpoints easy
+ * to call without waiting for a generated surface area.
+ */
+export declare class TMDBClient {
+    #private;
+    readonly configuration: ConfigurationResource;
+    readonly genres: GenresResource;
+    readonly images: ImagesHelper;
+    readonly movies: MoviesResource;
+    readonly people: PeopleResource;
+    readonly search: SearchResource;
+    readonly trending: TrendingResource;
+    readonly tv: TVResource;
+    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>;
+}
+/**
+ * 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
+ */
+export declare function createTMDB(options: TMDBFactoryOptions): TMDBClient;

package/dist/errors.d.cts

@@ -0,0 +1,86 @@
+import type { JsonValue } from './types.cjs';
+/** Raw TMDB error response body structure. */
+export interface TMDBErrorResponseBody {
+    success?: boolean;
+    status_code?: number;
+    status_message?: string;
+}
+/** Options for constructing a {@link TMDBResponseError} or its subclasses. */
+export interface TMDBResponseErrorOptions {
+    body: JsonValue | undefined;
+    headers: Headers;
+    status: number;
+    statusText: string;
+    url: string;
+}
+/** Base class for all SDK-originated errors. */
+export declare class TMDBError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown before a request is sent or when fetch itself rejects. */
+export declare class TMDBRequestError extends TMDBError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a request exceeds the timeout supplied to `withTimeout()`.
+ *
+ * The timeout helper aborts the request's AbortSignal and converts the
+ * resulting abort into this error so timeouts are distinguishable from
+ * caller-initiated cancellation.
+ */
+export declare class TMDBTimeoutError extends TMDBError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, message?: string);
+}
+/** Thrown when TMDB returns a non-2xx response. */
+export declare class TMDBResponseError extends TMDBError {
+    readonly body: JsonValue | undefined;
+    readonly headers: Headers;
+    readonly requestId: string | null;
+    readonly status: number;
+    readonly statusCode: number | undefined;
+    readonly statusMessage: string | undefined;
+    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;
+}
+export 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, or use the optional `retry()` / `withRetry()`
+ * helpers for a TMDB-aware default.
+ */
+export declare class TMDBRateLimitError extends TMDBResponseError {
+    readonly retryAfter: number;
+    constructor(message: string, options: TMDBRateLimitErrorOptions);
+}
+/**
+ * Create the appropriate error instance for a non-2xx TMDB response.
+ *
+ * Returns a {@link TMDBRateLimitError} when the status is 429, otherwise
+ * a generic {@link TMDBResponseError}. The error message is extracted from
+ * the TMDB `status_message` field when available.
+ */
+export declare function createResponseError(options: TMDBResponseErrorOptions): TMDBResponseError;
+/**
+ * Parse the `Retry-After` header into seconds. Accepts both delta-seconds
+ * (e.g. "5") and HTTP-date forms (e.g. "Wed, 21 Oct 2026 07:28:00 GMT").
+ * Falls back to 1 second when the header is missing or unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number;

package/dist/errors.d.ts

@@ -0,0 +1,86 @@
+import type { JsonValue } from './types.js';
+/** Raw TMDB error response body structure. */
+export interface TMDBErrorResponseBody {
+    success?: boolean;
+    status_code?: number;
+    status_message?: string;
+}
+/** Options for constructing a {@link TMDBResponseError} or its subclasses. */
+export interface TMDBResponseErrorOptions {
+    body: JsonValue | undefined;
+    headers: Headers;
+    status: number;
+    statusText: string;
+    url: string;
+}
+/** Base class for all SDK-originated errors. */
+export declare class TMDBError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown before a request is sent or when fetch itself rejects. */
+export declare class TMDBRequestError extends TMDBError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a request exceeds the timeout supplied to `withTimeout()`.
+ *
+ * The timeout helper aborts the request's AbortSignal and converts the
+ * resulting abort into this error so timeouts are distinguishable from
+ * caller-initiated cancellation.
+ */
+export declare class TMDBTimeoutError extends TMDBError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, message?: string);
+}
+/** Thrown when TMDB returns a non-2xx response. */
+export declare class TMDBResponseError extends TMDBError {
+    readonly body: JsonValue | undefined;
+    readonly headers: Headers;
+    readonly requestId: string | null;
+    readonly status: number;
+    readonly statusCode: number | undefined;
+    readonly statusMessage: string | undefined;
+    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;
+}
+export 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, or use the optional `retry()` / `withRetry()`
+ * helpers for a TMDB-aware default.
+ */
+export declare class TMDBRateLimitError extends TMDBResponseError {
+    readonly retryAfter: number;
+    constructor(message: string, options: TMDBRateLimitErrorOptions);
+}
+/**
+ * Create the appropriate error instance for a non-2xx TMDB response.
+ *
+ * Returns a {@link TMDBRateLimitError} when the status is 429, otherwise
+ * a generic {@link TMDBResponseError}. The error message is extracted from
+ * the TMDB `status_message` field when available.
+ */
+export declare function createResponseError(options: TMDBResponseErrorOptions): TMDBResponseError;
+/**
+ * Parse the `Retry-After` header into seconds. Accepts both delta-seconds
+ * (e.g. "5") and HTTP-date forms (e.g. "Wed, 21 Oct 2026 07:28:00 GMT").
+ * Falls back to 1 second when the header is missing or unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number;

package/dist/helpers/cache.d.cts

@@ -0,0 +1,28 @@
+import type { TMDBTransport } from '../http.cjs';
+export interface MemoryCacheOptions {
+    /** Entry lifetime in milliseconds. Defaults to 300000 (5 minutes). */
+    ttlMs?: number;
+    /** Maximum number of cached responses. Defaults to 100. */
+    maxEntries?: number;
+}
+export type MemoryCacheTransport<T extends TMDBTransport = TMDBTransport> = T & {
+    /** Remove every cached response. */
+    clear(): void;
+};
+/**
+ * Wrap a transport with a small in-memory LRU cache.
+ *
+ * Only successful responses are cached. The key includes the path, sorted
+ * query parameters, and sorted headers, so language, region, and header
+ * variants never collide. Signals are intentionally excluded from the key.
+ * Use one cache per client or credential: authentication is not part of the
+ * key.
+ *
+ * ```ts
+ * const http = new TMDBHttpClient({ accessToken })
+ * const tmdb = createTMDB({
+ *   transport: withMemoryCache(http, { ttlMs: 60_000, maxEntries: 200 }),
+ * })
+ * ```
+ */
+export declare function withMemoryCache<T extends TMDBTransport>(transport: T, options?: MemoryCacheOptions): MemoryCacheTransport<T>;

package/dist/helpers/cache.d.ts

@@ -0,0 +1,28 @@
+import type { TMDBTransport } from '../http.js';
+export interface MemoryCacheOptions {
+    /** Entry lifetime in milliseconds. Defaults to 300000 (5 minutes). */
+    ttlMs?: number;
+    /** Maximum number of cached responses. Defaults to 100. */
+    maxEntries?: number;
+}
+export type MemoryCacheTransport<T extends TMDBTransport = TMDBTransport> = T & {
+    /** Remove every cached response. */
+    clear(): void;
+};
+/**
+ * Wrap a transport with a small in-memory LRU cache.
+ *
+ * Only successful responses are cached. The key includes the path, sorted
+ * query parameters, and sorted headers, so language, region, and header
+ * variants never collide. Signals are intentionally excluded from the key.
+ * Use one cache per client or credential: authentication is not part of the
+ * key.
+ *
+ * ```ts
+ * const http = new TMDBHttpClient({ accessToken })
+ * const tmdb = createTMDB({
+ *   transport: withMemoryCache(http, { ttlMs: 60_000, maxEntries: 200 }),
+ * })
+ * ```
+ */
+export declare function withMemoryCache<T extends TMDBTransport>(transport: T, options?: MemoryCacheOptions): MemoryCacheTransport<T>;

package/dist/helpers/pagination.d.cts

@@ -0,0 +1,35 @@
+import type { PagedResponse } from '../types.cjs';
+/** Fetches a single page. The caller closes over its own query options. */
+export interface PageFetcher<T> {
+    (page: number): Promise<PagedResponse<T>>;
+}
+export interface PaginateOptions {
+    /** First page to request. Defaults to 1. */
+    startPage?: number;
+    /** Last page to request, inclusive. Defaults to 500, TMDB's documented cap. */
+    endPage?: number;
+    /** Cancels the iteration before the next request. */
+    signal?: AbortSignal;
+}
+/**
+ * Iterate a paged TMDB endpoint page by page.
+ *
+ * Stops when the API reports the last page, when a page has no results,
+ * when `endPage` is reached, or when the signal is aborted. Yields nothing
+ * when `endPage` is lower than `startPage`. The fetcher
+ * receives the page number and should forward the signal to the SDK:
+ *
+ * ```ts
+ * for await (const page of paginate((page) => tmdb.movies.popular({ page, signal }))) {
+ *   console.log(page.page, page.results.length)
+ * }
+ * ```
+ */
+export declare function paginate<T>(fetchPage: PageFetcher<T>, options?: PaginateOptions): AsyncGenerator<PagedResponse<T>, void, undefined>;
+/**
+ * Iterate a paged TMDB endpoint item by item.
+ *
+ * Built on {@link paginate}; use `paginate` directly when you need page
+ * metadata such as `total_pages`.
+ */
+export declare function paginateItems<T>(fetchPage: PageFetcher<T>, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;

package/dist/helpers/pagination.d.ts

@@ -0,0 +1,35 @@
+import type { PagedResponse } from '../types.js';
+/** Fetches a single page. The caller closes over its own query options. */
+export interface PageFetcher<T> {
+    (page: number): Promise<PagedResponse<T>>;
+}
+export interface PaginateOptions {
+    /** First page to request. Defaults to 1. */
+    startPage?: number;
+    /** Last page to request, inclusive. Defaults to 500, TMDB's documented cap. */
+    endPage?: number;
+    /** Cancels the iteration before the next request. */
+    signal?: AbortSignal;
+}
+/**
+ * Iterate a paged TMDB endpoint page by page.
+ *
+ * Stops when the API reports the last page, when a page has no results,
+ * when `endPage` is reached, or when the signal is aborted. Yields nothing
+ * when `endPage` is lower than `startPage`. The fetcher
+ * receives the page number and should forward the signal to the SDK:
+ *
+ * ```ts
+ * for await (const page of paginate((page) => tmdb.movies.popular({ page, signal }))) {
+ *   console.log(page.page, page.results.length)
+ * }
+ * ```
+ */
+export declare function paginate<T>(fetchPage: PageFetcher<T>, options?: PaginateOptions): AsyncGenerator<PagedResponse<T>, void, undefined>;
+/**
+ * Iterate a paged TMDB endpoint item by item.
+ *
+ * Built on {@link paginate}; use `paginate` directly when you need page
+ * metadata such as `total_pages`.
+ */
+export declare function paginateItems<T>(fetchPage: PageFetcher<T>, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;

package/dist/helpers/retry.d.cts

@@ -0,0 +1,47 @@
+import type { TMDBTransport } from '../http.cjs';
+export interface RetryInfo {
+    /** Zero-based attempt number that failed. */
+    attempt: number;
+    /** Delay before the next attempt, in milliseconds. */
+    delayMs: number;
+    error: unknown;
+}
+export interface RetryOptions {
+    /** Retries after the first attempt. Defaults to 2. */
+    retries?: number;
+    /** Base delay for exponential backoff in milliseconds. Defaults to 250. */
+    baseDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. Defaults to 10000. */
+    maxDelayMs?: number;
+    /** Exponential backoff factor. Defaults to 2. */
+    factor?: number;
+    /** Apply full jitter to exponential delays. Defaults to true. */
+    jitter?: boolean;
+    /** Cancels the delay and any further attempts. */
+    signal?: AbortSignal;
+    /** Replaces the default retry predicate. */
+    retryOn?: (error: unknown, attempt: number) => boolean;
+    /** Observes each retry decision without changing it. */
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Retry an async task using TMDB-aware defaults.
+ *
+ * Retries 429 and any response that carries `Retry-After`, retries 408 and
+ * 5xx responses plus network failures with exponential backoff, and never
+ * retries other 4xx responses, validation errors, aborts, or timeouts. All
+ * TMDB requests are GETs, so the helper is safe for every resource method.
+ */
+export declare function retry<T>(task: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Wrap a transport so every request uses {@link retry}.
+ *
+ * ```ts
+ * const http = new TMDBHttpClient({ accessToken })
+ * const tmdb = createTMDB({ transport: withRetry(http, { retries: 3 }) })
+ * ```
+ *
+ * A wrapper-level `signal` and a per-request `signal` are combined, so
+ * aborting either cancels the call. Extra transport members are preserved.
+ */
+export declare function withRetry<T extends TMDBTransport>(transport: T, options?: RetryOptions): T;

package/dist/helpers/retry.d.ts

@@ -0,0 +1,47 @@
+import type { TMDBTransport } from '../http.js';
+export interface RetryInfo {
+    /** Zero-based attempt number that failed. */
+    attempt: number;
+    /** Delay before the next attempt, in milliseconds. */
+    delayMs: number;
+    error: unknown;
+}
+export interface RetryOptions {
+    /** Retries after the first attempt. Defaults to 2. */
+    retries?: number;
+    /** Base delay for exponential backoff in milliseconds. Defaults to 250. */
+    baseDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. Defaults to 10000. */
+    maxDelayMs?: number;
+    /** Exponential backoff factor. Defaults to 2. */
+    factor?: number;
+    /** Apply full jitter to exponential delays. Defaults to true. */
+    jitter?: boolean;
+    /** Cancels the delay and any further attempts. */
+    signal?: AbortSignal;
+    /** Replaces the default retry predicate. */
+    retryOn?: (error: unknown, attempt: number) => boolean;
+    /** Observes each retry decision without changing it. */
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Retry an async task using TMDB-aware defaults.
+ *
+ * Retries 429 and any response that carries `Retry-After`, retries 408 and
+ * 5xx responses plus network failures with exponential backoff, and never
+ * retries other 4xx responses, validation errors, aborts, or timeouts. All
+ * TMDB requests are GETs, so the helper is safe for every resource method.
+ */
+export declare function retry<T>(task: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Wrap a transport so every request uses {@link retry}.
+ *
+ * ```ts
+ * const http = new TMDBHttpClient({ accessToken })
+ * const tmdb = createTMDB({ transport: withRetry(http, { retries: 3 }) })
+ * ```
+ *
+ * A wrapper-level `signal` and a per-request `signal` are combined, so
+ * aborting either cancels the call. Extra transport members are preserved.
+ */
+export declare function withRetry<T extends TMDBTransport>(transport: T, options?: RetryOptions): T;

package/dist/helpers/timeout.d.cts

@@ -0,0 +1,20 @@
+export interface TimeoutOptions {
+    /** Parent signal. Aborting it cancels the task with the same reason. */
+    signal?: AbortSignal;
+    /** Custom message for the TMDBTimeoutError. */
+    message?: string;
+}
+/**
+ * Run a task with an AbortSignal-backed timeout.
+ *
+ * The task must forward the provided signal to the SDK for cancellation to
+ * take effect. Timeouts are reported as {@link TMDBTimeoutError}; aborts from
+ * the parent signal keep the parent's reason.
+ *
+ * ```ts
+ * const movie = await withTimeout(5_000, (signal) =>
+ *   tmdb.movies.details(550, { signal }),
+ * )
+ * ```
+ */
+export declare function withTimeout<T>(timeoutMs: number, task: (signal: AbortSignal) => Promise<T>, options?: TimeoutOptions): Promise<T>;

package/dist/helpers/timeout.d.ts

@@ -0,0 +1,20 @@
+export interface TimeoutOptions {
+    /** Parent signal. Aborting it cancels the task with the same reason. */
+    signal?: AbortSignal;
+    /** Custom message for the TMDBTimeoutError. */
+    message?: string;
+}
+/**
+ * Run a task with an AbortSignal-backed timeout.
+ *
+ * The task must forward the provided signal to the SDK for cancellation to
+ * take effect. Timeouts are reported as {@link TMDBTimeoutError}; aborts from
+ * the parent signal keep the parent's reason.
+ *
+ * ```ts
+ * const movie = await withTimeout(5_000, (signal) =>
+ *   tmdb.movies.details(550, { signal }),
+ * )
+ * ```
+ */
+export declare function withTimeout<T>(timeoutMs: number, task: (signal: AbortSignal) => Promise<T>, options?: TimeoutOptions): Promise<T>;

package/dist/http.d.cts

@@ -0,0 +1,80 @@
+import { type QueryDefaults, type QueryParams } from './query.cjs';
+import type { ImageUrlTransform } from './resources/images.cjs';
+import type { LanguageCode, RegionCode } from './types.cjs';
+export type { ImageUrlTransform };
+/**
+ * A minimal fetch-like function signature. Any runtime's native `fetch`
+ * or a test double conforming to this shape can be used.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface TMDBAccessTokenAuth {
+    /** TMDB API Read Access Token. Sent as an Authorization Bearer header. */
+    accessToken: string;
+    apiKey?: never;
+}
+export interface TMDBApiKeyAuth {
+    /** Legacy v3 API key. Sent as api_key query parameter. */
+    apiKey: string;
+    accessToken?: never;
+}
+export type TMDBAuth = TMDBAccessTokenAuth | TMDBApiKeyAuth;
+/** Internal defaults resolved during client construction. */
+export interface TMDBClientDefaults extends QueryDefaults {
+    imageBaseUrl: string;
+}
+export 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;
+}
+export 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;
+    /** 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. */
+export 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.
+ */
+export interface TMDBTransport {
+    readonly defaults: TMDBClientDefaults;
+    get<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
+}
+/**
+ * Built-in HTTP transport that uses the Fetch API.
+ *
+ * Handles authentication (API key or access token), URL construction,
+ * request headers, and response parsing. Use the factory function
+ * {@link createTMDB} instead of instantiating this directly.
+ */
+export declare class TMDBHttpClient implements TMDBTransport {
+    #private;
+    readonly defaults: TMDBClientDefaults;
+    readonly imageTransform: ImageUrlTransform | undefined;
+    constructor(options: TMDBClientOptions);
+    get<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
+}