tmdb-kit 1.0.0 → 1.2.0

package/dist/query.d.ts

@@ -0,0 +1,91 @@
+import type { ImageSize, RegionCode, LanguageCode, TrendingTimeWindow } from './types.js';
+/** Primitives allowed as query parameter values. */
+export type QueryPrimitive = string | number | boolean;
+/** A single query parameter value: primitive, array, or nullish. */
+export type QueryValue = QueryPrimitive | readonly QueryPrimitive[] | null | undefined;
+/** Key-value map of query parameters for API requests. */
+export type QueryParams = Record<string, QueryValue>;
+/** Default query parameters inherited from the client configuration. */
+export interface QueryDefaults {
+    language?: LanguageCode;
+    region?: RegionCode;
+}
+export declare const DEFAULT_API_BASE_URL = "https://api.themoviedb.org/3";
+export declare const DEFAULT_IMAGE_BASE_URL = "https://image.tmdb.org/t/p";
+/**
+ * Append query parameters to a URL object.
+ *
+ * - `undefined` and `null` values are skipped.
+ * - Arrays are joined with commas (TMDB convention).
+ * - All values are converted to strings.
+ */
+export declare function appendQuery(url: URL, query: QueryParams): void;
+/**
+ * Merge a language query parameter with client defaults.
+ *
+ * If `query.language` is set it takes precedence; otherwise the client's
+ * default language is used.
+ */
+export declare function withLanguage(defaults: QueryDefaults, query: QueryParams): QueryParams;
+/**
+ * Merge language and region defaults for list endpoints.
+ *
+ * Combines {@link withLanguage} with region fallback from client defaults.
+ */
+export declare function withListDefaults(defaults: QueryDefaults, query: QueryParams): QueryParams;
+/**
+ * Convert a string or string array to a comma-separated list.
+ *
+ * Returns `undefined` if the input is `undefined` (skips the parameter).
+ * TMDB uses comma-separated values for multi-value query parameters.
+ */
+export declare function toCommaList(value: string | readonly string[] | undefined): string | undefined;
+/**
+ * Validate and convert a numeric ID to a string for use in URL paths.
+ *
+ * @throws {TMDBRequestError} If `value` is not a positive integer.
+ */
+export declare function toId(value: number, name: string): string;
+/**
+ * Validate and convert a season number to a string for use in URL paths.
+ *
+ * Season `0` is valid and refers to specials.
+ *
+ * @throws {TMDBRequestError} If `value` is not a non-negative integer.
+ */
+export declare function toSeasonNumber(value: number): string;
+/**
+ * Validate and normalize a string identifier for use in URL paths.
+ *
+ * @throws {TMDBRequestError} If `value` is empty or contains non-identifier characters.
+ */
+export declare function toGroupId(value: string): string;
+/**
+ * Validate and trim a search query string.
+ *
+ * @throws {TMDBRequestError} If the query is empty after trimming.
+ */
+export declare function toSearchQuery(value: string): string;
+/**
+ * Validate a trending time window value.
+ *
+ * @throws {TMDBRequestError} If `value` is not `"day"` or `"week"`.
+ */
+export declare function toTimeWindow(value: TrendingTimeWindow): TrendingTimeWindow;
+export 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.
+ * Returns null for nullish image paths so UI code can branch naturally.
+ */
+export declare function buildImageUrl(path: string | null | undefined, size?: ImageSize, options?: BuildImageUrlOptions): string | null;
+/**
+ * Strip trailing slashes from a base URL to ensure consistent path joining.
+ */
+export declare function normalizeBaseUrl(baseUrl: string): string;

package/dist/resources/configuration.d.cts

@@ -0,0 +1,17 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { Configuration, Country, JobDepartment, Language, RequestOptions, Timezone } from '../types.cjs';
+/**
+ * Access TMDB configuration data (image sizes, countries, languages, etc.).
+ *
+ * Obtained via `client.configuration`.
+ */
+export declare class ConfigurationResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    details(options?: RequestOptions): Promise<Configuration>;
+    countries(options?: RequestOptions): Promise<Country[]>;
+    jobs(options?: RequestOptions): Promise<JobDepartment[]>;
+    languages(options?: RequestOptions): Promise<Language[]>;
+    primaryTranslations(options?: RequestOptions): Promise<string[]>;
+    timezones(options?: RequestOptions): Promise<Timezone[]>;
+}

package/dist/resources/configuration.d.ts

