@lorenzopant/tmdb 1.24.0 → 1.25.0

package/README.md

@@ -244,6 +244,23 @@ const tmdb = new TMDB(token, {
 });
 ```
 
+#### Standalone image URL builder
+
+Only need the image URL builder and not the rest of the SDK? Import `ImageAPI` from the
+`@lorenzopant/tmdb/image` subpath. It ships as its own ~3.4 kB bundle with no TMDB client and no
+endpoint code, so you don't pull in the full SDK:
+
+```typescript
+import { ImageAPI } from "@lorenzopant/tmdb/image";
+
+const images = new ImageAPI({ secure_images_url: true });
+
+const posterUrl = images.poster("/abc123.jpg", "w500");
+const backdropUrl = images.backdrop("/def456.jpg", "w1280");
+```
+
+`ImageAPI` needs no API token — it only builds URLs from paths.
+
 ### Error handling
 
 ```typescript

package/dist/image.d.mts

@@ -0,0 +1,2 @@
+import { _ as ProfileSize, a as FallbackUrlConfig, d as ImagesConfig, g as PosterSize, l as ImageSize, p as LogoSize, r as BackdropSize, t as ImageAPI, x as ImageCollectionKey, y as StillSize } from "./images.mjs";
+export { type BackdropSize, type FallbackUrlConfig, ImageAPI, type ImageCollectionKey, type ImageSize, type ImagesConfig, type LogoSize, type PosterSize, type ProfileSize, type StillSize };

package/dist/image.mjs

@@ -0,0 +1 @@
+import{t as e}from"./images.mjs";export{e as ImageAPI};

package/dist/images.d.mts

