tmdb-kit 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,513 @@
+//#region src/types.d.ts
+/** Primitive JSON values returned by TMDB. */
+type JsonPrimitive = string | number | boolean | null;
+/** JSON object/array tree returned by TMDB for fields this SDK does not model yet. */
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+  [key: string]: JsonValue | undefined;
+}
+/** Escape hatch for append_to_response payloads and future TMDB fields. */
+type TMDBObject = Record<string, unknown>;
+type TMDBDateString = string;
+type LanguageCode = string;
+type RegionCode = string;
+type MediaType = 'movie' | 'tv' | 'person';
+type TrendingTimeWindow = 'day' | 'week';
+interface PagedResponse<T> {
+  page: number;
+  results: T[];
+  total_pages: number;
+  total_results: number;
+}
+interface Genre {
+  id: number;
+  name: string;
+}
+interface ProductionCompany {
+  id: number;
+  logo_path: string | null;
+  name: string;
+  origin_country: string;
+}
+interface ProductionCountry {
+  iso_3166_1: string;
+  name: string;
+}
+interface SpokenLanguage {
+  english_name: string;
+  iso_639_1: string;
+  name: string;
+}
+interface CollectionSummary {
+  id: number;
+  name: string;
+  poster_path: string | null;
+  backdrop_path: string | null;
+}
+interface MovieSummary {
+  adult: boolean;
+  backdrop_path: string | null;
+  genre_ids: number[];
+  id: number;
+  original_language: string;
+  original_title: string;
+  overview: string;
+  popularity: number;
+  poster_path: string | null;
+  release_date: TMDBDateString;
+  title: string;
+  video: boolean;
+  vote_average: number;
+  vote_count: number;
+}
+interface MovieDetails extends Omit<MovieSummary, 'genre_ids'> {
+  belongs_to_collection: CollectionSummary | null;
+  budget: number;
+  genres: Genre[];
+  homepage: string | null;
+  imdb_id: string | null;
+  origin_country?: string[];
+  production_companies: ProductionCompany[];
+  production_countries: ProductionCountry[];
+  revenue: number;
+  runtime: number | null;
+  spoken_languages: SpokenLanguage[];
+  status: string;
+  tagline: string | null;
+}
+interface TVSummary {
+  adult?: boolean;
+  backdrop_path: string | null;
+  first_air_date: TMDBDateString;
+  genre_ids: number[];
+  id: number;
+  name: string;
+  origin_country: string[];
+  original_language: string;
+  original_name: string;
+  overview: string;
+  popularity: number;
+  poster_path: string | null;
+  vote_average: number;
+  vote_count: number;
+}
+interface CreatedBy {
+  id: number;
+  credit_id: string;
+  name: string;
+  gender: number;
+  profile_path: string | null;
+}
+interface Network {
+  id: number;
+  logo_path: string | null;
+  name: string;
+  origin_country: string;
+}
+interface SeasonSummary {
+  air_date: TMDBDateString | null;
+  episode_count: number;
+  id: number;
+  name: string;
+  overview: string;
+  poster_path: string | null;
+  season_number: number;
+  vote_average: number;
+}
+interface TVDetails extends Omit<TVSummary, 'genre_ids'> {
+  created_by: CreatedBy[];
+  episode_run_time: number[];
+  genres: Genre[];
+  homepage: string | null;
+  in_production: boolean;
+  languages: string[];
+  last_air_date: TMDBDateString | null;
+  networks: Network[];
+  number_of_episodes: number;
+  number_of_seasons: number;
+  production_companies: ProductionCompany[];
+  production_countries: ProductionCountry[];
+  seasons: SeasonSummary[];
+  spoken_languages: SpokenLanguage[];
+  status: string;
+  tagline: string | null;
+  type: string;
+}
+interface PersonKnownForMovie extends MovieSummary {
+  media_type: 'movie';
+}
+interface PersonKnownForTV extends TVSummary {
+  media_type: 'tv';
+}
+type PersonKnownFor = PersonKnownForMovie | PersonKnownForTV;
+interface PersonSummary {
+  adult: boolean;
+  gender: number;
+  id: number;
+  known_for: PersonKnownFor[];
+  known_for_department: string;
+  name: string;
+  original_name?: string;
+  popularity: number;
+  profile_path: string | null;
+}
+interface PersonDetails extends Omit<PersonSummary, 'known_for'> {
+  also_known_as: string[];
+  biography: string;
+  birthday: TMDBDateString | null;
+  deathday: TMDBDateString | null;
+  homepage: string | null;
+  imdb_id: string | null;
+  place_of_birth: string | null;
+}
+interface MovieSearchResult extends MovieSummary {
+  media_type?: 'movie';
+}
+interface TVSearchResult extends TVSummary {
+  media_type?: 'tv';
+}
+interface PersonSearchResult extends PersonSummary {
+  media_type?: 'person';
+}
+type SearchMultiResult = (MovieSummary & {
+  media_type: 'movie';
+}) | (TVSummary & {
+  media_type: 'tv';
+}) | (PersonSummary & {
+  media_type: 'person';
+});
+type TrendingResult = SearchMultiResult;
+interface CreditCastMember {
+  adult?: boolean;
+  cast_id?: number;
+  character: string;
+  credit_id: string;
+  gender: number | null;
+  id: number;
+  known_for_department: string;
+  name: string;
+  order: number;
+  original_name: string;
+  popularity: number;
+  profile_path: string | null;
+}
+interface CreditCrewMember {
+  adult?: boolean;
+  credit_id: string;
+  department: string;
+  gender: number | null;
+  id: number;
+  job: string;
+  known_for_department: string;
+  name: string;
+  original_name: string;
+  popularity: number;
+  profile_path: string | null;
+}
+interface CreditsResponse {
+  id: number;
+  cast: CreditCastMember[];
+  crew: CreditCrewMember[];
+}
+interface Video {
+  id: string;
+  iso_3166_1: string;
+  iso_639_1: string;
+  key: string;
+  name: string;
+  official: boolean;
+  published_at: string;
+  site: string;
+  size: number;
+  type: string;
+}
+interface VideosResponse {
+  id: number;
+  results: Video[];
+}
+interface ImageItem {
+  aspect_ratio: number;
+  height: number;
+  iso_639_1: string | null;
+  file_path: string;
+  vote_average: number;
+  vote_count: number;
+  width: number;
+}
+interface ImagesResponse {
+  id: number;
+  backdrops: ImageItem[];
+  logos?: ImageItem[];
+  posters: ImageItem[];
+}
+interface ConfigurationImages {
+  base_url: string;
+  secure_base_url: string;
+  backdrop_sizes: string[];
+  logo_sizes: string[];
+  poster_sizes: string[];
+  profile_sizes: string[];
+  still_sizes: string[];
+}
+interface Configuration {
+  images: ConfigurationImages;
+  change_keys: string[];
+}
+interface Country {
+  iso_3166_1: string;
+  english_name: string;
+  native_name: string;
+}
+interface Language {
+  iso_639_1: string;
+  english_name: string;
+  name: string;
+}
+interface Timezone {
+  iso_3166_1: string;
+  zones: string[];
+}
+interface JobDepartment {
+  department: string;
+  jobs: string[];
+}
+interface GenresResponse {
+  genres: Genre[];
+}
+type BackdropSize = 'w300' | 'w780' | 'w1280' | 'original' | (string & {});
+type LogoSize = 'w45' | 'w92' | 'w154' | 'w185' | 'w300' | 'w500' | 'original' | (string & {});
+type PosterSize = 'w92' | 'w154' | 'w185' | 'w342' | 'w500' | 'w780' | 'original' | (string & {});
+type ProfileSize = 'w45' | 'w185' | 'h632' | 'original' | (string & {});
+type StillSize = 'w92' | 'w185' | 'w300' | 'original' | (string & {});
+type ImageSize = BackdropSize | LogoSize | PosterSize | ProfileSize | StillSize;
+type MovieAppendToResponse = 'account_states' | 'alternative_titles' | 'changes' | 'credits' | 'external_ids' | 'images' | 'keywords' | 'lists' | 'recommendations' | 'release_dates' | 'reviews' | 'similar' | 'translations' | 'videos' | 'watch/providers' | (string & {});
+type TVAppendToResponse = 'account_states' | 'aggregate_credits' | 'alternative_titles' | 'changes' | 'content_ratings' | 'credits' | 'episode_groups' | 'external_ids' | 'images' | 'keywords' | 'recommendations' | 'reviews' | 'screened_theatrically' | 'similar' | 'translations' | 'videos' | 'watch/providers' | (string & {});
+interface ListOptions {
+  language?: LanguageCode;
+  page?: number;
+  region?: RegionCode;
+}
+interface LanguageOptions {
+  language?: LanguageCode;
+}
+interface MovieDetailsOptions extends LanguageOptions {
+  appendToResponse?: MovieAppendToResponse | readonly MovieAppendToResponse[];
+}
+interface TVDetailsOptions extends LanguageOptions {
+  appendToResponse?: TVAppendToResponse | readonly TVAppendToResponse[];
+}
+interface MovieSearchOptions extends ListOptions {
+  includeAdult?: boolean;
+  primaryReleaseYear?: string | number;
+  year?: string | number;
+}
+interface TVSearchOptions extends Omit<ListOptions, 'region'> {
+  firstAirDateYear?: string | number;
+  includeAdult?: boolean;
+  year?: string | number;
+}
+interface MultiSearchOptions extends Omit<ListOptions, 'region'> {
+  includeAdult?: boolean;
+}
+interface ImageQueryOptions extends LanguageOptions {
+  includeImageLanguage?: string | readonly string[];
+}
+//#endregion
+//#region src/query.d.ts
+type QueryPrimitive = string | number | boolean;
+type QueryValue = QueryPrimitive | readonly QueryPrimitive[] | null | undefined;
+type QueryParams = Record<string, QueryValue>;
+interface QueryDefaults {
+  language?: LanguageCode;
+  region?: RegionCode;
+}
+interface BuildImageUrlOptions {
+  baseUrl?: 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.
+ */
+declare function buildImageUrl(path: string | null | undefined, size?: ImageSize, options?: BuildImageUrlOptions): string | null;
+//#endregion
+//#region src/http.d.ts
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface TMDBAccessTokenAuth {
+  /** TMDB API Read Access Token. Sent as an Authorization Bearer header. */
+  accessToken: string;
+  apiKey?: never;
+}
+interface TMDBApiKeyAuth {
+  /** Legacy v3 API key. Sent as api_key query parameter. */
+  apiKey: string;
+  accessToken?: never;
+}
+type TMDBAuth = TMDBAccessTokenAuth | TMDBApiKeyAuth;
+interface TMDBClientDefaults extends QueryDefaults {
+  imageBaseUrl: string;
+}
+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; /** Additional headers merged into every request before authentication is applied. */
+  headers?: HeadersInit;
+};
+interface TMDBRequestOptions {
+  headers?: HeadersInit;
+  query?: QueryParams;
+  signal?: AbortSignal;
+}
+interface TMDBTransport {
+  readonly defaults: TMDBClientDefaults;
+  get<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/resources/configuration.d.ts
+declare class ConfigurationResource {
+  #private;
+  constructor(transport: TMDBTransport);
+  details(): Promise<Configuration>;
+  countries(): Promise<Country[]>;
+  jobs(): Promise<JobDepartment[]>;
+  languages(): Promise<Language[]>;
+  primaryTranslations(): Promise<string[]>;
+  timezones(): Promise<Timezone[]>;
+}
+//#endregion
+//#region src/resources/genres.d.ts
+declare class GenresResource {
+  #private;
+  constructor(transport: TMDBTransport);
+  movies(options?: LanguageOptions): Promise<GenresResponse>;
+  tv(options?: LanguageOptions): Promise<GenresResponse>;
+}
+//#endregion
+//#region src/resources/images.d.ts
+declare class ImagesHelper {
+  #private;
+  constructor(transport: TMDBTransport);
+  url(path: string | null | undefined, size?: ImageSize): string | null;
+}
+//#endregion
+//#region src/resources/movies.d.ts
+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?: Pick<ListOptions, 'language'>): 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?: Pick<ListOptions, 'language'>): Promise<VideosResponse>;
+}
+//#endregion
+//#region src/resources/people.d.ts
+declare class PeopleResource {
+  #private;
+  constructor(transport: TMDBTransport);
+  popular(options?: Omit<ListOptions, 'region'>): Promise<PagedResponse<PersonSummary>>;
+  details(personId: number, options?: LanguageOptions): Promise<PersonDetails>;
+}
+//#endregion
+//#region src/resources/search.d.ts
+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>>;
+}
+//#endregion
+//#region src/resources/trending.d.ts
+declare class TrendingResource {
+  #private;
+  constructor(transport: TMDBTransport);
+  all(timeWindow?: TrendingTimeWindow, options?: LanguageOptions): Promise<PagedResponse<TrendingResult>>;
+  movies(timeWindow?: TrendingTimeWindow, options?: LanguageOptions): Promise<PagedResponse<MovieSummary & {
+    media_type?: 'movie';
+  }>>;
+  tv(timeWindow?: TrendingTimeWindow, options?: LanguageOptions): Promise<PagedResponse<TVSummary & {
+    media_type?: 'tv';
+  }>>;
+  people(timeWindow?: TrendingTimeWindow, options?: LanguageOptions): Promise<PagedResponse<PersonSummary & {
+    media_type?: 'person';
+  }>>;
+}
+//#endregion
+//#region src/resources/tv.d.ts
+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>;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * 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.
+ */
+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: TMDBClientOptions);
+  request<T>(path: string, options?: TMDBRequestOptions): Promise<T>;
+}
+declare function createTMDB(options: TMDBClientOptions): TMDBClient;
+//#endregion
+//#region src/errors.d.ts
+interface TMDBResponseErrorOptions {
+  body: JsonValue | undefined;
+  headers: Headers;
+  status: number;
+  statusText: string;
+  url: string;
+}
+/** Base class for all SDK-originated errors. */
+declare class TMDBError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown before a request is sent or when fetch itself rejects. */
+declare class TMDBRequestError extends TMDBError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when TMDB returns a non-2xx response. */
+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);
+}
+//#endregion
+export { type BackdropSize, type CollectionSummary, type Configuration, type ConfigurationImages, type Country, type CreditCastMember, type CreditCrewMember, type CreditsResponse, type FetchLike, type Genre, type GenresResponse, type ImageItem, type ImageQueryOptions, type ImageSize, type ImagesResponse, type JobDepartment, type Language, type LanguageCode, type LanguageOptions, type ListOptions, type LogoSize, type MediaType, type MovieAppendToResponse, type MovieDetails, type MovieDetailsOptions, type MovieSearchOptions, type MovieSearchResult, type MovieSummary, type MultiSearchOptions, type Network, type PagedResponse, type PersonDetails, type PersonKnownFor, type PersonKnownForMovie, type PersonKnownForTV, type PersonSearchResult, type PersonSummary, type PosterSize, type ProductionCompany, type ProductionCountry, type ProfileSize, type RegionCode, type SearchMultiResult, type SeasonSummary, type SpokenLanguage, type StillSize, type TMDBAccessTokenAuth, type TMDBApiKeyAuth, type TMDBAuth, TMDBClient, type TMDBClientOptions, type TMDBDateString, TMDBError, type TMDBObject, TMDBRequestError, type TMDBRequestOptions, TMDBResponseError, type TVAppendToResponse, type TVDetails, type TVDetailsOptions, type TVSearchOptions, type TVSearchResult, type TVSummary, type Timezone, type TrendingResult, type TrendingTimeWindow, type Video, type VideosResponse, buildImageUrl, createTMDB };
+//# sourceMappingURL=index.d.ts.map