@@ -0,0 +1,17 @@
+import type { TMDBTransport } from '../http.js';
+import type { Configuration, Country, JobDepartment, Language, RequestOptions, Timezone } from '../types.js';
+/**
+ * Access TMDB configuration data (image sizes, countries, languages, etc.).
+ *
+ * Obtained via `client.configuration`.
+ */
+export declare class ConfigurationResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    details(options?: RequestOptions): Promise<Configuration>;
+    countries(options?: RequestOptions): Promise<Country[]>;
+    jobs(options?: RequestOptions): Promise<JobDepartment[]>;
+    languages(options?: RequestOptions): Promise<Language[]>;
+    primaryTranslations(options?: RequestOptions): Promise<string[]>;
+    timezones(options?: RequestOptions): Promise<Timezone[]>;
+}

package/dist/resources/genres.d.cts

@@ -0,0 +1,13 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { GenresResponse, LanguageOptions } from '../types.cjs';
+/**
+ * Access TMDB genre lists for movies and TV shows.
+ *
+ * Obtained via `client.genres`.
+ */
+export declare class GenresResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    movies(options?: LanguageOptions): Promise<GenresResponse>;
+    tv(options?: LanguageOptions): Promise<GenresResponse>;
+}

package/dist/resources/genres.d.ts

@@ -0,0 +1,13 @@
+import type { TMDBTransport } from '../http.js';
+import type { GenresResponse, LanguageOptions } from '../types.js';
+/**
+ * Access TMDB genre lists for movies and TV shows.
+ *
+ * Obtained via `client.genres`.
+ */
+export declare class GenresResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    movies(options?: LanguageOptions): Promise<GenresResponse>;
+    tv(options?: LanguageOptions): Promise<GenresResponse>;
+}

package/dist/resources/images.d.cts

@@ -0,0 +1,17 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { ImageSize } from '../types.cjs';
+/** Function that transforms a TMDB image URL (e.g. for CDN proxying). */
+export 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.
+ */
+export declare class ImagesHelper {
+    #private;
+    constructor(transport: TMDBTransport, transform?: ImageUrlTransform);
+    url(path: string | null | undefined, size?: ImageSize, options?: {
+        transform?: ImageUrlTransform;
+    }): string | null;
+}

package/dist/resources/images.d.ts

@@ -0,0 +1,17 @@
+import type { TMDBTransport } from '../http.js';
+import type { ImageSize } from '../types.js';
+/** Function that transforms a TMDB image URL (e.g. for CDN proxying). */
+export 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.
+ */
+export declare class ImagesHelper {
+    #private;
+    constructor(transport: TMDBTransport, transform?: ImageUrlTransform);
+    url(path: string | null | undefined, size?: ImageSize, options?: {
+        transform?: ImageUrlTransform;
+    }): string | null;
+}

package/dist/resources/movies.d.cts