@@ -0,0 +1,573 @@
+//#region src/types/config/languages.d.ts
+type LanguageISO6391 = "ay" | "ch" | "fj" | "it" | "nv" | "qu" | "ru" | "sc" | "sw" | "tn" | "ur" | "ho" | "km" | "kj" | "tt" | "ps" | "cn" | "mk" | "yo" | "fo" | "ff" | "ig" | "io" | "id" | "ko" | "mo" | "nr" | "pi" | "so" | "sq" | "ta" | "tl" | "th" | "ve" | "vo" | "cu" | "kw" | "fr" | "fy" | "ht" | "ie" | "ia" | "mh" | "rn" | "se" | "gd" | "ii" | "lo" | "la" | "ny" | "oj" | "ab" | "ar" | "ee" | "hi" | "an" | "ba" | "bn" | "bi" | "et" | "eu" | "gl" | "ha" | "hz" | "iu" | "jv" | "kr" | "mn" | "my" | "na" | "pt" | "sd" | "zu" | "ak" | "hu" | "ik" | "ks" | "ka" | "lg" | "oc" | "uz" | "xh" | "za" | "zh" | "el" | "ga" | "gn" | "gu" | "kl" | "kn" | "ky" | "nl" | "sl" | "sr" | "ss" | "ug" | "bg" | "co" | "cy" | "dv" | "ki" | "mt" | "ne" | "si" | "sn" | "su" | "to" | "wa" | "cr" | "fi" | "hr" | "mg" | "nb" | "ts" | "vi" | "hy" | "av" | "az" | "gv" | "sh" | "lv" | "mr" | "pl" | "rm" | "tr" | "xx" | "ca" | "de" | "rw" | "ln" | "ro" | "ty" | "ti" | "he" | "as" | "bo" | "dz" | "eo" | "ja" | "ng" | "no" | "pa" | "sa" | "am" | "fa" | "aa" | "ae" | "br" | "is" | "kk" | "lt" | "mi" | "ms" | "or" | "st" | "tk" | "af" | "bm" | "bs" | "cs" | "ce" | "kv" | "lb" | "nd" | "sk" | "sm" | "tg" | "wo" | "yi" | "be" | "cv" | "da" | "en" | "kg" | "ku" | "li" | "lu" | "ml" | "nn" | "om" | "os" | "sg" | "es" | "sv" | "te" | "tw" | "uk";
+/**
+ * Defined as const for utility purposes.
+ * Last update: 20 Nov 2025
+ */
+type PrimaryTranslations = "af-ZA" | "ar-AE" | "ar-SA" | "be-BY" | "bg-BG" | "bn-BD" | "ca-ES" | "ch-GU" | "cn-CN" | "cs-CZ" | "cy-GB" | "da-DK" | "de-AT" | "de-CH" | "de-DE" | "el-GR" | "en-AU" | "en-CA" | "en-GB" | "en-IE" | "en-NZ" | "en-US" | "eo-EO" | "es-ES" | "es-MX" | "et-EE" | "eu-ES" | "fa-IR" | "fi-FI" | "fr-CA" | "fr-FR" | "ga-IE" | "gd-GB" | "gl-ES" | "he-IL" | "hi-IN" | "hr-HR" | "hu-HU" | "id-ID" | "it-IT" | "ja-JP" | "ka-GE" | "kk-KZ" | "kn-IN" | "ko-KR" | "ky-KG" | "lt-LT" | "lv-LV" | "ml-IN" | "mr-IN" | "ms-MY" | "ms-SG" | "nb-NO" | "nl-BE" | "nl-NL" | "no-NO" | "pa-IN" | "pl-PL" | "pt-BR" | "pt-PT" | "ro-RO" | "ru-RU" | "si-LK" | "sk-SK" | "sl-SI" | "sq-AL" | "sr-RS" | "sv-SE" | "ta-IN" | "te-IN" | "th-TH" | "tl-PH" | "tr-TR" | "uk-UA" | "vi-VN" | "zh-CN" | "zh-HK" | "zh-SG" | "zh-TW" | "zu-ZA";
+/**
+ * As per TMDB documentation:
+ * https://developer.themoviedb.org/reference/configuration-primary-translations
+ */
+type Language = PrimaryTranslations | LanguageISO6391;
+//#endregion
+//#region src/types/config/configuration.d.ts
+type ImageConfiguration = {
+  /** Base URL for constructing image URLs (HTTP) */base_url: string; /** Secure base URL for constructing image URLs (HTTPS) */
+  secure_base_url: string; /** Available size options for backdrop images */
+  backdrop_sizes: string[]; /** Available size options for logo images */
+  logo_sizes: string[]; /** Available size options for poster images */
+  poster_sizes: string[]; /** Available size options for profile images */
+  profile_sizes: string[]; /** Available size options for still images (from TV shows/episodes) */
+  still_sizes: string[];
+};
+type ConfigurationResponse = {
+  /** Image configuration settings including base URLs and available sizes */images: ImageConfiguration; /** List of keys that can be used to track configuration changes */
+  change_keys: string[];
+};
+type ConfigurationCountry = {
+  /** ISO 3166-1 alpha-2 country code */iso_3166_1: CountryISO3166_1; /** English name of the country */
+  english_name: string; /** Native name of the country in its local language */
+  native_name: string;
+};
+type ConfigurationCountriesParams = {
+  /** ISO 639-1 language code for localized country names */language?: Language;
+};
+type ConfigurationJob = {
+  /** Name of the department (e.g., "Production", "Sound", "Camera") */department: string; /** List of job titles within this department */
+  jobs: string[];
+};
+type ConfigurationLanguage = {
+  /** ISO 639-1 two-letter language code */iso_639_1: string; /** English name of the language */
+  english_name: string; /** Native name of the language */
+  name: string;
+};
+type ConfigurationTimezone = {
+  /** ISO 3166-1 two-letter country code */iso_3166_1: string; /** List of timezone identifiers for this country (e.g., "America/New_York") */
+  zones: string[];
+};
+//#endregion
+//#region src/types/config/countries.d.ts
+declare const TMDBCountries: ConfigurationCountry[];
+type CountryISO3166_1 = "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AN" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BM" | "BN" | "BO" | "BR" | "BS" | "BT" | "BU" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CS" | "CU" | "CV" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SU" | "SV" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TP" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "XC" | "XG" | "XI" | "XK" | "YE" | "YT" | "YU" | "ZA" | "ZM" | "ZR" | "ZW";
+//#endregion
+//#region src/types/common/media.d.ts
+/**
+ * Represents a genre of a movie or TV show.
+ */
+type Genre = {
+  id: number;
+  name: string;
+};
+/**
+ * Response containing available genres
+ */
+type GenresResponse = {
+  /** Array of genre objects with ID and name */genres: Genre[];
+};
+/**
+ * Represents a production company involved in creating a movie or TV show.
+ */
+type ProductionCompany = {
+  id: number;
+  logo_path?: string;
+  name: string;
+  origin_country: string;
+};
+/**
+ * Represents a country where a movie or TV show was produced.
+ */
+type ProductionCountry = {
+  iso_3166_1: string;
+  name: string;
+};
+/**
+ * Represents a spoken language in a movie or TV show.
+ */
+type SpokenLanguage = {
+  english_name: string;
+  iso_639_1: string;
+  name: string;
+};
+/**
+ * Represents a collection of movies.
+ */
+type MovieCollection = {
+  id: number;
+  name: string;
+  poster_path?: string;
+  backdrop_path?: string;
+};
+/**
+ * Represents common class for cast and crew types
+ */
+type Credit = {
+  adult: boolean;
+  gender?: number;
+  id: number;
+  known_for_department: string;
+  name: string;
+  original_name: string;
+  popularity: number;
+  profile_path?: string;
+  credit_id: string;
+};
+/**
+ * Represents a cast member in a movie or TV show.
+ */
+type Cast = Credit & {
+  cast_id?: number;
+  character: string;
+  order: number;
+};
+/**
+ * Represents a crew member in a movie or TV show.
+ */
+type Crew = Credit & {
+  department: string;
+  job: string;
+};
+/**
+ * Represents a keyword entry
+ */
+type Keyword = {
+  id: number;
+  name: string;
+};
+/**
+ * Represents an alternative name entry for a company or network.
+ *
+ * @see https://developer.themoviedb.org/reference/company-alternative-names
+ * @see https://developer.themoviedb.org/reference/network-alternative-names
+ */
+type AlternativeName = {
+  /** The alternative name. */name: string; /** The type or context of the alternative name (e.g. "short name", "abbreviation"). */
+  type: string;
+};
+/**
+ * Represents the response from the TMDB alternative names endpoint
+ * for a company or network.
+ *
+ * @see https://developer.themoviedb.org/reference/company-alternative-names
+ * @see https://developer.themoviedb.org/reference/network-alternative-names
+ */
+type AlternativeNamesResult = {
+  /** The unique TMDB identifier of the company or network. */id: number; /** A list of alternative names associated with the company or network. */
+  results: AlternativeName[];
+};
+/**
+ *  Alternative title entry
+ */
+type AlternativeTitle = {
+  /** Alternative title text */title: string; /** ISO 3166-1 country code where this title is used */
+  iso_3166_1: string; /** Type of title (e.g., "original title", "working title") */
+  type: string;
+};
+type VideoResults = {
+  /** Media identifier. Absent when this resource is fetched via `append_to_response` rather than standalone. */id?: number | string; /** Array of video items */
+  results: VideoItem[];
+};
+/**
+ * Video metadata and details
+ */
+type VideoItem = {
+  /** ISO 639-1 language code of the video */iso_639_1: string; /** ISO 3166-1 country code where the video is available */
+  iso_3166_1: string; /** Video title or name */
+  name: string; /** Unique video key/ID on the hosting platform */
+  key: string; /** Video hosting platform (e.g., "YouTube", "Vimeo") */
+  site: string; /** Video resolution/size (e.g., 1080, 720) */
+  size: number; /** Type of video (e.g., "Trailer", "Teaser", "Clip", "Featurette", "Behind the Scenes") */
+  type: string; /** Whether this is an official video from the content distributor */
+  official: boolean; /** Publication date and time (ISO 8601 format) */
+  published_at: string; /** Unique video identifier in TMDB */
+  id: string;
+};
+/**
+ * Watch provider monetization filters supported by TMDB media discovery endpoints.
+ */
+type WatchMonetizationType = "flatrate" | "free" | "ads" | "rent" | "buy";
+/**
+ * Base properties shared between movie and TV show results
+ */
+type BaseKnownForItem = {
+  adult: boolean;
+  backdrop_path?: string;
+  id: number;
+  original_language: string;
+  overview: string;
+  poster_path?: string;
+  genre_ids: number[];
+  popularity: number; /** Whether the item is flagged as softcore content */
+  softcore: boolean;
+  vote_average: number;
+  vote_count: number;
+};
+/**
+ * Movie item in known_for array
+ */
+type KnownForMovie = BaseKnownForItem & {
+  /** Media type discriminator */media_type: "movie"; /** Movie title (localized) */
+  title: string; /** Original title in the original language */
+  original_title: string; /** Release date in ISO 8601 format (YYYY-MM-DD) */
+  release_date: string; /** Whether a video is available on TMDB */
+  video: boolean;
+};
+/**
+ * TV show item in known_for array
+ */
+type KnownForTV = BaseKnownForItem & {
+  /** Media type discriminator */media_type: "tv"; /** Series name (localized) */
+  name: string; /** Original series name */
+  original_name: string; /** First air date (YYYY-MM-DD) */
+  first_air_date: string; /** Origin country codes (ISO 3166-1 array) */
+  origin_country: CountryISO3166_1[];
+};
+/**
+ * Union type for items in the known_for array (can be either movie or TV show)
+ */
+type KnownForItem = KnownForMovie | KnownForTV;
+/** Available media types on TMDB */
+type MediaType = "movie" | "tv";
+/**
+ * Content rating information for a TV show or movie
+ */
+type ContentRating = {
+  /** Additional content descriptors or advisory warnings (e.g., "violence", "language", "nudity") */descriptors: string[]; /** ISO 3166-1 country code where this rating applies */
+  iso_3166_1: string; /** Age or content rating (e.g., "TV-MA", "PG-13", "TV-14", "R") */
+  rating: string;
+};
+/**
+ * Individual movie review with author information
+ */
+type Review = {
+  /** Review author's display name */author: string; /** Detailed information about the review author */
+  author_details: ReviewAuthorDetails; /** Full review text content */
+  content: string; /** Timestamp when the review was created (ISO 8601) */
+  created_at: string; /** Unique review identifier */
+  id: string; /** Timestamp of last update (ISO 8601) */
+  updated_at: string; /** URL to the review on TMDB website */
+  url: string;
+};
+/**
+ * Author information for a movie review
+ */
+type ReviewAuthorDetails = {
+  /** Author's full name */name: string; /** Author's username on TMDB */
+  username: string; /** Path to author's avatar image (optional) */
+  avatar_path?: string; /** Rating given by the author (0-10 scale, optional) */
+  rating?: number;
+};
+/** Collection of translations for a media item (object with `id` and `translations`). */
+type TranslationResults<T> = {
+  /** Absent when this resource is fetched via `append_to_response` rather than standalone. */id?: number | string;
+  translations: Translation<T>[];
+};
+/**
+ * Translation data for a specific language
+ */
+type Translation<T = unknown> = {
+  /** ISO 3166-1 alpha-2 country code */iso_3166_1: string; /** ISO 639-1 language code */
+  iso_639_1: string; /** Native name of the language */
+  name: string; /** English name of the language */
+  english_name: string; /** Translated media (tv/movie) information */
+  data: T;
+};
+/**
+ * Watch provider availability by country
+ */
+type MediaWatchProviders = {
+  /** Movie/TV show identifier. Absent when fetched via `append_to_response` rather than standalone. */id?: number; /** Watch providers grouped by country code */
+  results: Record<CountryISO3166_1, WatchProvider>;
+};
+/**
+ * Watch provider options for a specific country
+ */
+type WatchProvider = {
+  /** URL to watch/purchase the movie */link: string; /** Ad-supported (free with ads) providers */
+  ads?: WatchProviderItem[]; /** Streaming providers (subscription required) */
+  flatrate?: WatchProviderItem[]; /** Free (no ads, no subscription) providers */
+  free?: WatchProviderItem[]; /** Rental providers */
+  rent?: WatchProviderItem[]; /** Purchase providers */
+  buy?: WatchProviderItem[];
+};
+/**
+ * Individual watch provider details
+ */
+type WatchProviderItem = {
+  /** Path to provider logo image */logo_path: string; /** Unique provider identifier */
+  provider_id: number; /** Provider name (e.g., "Netflix", "Amazon Prime Video") */
+  provider_name: string; /** Display priority order (lower numbers = higher priority) */
+  display_priority: number;
+};
+//#endregion
+//#region src/types/utility.d.ts
+/**
+ * Forces TypeScript to resolve and display the final shape of a type.
+ * Useful for seeing the actual properties when hovering in the IDE.
+ */
+type Prettify<T> = T extends object ? (T extends infer O ? { [K in keyof O]: Prettify<O[K]> } : never) : T;
+/** Keep literal suggestions but allow any string */
+type LiteralUnion<T extends string> = T | (string & {});
+/** Keep literal suggestions but allow any number */
+type LiteralUnionNumber<T extends number> = T | (number & {});
+/**
+ * Type guard checks for KnowForItems (tv or movie)
+ * @returns
+ */
+declare function isKnownForMovie(item: KnownForItem): item is KnownForMovie;
+declare function isKnownForTV(item: KnownForItem): item is KnownForTV;
+//#endregion
+//#region src/types/common/images.d.ts
+/**
+ * Defines the possible image collection keys returned by TMDB image endpoints.
+ */
+type ImageCollectionKey = "backdrops" | "logos" | "posters" | "profiles" | "stills";
+/**
+ * Image metadata and details
+ */
+type ImageItem = {
+  /** Aspect ratio of the image (width/height) */aspect_ratio: number; /** Image height in pixels */
+  height: number; /** ISO 639-1 language code if image contains text, null otherwise */
+  iso_639_1?: string; /** ISO 3166-1 country code the image is tagged for, if any */
+  iso_3166_1?: string; /** Relative path to the image file (append to base URL) */
+  file_path: string; /** Average user rating for this image */
+  vote_average: number; /** Total number of votes for this image */
+  vote_count: number; /** Image width in pixels */
+  width: number;
+};
+/**
+ * Represents a single company or network logo (slightly different from ImageItem)
+ *
+ * Note on FileType from TMDB:
+ * There are two image formats that are supported for companies, PNG's and SVG's.
+ * You can see which type the original file is by looking at the file_type field.
+ * We prefer SVG's as they are resolution independent and as such, the width and height are only
+ * there to reflect the original asset that was uploaded.
+ * An SVG can be scaled properly beyond those dimensions if you call them as a PNG.
+ */
+type OrganizationImage = Omit<ImageItem, "iso_639_1"> & {
+  id: string;
+  file_type: FileType;
+};
+/**
+ * Represents the response from a TMDB image endpoint.
+ * Use the generic parameter to specify which image collections are present.
+ *
+ * @template K - The image collection keys available for the given entity type.
+ *
+ * @example
+ * // Company or Network (logos only)
+ * type OrganizationImagesResult = ImagesResult<"logos">;
+ *
+ * @example
+ * // Movie or TV Show (backdrops, logos and posters)
+ * type MovieImagesResult = ImagesResult<"backdrops" | "logos" | "posters">;
+ *
+ * @example
+ * // Person (profiles only)
+ * type PersonImagesResult = ImagesResult<"profiles">;
+ */
+type ImagesResult<T, K extends ImageCollectionKey> = {
+  /** The unique TMDB identifier of the entity. Absent when fetched via `append_to_response` rather than standalone. */id?: number;
+} & { [P in K]: T[] };
+/** Available file type on svg (for images) */
+type FileType = LiteralUnion<".png" | ".svg">;
+//#endregion
+//#region src/types/config/images.d.ts
+declare const IMAGE_BASE_URL = "http://image.tmdb.org/t/p/";
+declare const IMAGE_SECURE_BASE_URL = "https://image.tmdb.org/t/p/";
+declare const BACKDROP_SIZES: readonly ["w300", "w780", "w1280", "original"];
+type BackdropSize = (typeof BACKDROP_SIZES)[number];
+declare const LOGO_SIZES: readonly ["w45", "w92", "w154", "w185", "w300", "w500", "original"];
+type LogoSize = (typeof LOGO_SIZES)[number];
+declare const POSTER_SIZES: readonly ["w92", "w154", "w185", "w342", "w500", "w780", "original"];
+type PosterSize = (typeof POSTER_SIZES)[number];
+declare const PROFILE_SIZES: readonly ["w45", "w185", "h632", "original"];
+type ProfileSize = (typeof PROFILE_SIZES)[number];
+declare const STILL_SIZES: readonly ["w92", "w185", "w300", "original"];
+type StillSize = (typeof STILL_SIZES)[number];
+type ImageSize = BackdropSize | LogoSize | PosterSize | ProfileSize | StillSize;
+/**
+ * Image size type definitions
+ */
+type ImageSizeTypes = {
+  /** Size options for backdrop images: "w300", "w780", "w1280", "original" */BackdropSize: BackdropSize; /** Size options for logo images: "w45", "w92", "w154", "w185", "w300", "w500", "original" */
+  LogoSize: LogoSize; /** Size options for poster images: "w92", "w154", "w185", "w342", "w500", "w780", "original" */
+  PosterSize: PosterSize; /** Size options for profile images: "w45", "w185", "h632", "original" */
+  ProfileSize: ProfileSize; /** Size options for still images: "w92", "w185", "w300", "original" */
+  StillSize: StillSize; /** Union of all available image sizes */
+  ImageSize: ImageSize;
+};
+type DefaultImageSizesConfig = {
+  posters?: PosterSize;
+  backdrops?: BackdropSize;
+  logos?: LogoSize;
+  profiles?: ProfileSize;
+  still?: StillSize;
+};
+/**
+ * Per-collection language priority order used by `autocomplete_paths`.
+ *
+ * When set, image items in the matching collection array are reordered so that
+ * images whose `iso_639_1` matches earlier priority entries appear first.
+ * No items are ever dropped — only their order is affected.
+ *
+ * Special values:
+ * - `"null"` — matches untagged images (where `iso_639_1` is `null` or absent)
+ * - `"*"` — catch-all: consumes all remaining items at that position
+ *
+ * Items not matched by any entry are appended at the end.
+ *
+ * @example
+ * // Prefer textless posters → English → any fallback
+ * { posters: ["null", "en", "*"] }
+ */
+type ImageLanguagePriorityConfig = Partial<Record<"backdrops" | "logos" | "posters" | "profiles" | "stills", string[]>>;
+/**
+ * Fallback URL(s) used when an image path field is absent (`null` / `undefined`) in a TMDB
+ * API response and `autocompleteImagePaths` is applied.
+ *
+ * - **string** — one URL used for every image type
+ * - **object** — per-type URLs; any unspecified type keeps the original `null` / `undefined`
+ *
+ * @example
+ * // Single fallback for everything
+ * fallback_url: "/placeholder.png"
+ *
+ * @example
+ * // Different placeholders per type
+ * fallback_url: {
+ *   posters: "/poster-placeholder.png",
+ *   backdrops: "/backdrop-placeholder.png",
+ * }
+ */
+type FallbackUrlConfig = string | Partial<Record<ImageCollectionKey, string>>;
+type ImagesConfig = {
+  /**
+   * Whether to use the secure (HTTPS) image base URL.
+   * Defaults to true. Set to false only if working in an environment where HTTPS is not supported
+   * or where you explicitly need non-secure image URLs.
+   */
+  secure_images_url?: boolean;
+  /**
+   * Provide default image size configuration for each type of images.
+   */
+  default_image_sizes?: Partial<DefaultImageSizesConfig>;
+  /**
+   * Automatically expand TMDB image paths found in API responses into full URLs
+   * using the configured default image sizes.
+   *
+   * This is disabled by default to preserve the existing response shape semantics,
+   * where fields like `poster_path` contain the original relative TMDB path.
+   */
+  autocomplete_paths?: boolean;
+  /**
+   * Controls the order of image items inside collection arrays (e.g. `posters`, `backdrops`)
+   * when `autocomplete_paths` is enabled.
+   *
+   * Use `"null"` to match untagged images, ISO-639-1 codes (e.g. `"en"`) to match
+   * language-specific images, and `"*"` as a catch-all fallback.
+   *
+   * Items not matched by any entry are appended at the end. No items are dropped.
+   *
+   * @example
+   * image_language_priority: {
+   *   posters: ["null", "en", "*"],
+   * }
+   */
+  image_language_priority?: ImageLanguagePriorityConfig;
+  /**
+   * When `true`, automatically derives `include_image_language` from the language
+   * codes declared in `image_language_priority` and injects it into every `.images()`
+   * request — so TMDB returns the language variants that the priority config expects
+   * to sort.
+   *
+   * The injected value is the union of all language codes across all configured
+   * collections, with `"*"` excluded (it has no meaning as an HTTP parameter).
+   * An explicit `include_image_language` on the call site always takes precedence.
+   *
+   * Requires `image_language_priority` to be set; has no effect without it.
+   *
+   * @default false
+   *
+   * @example
+   * // Config: automatically fetch Italian + textless posters on every images() call
+   * images: {
+   *   autocomplete_paths: true,
+   *   image_language_priority: { posters: ["it", "null", "*"] },
+   *   auto_include_image_language: true,
+   * }
+   * // Equivalent to always passing: include_image_language: ["it", "null"]
+   */
+  auto_include_image_language?: boolean;
+  /**
+   * Fallback URL returned for image path fields that are absent (`null` / `undefined`) in the
+   * API response.
+   *
+   * Works independently of `autocomplete_paths`. When set, the response traversal is activated
+   * even if `autocomplete_paths` is `false`, but only null/undefined image paths are replaced —
+   * existing relative paths are left as-is unless `autocomplete_paths` is also `true`.
+   *
+   * @example
+   * fallback_url: "/placeholder.png"
+   *
+   * @example
+   * fallback_url: { posters: "/poster-ph.png", backdrops: "/backdrop-ph.png" }
+   */
+  fallback_url?: FallbackUrlConfig;
+};
+//#endregion
+//#region src/images/images.d.ts
+declare class ImageAPI {
+  private options;
+  constructor(options?: ImagesConfig);
+  private buildUrl;
+  backdrop(path: string, size?: BackdropSize): string;
+  logo(path: string, size?: LogoSize): string;
+  poster(path: string, size?: PosterSize): string;
+  profile(path: string, size?: ProfileSize): string;
+  still(path: string, size?: StillSize): string;
+  /**
+   * Recursively processes an object or array to autocomplete image paths by transforming string values
+   * and tracking the current image collection context.
+   *
+   * @template T - The type of the value being processed
+   * @param value - The value to process (can be an object, array, string, or primitive)
+   * @param collectionKey - Optional image collection key to maintain context during recursion
+   * @returns The processed value with autocompleted image paths, maintaining the original type
+   *
+   * @remarks
+   * - Arrays are recursively mapped over each entry
+   * - String values are transformed using {@link transformPathValue}
+   * - Object keys that match image collection keys update the collection context
+   * - Non-plain objects (e.g. Date/class instances) are returned unchanged
+   */
+  autocompleteImagePaths<T>(value: T, collectionKey?: ImageCollectionKey): T;
+  /**
+   * Traverses a response object substituting `null` / `undefined` image path fields with the
+   * configured `fallback_url` without expanding existing relative paths to full URLs.
+   *
+   * Used internally by the client when `fallback_url` is set but `autocomplete_paths` is `false`.
+   */
+  applyFallbacksOnly<T>(value: T): T;
+  private traverse;
+  /**
+   * Reorders an image-item array according to a language priority list.
+   *
+   * Iterates through each priority entry in order:
+   * - `"null"` matches items where `iso_639_1` is `null` or `undefined` (untagged)
+   * - `"*"` consumes all remaining items as a catch-all and stops processing
+   * - Any other string is matched against `iso_639_1` directly
+   *
+   * Items not matched by any entry are appended at the end.
+   * No items are dropped — only their order changes.
+   */
+  private sortByLanguagePriority;
+  private isImageCollectionKey;
+  private getFallbackForCollection;
+  private isFullUrl;
+  private buildImageUrl;
+  private transformPathValue;
+}
+//#endregion
+export { VideoItem as $, AlternativeName as A, KnownForItem as B, ImagesResult as C, Prettify as D, LiteralUnionNumber as E, Credit as F, MovieCollection as G, KnownForTV as H, Crew as I, Review as J, ProductionCompany as K, Genre as L, AlternativeTitle as M, Cast as N, isKnownForMovie as O, ContentRating as P, TranslationResults as Q, GenresResponse as R, ImageItem as S, LiteralUnion as T, MediaType as U, KnownForMovie as V, MediaWatchProviders as W, SpokenLanguage as X, ReviewAuthorDetails as Y, Translation as Z, ProfileSize as _, FallbackUrlConfig as a, TMDBCountries as at, FileType as b, ImageLanguagePriorityConfig as c, ConfigurationJob as ct, ImagesConfig as d, ConfigurationTimezone as dt, VideoResults as et, LOGO_SIZES as f, ImageConfiguration as ft, PosterSize as g, PROFILE_SIZES as h, PrimaryTranslations as ht, DefaultImageSizesConfig as i, CountryISO3166_1 as it, AlternativeNamesResult as j, isKnownForTV as k, ImageSize as l, ConfigurationLanguage as lt, POSTER_SIZES as m, LanguageISO6391 as mt, BACKDROP_SIZES as n, WatchProvider as nt, IMAGE_BASE_URL as o, ConfigurationCountriesParams as ot, LogoSize as p, Language as pt, ProductionCountry as q, BackdropSize as r, WatchProviderItem as rt, IMAGE_SECURE_BASE_URL as s, ConfigurationCountry as st, ImageAPI as t, WatchMonetizationType as tt, ImageSizeTypes as u, ConfigurationResponse as ut, STILL_SIZES as v, OrganizationImage as w, ImageCollectionKey as x, StillSize as y, Keyword as z };

