tmdb-kit 0.1.0-beta.4 → 1.1.0

package/dist/client.d.cts

@@ -0,0 +1,63 @@
+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 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.
+ */
+export type TMDBFactoryOptions = TMDBClientOptions & {
+    transport?: TMDBTransport;
+};
+/**
+ * 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,63 @@
+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 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.
+ */
+export type TMDBFactoryOptions = TMDBClientOptions & {
+    transport?: TMDBTransport;
+};
+/**
+ * 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,74 @@
+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 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.
+ */
+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,74 @@
+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 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.
+ */
+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/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>;
+}

package/dist/http.d.ts

@@ -0,0 +1,80 @@
+import { type QueryDefaults, type QueryParams } from './query.js';
+import type { ImageUrlTransform } from './resources/images.js';
+import type { LanguageCode, RegionCode } from './types.js';
+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>;
+}