@@ -0,0 +1,21 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { CreditsResponse, ImageQueryOptions, ImagesResponse, LanguageOptions, ListOptions, MovieDetails, MovieDetailsOptions, MovieSummary, PagedResponse, TMDBObject, VideosResponse } from '../types.cjs';
+/**
+ * Access TMDB movie endpoints (popular, top-rated, details, credits, etc.).
+ *
+ * Obtained via `client.movies`.
+ */
+export declare class MoviesResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    topRated(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    nowPlaying(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    upcoming(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    details<TAppend extends TMDBObject = TMDBObject>(movieId: number, options?: MovieDetailsOptions): Promise<MovieDetails & TAppend>;
+    credits(movieId: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    images(movieId: number, options?: ImageQueryOptions): Promise<ImagesResponse>;
+    recommendations(movieId: number, options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    similar(movieId: number, options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    videos(movieId: number, options?: LanguageOptions): Promise<VideosResponse>;
+}

package/dist/resources/movies.d.ts

@@ -0,0 +1,21 @@
+import type { TMDBTransport } from '../http.js';
+import type { CreditsResponse, ImageQueryOptions, ImagesResponse, LanguageOptions, ListOptions, MovieDetails, MovieDetailsOptions, MovieSummary, PagedResponse, TMDBObject, VideosResponse } from '../types.js';
+/**
+ * Access TMDB movie endpoints (popular, top-rated, details, credits, etc.).
+ *
+ * Obtained via `client.movies`.
+ */
+export declare class MoviesResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    topRated(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    nowPlaying(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    upcoming(options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    details<TAppend extends TMDBObject = TMDBObject>(movieId: number, options?: MovieDetailsOptions): Promise<MovieDetails & TAppend>;
+    credits(movieId: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    images(movieId: number, options?: ImageQueryOptions): Promise<ImagesResponse>;
+    recommendations(movieId: number, options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    similar(movieId: number, options?: ListOptions): Promise<PagedResponse<MovieSummary>>;
+    videos(movieId: number, options?: LanguageOptions): Promise<VideosResponse>;
+}

package/dist/resources/people.d.cts

@@ -0,0 +1,14 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { LanguageOptions, ListOptions, PagedResponse, PersonCombinedCreditsResponse, PersonDetails, PersonSummary } from '../types.cjs';
+/**
+ * Access TMDB person (actor, director, etc.) endpoints.
+ *
+ * Obtained via `client.people`.
+ */
+export declare class PeopleResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<PersonSummary>>;
+    details(personId: number, options?: LanguageOptions): Promise<PersonDetails>;
+    combinedCredits(personId: number, options?: LanguageOptions): Promise<PersonCombinedCreditsResponse>;
+}

package/dist/resources/people.d.ts

@@ -0,0 +1,14 @@
+import type { TMDBTransport } from '../http.js';
+import type { LanguageOptions, ListOptions, PagedResponse, PersonCombinedCreditsResponse, PersonDetails, PersonSummary } from '../types.js';
+/**
+ * Access TMDB person (actor, director, etc.) endpoints.
+ *
+ * Obtained via `client.people`.
+ */
+export declare class PeopleResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<PersonSummary>>;
+    details(personId: number, options?: LanguageOptions): Promise<PersonDetails>;
+    combinedCredits(personId: number, options?: LanguageOptions): Promise<PersonCombinedCreditsResponse>;
+}

package/dist/resources/search.d.cts

@@ -0,0 +1,15 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { MovieSearchOptions, MovieSearchResult, MultiSearchOptions, PagedResponse, PersonSearchResult, SearchMultiResult, TVSearchOptions, TVSearchResult } from '../types.cjs';
+/**
+ * Search TMDB for movies, TV shows, people, or all media types.
+ *
+ * Obtained via `client.search`.
+ */
+export declare class SearchResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    movies(query: string, options?: MovieSearchOptions): Promise<PagedResponse<MovieSearchResult>>;
+    tv(query: string, options?: TVSearchOptions): Promise<PagedResponse<TVSearchResult>>;
+    people(query: string, options?: MultiSearchOptions): Promise<PagedResponse<PersonSearchResult>>;
+    multi(query: string, options?: MultiSearchOptions): Promise<PagedResponse<SearchMultiResult>>;
+}

package/dist/resources/search.d.ts

@@ -0,0 +1,15 @@
+import type { TMDBTransport } from '../http.js';
+import type { MovieSearchOptions, MovieSearchResult, MultiSearchOptions, PagedResponse, PersonSearchResult, SearchMultiResult, TVSearchOptions, TVSearchResult } from '../types.js';
+/**
+ * Search TMDB for movies, TV shows, people, or all media types.
+ *
+ * Obtained via `client.search`.
+ */
+export declare class SearchResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    movies(query: string, options?: MovieSearchOptions): Promise<PagedResponse<MovieSearchResult>>;
+    tv(query: string, options?: TVSearchOptions): Promise<PagedResponse<TVSearchResult>>;
+    people(query: string, options?: MultiSearchOptions): Promise<PagedResponse<PersonSearchResult>>;
+    multi(query: string, options?: MultiSearchOptions): Promise<PagedResponse<SearchMultiResult>>;
+}

package/dist/resources/trending.d.cts

@@ -0,0 +1,23 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { ListOptions, MovieSummary, PagedResponse, PersonSummary, TrendingResult, TrendingTimeWindow, TVSummary } from '../types.cjs';
+type TrendingOptions = Omit<ListOptions, 'region'>;
+/**
+ * Access TMDB trending content (movies, TV, people) for day/week windows.
+ *
+ * Obtained via `client.trending`.
+ */
+export declare class TrendingResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    all(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<TrendingResult>>;
+    movies(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<MovieSummary & {
+        media_type?: 'movie';
+    }>>;
+    tv(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<TVSummary & {
+        media_type?: 'tv';
+    }>>;
+    people(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<PersonSummary & {
+        media_type?: 'person';
+    }>>;
+}
+export {};

package/dist/resources/trending.d.ts

@@ -0,0 +1,23 @@
+import type { TMDBTransport } from '../http.js';
+import type { ListOptions, MovieSummary, PagedResponse, PersonSummary, TrendingResult, TrendingTimeWindow, TVSummary } from '../types.js';
+type TrendingOptions = Omit<ListOptions, 'region'>;
+/**
+ * Access TMDB trending content (movies, TV, people) for day/week windows.
+ *
+ * Obtained via `client.trending`.
+ */
+export declare class TrendingResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    all(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<TrendingResult>>;
+    movies(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<MovieSummary & {
+        media_type?: 'movie';
+    }>>;
+    tv(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<TVSummary & {
+        media_type?: 'tv';
+    }>>;
+    people(timeWindow?: TrendingTimeWindow, options?: TrendingOptions): Promise<PagedResponse<PersonSummary & {
+        media_type?: 'person';
+    }>>;
+}
+export {};

package/dist/resources/tv.d.cts

@@ -0,0 +1,30 @@
+import type { TMDBTransport } from '../http.cjs';
+import type { AggregateCreditsResponse, CreditsResponse, EpisodeDetails, EpisodeDetailsOptions, EpisodeGroupDetails, EpisodeGroupsResponse, ImageQueryOptions, ImagesResponse, LanguageOptions, ListOptions, PagedResponse, SeasonImagesResponse, TMDBObject, TVDetails, TVDetailsOptions, TVSeasonDetails, TVSeasonDetailsOptions, TVSummary, VideosResponse } from '../types.cjs';
+/**
+ * Access TMDB TV show endpoints (popular, top-rated, details, seasons, etc.).
+ *
+ * Obtained via `client.tv`.
+ */
+export declare class TVResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    topRated(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    airingToday(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    onTheAir(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    details<TAppend extends TMDBObject = TMDBObject>(seriesId: number, options?: TVDetailsOptions): Promise<TVDetails & TAppend>;
+    credits(seriesId: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    images(seriesId: number, options?: ImageQueryOptions): Promise<ImagesResponse>;
+    recommendations(seriesId: number, options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    similar(seriesId: number, options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    videos(seriesId: number, options?: LanguageOptions): Promise<VideosResponse>;
+    seasonDetails<TAppend extends TMDBObject = TMDBObject>(seriesId: number, seasonNumber: number, options?: TVSeasonDetailsOptions): Promise<TVSeasonDetails & TAppend>;
+    seasonCredits(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    seasonAggregateCredits(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<AggregateCreditsResponse>;
+    seasonImages(seriesId: number, seasonNumber: number, options?: ImageQueryOptions): Promise<SeasonImagesResponse>;
+    seasonVideos(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<VideosResponse>;
+    episodeDetails<TAppend extends TMDBObject = TMDBObject>(seriesId: number, seasonNumber: number, episodeNumber: number, options?: EpisodeDetailsOptions): Promise<EpisodeDetails & TAppend>;
+    aggregateCredits(seriesId: number, options?: LanguageOptions): Promise<AggregateCreditsResponse>;
+    episodeGroups(seriesId: number, options?: LanguageOptions): Promise<EpisodeGroupsResponse>;
+    episodeGroup(groupId: string, options?: LanguageOptions): Promise<EpisodeGroupDetails>;
+}

package/dist/resources/tv.d.ts

@@ -0,0 +1,30 @@
+import type { TMDBTransport } from '../http.js';
+import type { AggregateCreditsResponse, CreditsResponse, EpisodeDetails, EpisodeDetailsOptions, EpisodeGroupDetails, EpisodeGroupsResponse, ImageQueryOptions, ImagesResponse, LanguageOptions, ListOptions, PagedResponse, SeasonImagesResponse, TMDBObject, TVDetails, TVDetailsOptions, TVSeasonDetails, TVSeasonDetailsOptions, TVSummary, VideosResponse } from '../types.js';
+/**
+ * Access TMDB TV show endpoints (popular, top-rated, details, seasons, etc.).
+ *
+ * Obtained via `client.tv`.
+ */
+export declare class TVResource {
+    #private;
+    constructor(transport: TMDBTransport);
+    popular(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    topRated(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    airingToday(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    onTheAir(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    details<TAppend extends TMDBObject = TMDBObject>(seriesId: number, options?: TVDetailsOptions): Promise<TVDetails & TAppend>;
+    credits(seriesId: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    images(seriesId: number, options?: ImageQueryOptions): Promise<ImagesResponse>;
+    recommendations(seriesId: number, options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    similar(seriesId: number, options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<TVSummary>>;
+    videos(seriesId: number, options?: LanguageOptions): Promise<VideosResponse>;
+    seasonDetails<TAppend extends TMDBObject = TMDBObject>(seriesId: number, seasonNumber: number, options?: TVSeasonDetailsOptions): Promise<TVSeasonDetails & TAppend>;
+    seasonCredits(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<CreditsResponse>;
+    seasonAggregateCredits(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<AggregateCreditsResponse>;
+    seasonImages(seriesId: number, seasonNumber: number, options?: ImageQueryOptions): Promise<SeasonImagesResponse>;
+    seasonVideos(seriesId: number, seasonNumber: number, options?: LanguageOptions): Promise<VideosResponse>;
+    episodeDetails<TAppend extends TMDBObject = TMDBObject>(seriesId: number, seasonNumber: number, episodeNumber: number, options?: EpisodeDetailsOptions): Promise<EpisodeDetails & TAppend>;
+    aggregateCredits(seriesId: number, options?: LanguageOptions): Promise<AggregateCreditsResponse>;
+    episodeGroups(seriesId: number, options?: LanguageOptions): Promise<EpisodeGroupsResponse>;
+    episodeGroup(groupId: string, options?: LanguageOptions): Promise<EpisodeGroupDetails>;
+}

package/dist/search-guards.d.cts

@@ -0,0 +1,32 @@
+import type { MovieMultiResult, MovieSearchResult, PersonMultiResult, PersonSearchResult, SearchMultiResult, TVMultiResult, TVSearchResult } from './types.cjs';
+/**
+ * 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.
+ */
+export declare function isMovieSearchResult(result: SearchMultiResult): result is MovieMultiResult;
+export declare function isMovieSearchResult(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a `search.multi()` result to a TV entry. */
+export declare function isTVSearchResult(result: SearchMultiResult): result is TVMultiResult;
+export declare function isTVSearchResult(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a `search.multi()` result to a person entry. */
+export declare function isPersonSearchResult(result: SearchMultiResult): result is PersonMultiResult;
+export 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.
+ */
+export declare function isMovie(result: MovieSearchResult | SearchMultiResult): result is MovieMultiResult;
+export declare function isMovie(result: SearchMultiResult): result is MovieMultiResult;
+export declare function isMovie(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a search result to a TV entry. */
+export declare function isTV(result: TVSearchResult | SearchMultiResult): result is TVMultiResult;
+export declare function isTV(result: SearchMultiResult): result is TVMultiResult;
+export declare function isTV(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a search result to a person entry. */
+export declare function isPerson(result: PersonSearchResult | SearchMultiResult): result is PersonMultiResult;
+export declare function isPerson(result: SearchMultiResult): result is PersonMultiResult;
+export declare function isPerson(result: unknown): result is PersonMultiResult;

package/dist/search-guards.d.ts

@@ -0,0 +1,32 @@
+import type { MovieMultiResult, MovieSearchResult, PersonMultiResult, PersonSearchResult, SearchMultiResult, TVMultiResult, TVSearchResult } from './types.js';
+/**
+ * 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.
+ */
+export declare function isMovieSearchResult(result: SearchMultiResult): result is MovieMultiResult;
+export declare function isMovieSearchResult(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a `search.multi()` result to a TV entry. */
+export declare function isTVSearchResult(result: SearchMultiResult): result is TVMultiResult;
+export declare function isTVSearchResult(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a `search.multi()` result to a person entry. */
+export declare function isPersonSearchResult(result: SearchMultiResult): result is PersonMultiResult;
+export 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.
+ */
+export declare function isMovie(result: MovieSearchResult | SearchMultiResult): result is MovieMultiResult;
+export declare function isMovie(result: SearchMultiResult): result is MovieMultiResult;
+export declare function isMovie(result: unknown): result is MovieMultiResult;
+/** Type guard that narrows a search result to a TV entry. */
+export declare function isTV(result: TVSearchResult | SearchMultiResult): result is TVMultiResult;
+export declare function isTV(result: SearchMultiResult): result is TVMultiResult;
+export declare function isTV(result: unknown): result is TVMultiResult;
+/** Type guard that narrows a search result to a person entry. */
+export declare function isPerson(result: PersonSearchResult | SearchMultiResult): result is PersonMultiResult;
+export declare function isPerson(result: SearchMultiResult): result is PersonMultiResult;
+export declare function isPerson(result: unknown): result is PersonMultiResult;