tmdb-kit 1.0.0 → 1.2.0

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