package/dist/images.mjs

@@ -0,0 +1 @@
+const e=`http://image.tmdb.org/t/p/`,t=`https://image.tmdb.org/t/p/`,n=[`w300`,`w780`,`w1280`,`original`],r=[`w45`,`w92`,`w154`,`w185`,`w300`,`w500`,`original`],i=[`w92`,`w154`,`w185`,`w342`,`w500`,`w780`,`original`],a=[`w45`,`w185`,`h632`,`original`],o=[`w92`,`w185`,`w300`,`original`];function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e){if(!s(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function l(e){return typeof e==`object`&&!!e&&`poster_path`in e&&typeof e.poster_path==`string`}function u(e){return typeof e==`object`&&!!e&&`backdrop_path`in e&&typeof e.backdrop_path==`string`}function d(e){return typeof e==`object`&&!!e&&`profile_path`in e&&typeof e.profile_path==`string`}function f(e){return typeof e==`object`&&!!e&&`still_path`in e&&typeof e.still_path==`string`}function p(e){return typeof e==`object`&&!!e&&`logo_path`in e&&typeof e.logo_path==`string`}const m={backdrop_path:`backdrop`,logo_path:`logo`,poster_path:`poster`,profile_path:`profile`,still_path:`still`},h={backdrop_path:`backdrops`,logo_path:`logos`,poster_path:`posters`,profile_path:`profiles`,still_path:`stills`},g={backdrops:`backdrop_path`,logos:`logo_path`,posters:`poster_path`,profiles:`profile_path`,stills:`still_path`};var _=class{options;constructor(e={}){this.options={secure_images_url:!0,...e}}buildUrl(n,r){return`${this.options.secure_images_url?t:e}${r}${n}`}backdrop(e,t=this.options.default_image_sizes?.backdrops||`w780`){return this.buildUrl(e,t)}logo(e,t=this.options.default_image_sizes?.logos||`w185`){return this.buildUrl(e,t)}poster(e,t=this.options.default_image_sizes?.posters||`w500`){return this.buildUrl(e,t)}profile(e,t=this.options.default_image_sizes?.profiles||`w185`){return this.buildUrl(e,t)}still(e,t=this.options.default_image_sizes?.still||`w300`){return this.buildUrl(e,t)}autocompleteImagePaths(e,t){return this.traverse(e,t,!0)}applyFallbacksOnly(e){return this.traverse(e,void 0,!1)}traverse(e,t,n){if(Array.isArray(e)){let r=n&&t&&this.options.image_language_priority?.[t];return(r?this.sortByLanguagePriority(e,r):e).map(e=>this.traverse(e,t,n))}if(!c(e))return e;let r=Object.create(null);for(let[i,a]of Object.entries(e)){if(i===`__proto__`||i===`constructor`||i===`prototype`){r[i]=a;continue}if(a==null){if(Object.hasOwn(m,i)){let e=h[i];r[i]=this.getFallbackForCollection(e)??a;continue}if(i===`file_path`&&t){r[i]=this.getFallbackForCollection(t)??a;continue}r[i]=a;continue}if(typeof a==`string`){r[i]=n?this.transformPathValue(i,a,t):a;continue}let e=this.isImageCollectionKey(i)?i:t;r[i]=this.traverse(a,e,n)}return r}sortByLanguagePriority(e,t){let n=[],r=[...e];for(let e of t){if(e===`*`){n.push(...r.splice(0,r.length));break}let t=[];for(let i of r){let r=i?.iso_639_1;(e===`null`?r==null:r===e)?n.push(i):t.push(i)}r.length=0,r.push(...t)}return n.push(...r),n}isImageCollectionKey(e){return Object.hasOwn(g,e)}getFallbackForCollection(e){let t=this.options.fallback_url;if(t!=null)return typeof t==`string`?t:t[e]}isFullUrl(e){return/^https?:\/\//.test(e)}buildImageUrl(e,t){let n=m[e];return Object.hasOwn(this,n)||this[n],this[n](t)}transformPathValue(e,t,n){return!t.startsWith(`/`)||this.isFullUrl(t)?t:Object.hasOwn(m,e)?this.buildImageUrl(e,t):e===`file_path`&&n?this.buildImageUrl(g[n],t):t}};export{d as a,s as c,t as d,r as f,o as h,l as i,n as l,a as m,u as n,f as o,i as p,p as r,c as s,_ as t,e as u};