tmdb-kit 1.1.0 → 1.2.0

package/dist/client.d.cts

@@ -7,16 +7,24 @@ 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.
  *
- * 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.
+ * 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 & {
+export type TMDBFactoryOptions = (TMDBClientOptions & {
     transport?: TMDBTransport;
-};
+}) | TMDBTransportOptions;
 /**
  * Main SDK entry point.
  *

package/dist/client.d.ts

@@ -7,16 +7,24 @@ 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.
  *
- * 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.
+ * 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 & {
+export type TMDBFactoryOptions = (TMDBClientOptions & {
     transport?: TMDBTransport;
-};
+}) | TMDBTransportOptions;
 /**
  * Main SDK entry point.
  *

package/dist/errors.d.cts

@@ -21,6 +21,17 @@ export declare class TMDBError extends Error {
 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;
@@ -52,7 +63,8 @@ export interface TMDBRateLimitErrorOptions extends TMDBResponseErrorOptions {
  *
  * 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.
+ * 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;

package/dist/errors.d.ts

@@ -21,6 +21,17 @@ export declare class TMDBError extends Error {
 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;
@@ -52,7 +63,8 @@ export interface TMDBRateLimitErrorOptions extends TMDBResponseErrorOptions {
  *
  * 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.
+ * 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;

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>;