tmdb-kit 1.0.0 → 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,452 @@
+/** Primitive JSON values returned by TMDB. */
+export type JsonPrimitive = string | number | boolean | null;
+/** JSON object/array tree returned by TMDB for fields this SDK does not model yet. */
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+/** Escape hatch for append_to_response payloads and future TMDB fields. */
+export type TMDBObject = Record<string, unknown>;
+/** Date string in TMDB format (typically `YYYY-MM-DD`). */
+export type TMDBDateString = string;
+/** ISO 639-1 language code (e.g. `"en"`, `"zh"`). */
+export type LanguageCode = string;
+/** ISO 3166-1 country/region code (e.g. `"US"`, `"CN"`). */
+export type RegionCode = string;
+/** Supported media types for multi-search results. */
+export type MediaType = 'movie' | 'tv' | 'person';
+/** Time window for trending endpoints: `"day"` or `"week"`. */
+export type TrendingTimeWindow = 'day' | 'week';
+export interface PagedResponse<T> {
+    page: number;
+    results: T[];
+    total_pages: number;
+    total_results: number;
+}
+export interface Genre {
+    id: number;
+    name: string;
+}
+export interface ProductionCompany {
+    id: number;
+    logo_path: string | null;
+    name: string;
+    origin_country: string;
+}
+export interface ProductionCountry {
+    iso_3166_1: string;
+    name: string;
+}
+export interface SpokenLanguage {
+    english_name: string;
+    iso_639_1: string;
+    name: string;
+}
+export interface CollectionSummary {
+    id: number;
+    name: string;
+    poster_path: string | null;
+    backdrop_path: string | null;
+}
+export 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;
+}
+export interface MovieDetails extends Omit<MovieSummary, 'genre_ids'> {
+    belongs_to_collection: CollectionSummary | null;
+    budget: number;
+    genres: Genre[];
+    homepage: string | null;
+    imdb_id: string | null;
+    production_companies: ProductionCompany[];
+    production_countries: ProductionCountry[];
+    revenue: number;
+    runtime: number | null;
+    spoken_languages: SpokenLanguage[];
+    status: string;
+    tagline: string | null;
+}
+export 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;
+}
+export interface CreatedBy {
+    id: number;
+    credit_id: string;
+    name: string;
+    gender: number;
+    profile_path: string | null;
+}
+export interface Network {
+    id: number;
+    logo_path: string | null;
+    name: string;
+    origin_country: string;
+}
+export 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;
+}
+export interface EpisodeGuestStar {
+    adult: boolean;
+    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;
+}
+export interface EpisodeSummary {
+    air_date: TMDBDateString | null;
+    crew: CreditCrewMember[];
+    episode_number: number;
+    episode_type: string;
+    guest_stars: EpisodeGuestStar[];
+    id: number;
+    name: string;
+    overview: string;
+    production_code: string | null;
+    runtime: number | null;
+    season_number: number;
+    show_id: number;
+    still_path: string | null;
+    vote_average: number;
+    vote_count: number;
+}
+export interface TVSeasonDetails {
+    _id: string;
+    air_date: TMDBDateString | null;
+    episodes: EpisodeSummary[];
+    id: number;
+    name: string;
+    overview: string;
+    poster_path: string | null;
+    season_number: number;
+    vote_average: number;
+}
+export type TVSeasonAppendToResponse = 'account_states' | 'aggregate_credits' | 'credits' | 'external_ids' | 'images' | 'translations' | 'videos' | (string & {});
+export interface TVSeasonDetailsOptions extends LanguageOptions {
+    appendToResponse?: TVSeasonAppendToResponse | readonly TVSeasonAppendToResponse[];
+}
+export 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;
+}
+export interface PersonKnownForMovie extends MovieSummary {
+    media_type: 'movie';
+}
+export interface PersonKnownForTV extends TVSummary {
+    media_type: 'tv';
+}
+export type PersonKnownFor = PersonKnownForMovie | PersonKnownForTV;
+export 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;
+}
+export 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;
+}
+export interface PersonCombinedCastMovie extends MovieSummary {
+    character: string;
+    credit_id: string;
+    media_type: 'movie';
+    order?: number;
+}
+export interface PersonCombinedCastTV extends TVSummary {
+    character: string;
+    credit_id: string;
+    episode_count?: number;
+    media_type: 'tv';
+}
+export type PersonCombinedCast = PersonCombinedCastMovie | PersonCombinedCastTV;
+export interface PersonCombinedCrewMovie extends MovieSummary {
+    credit_id: string;
+    department: string;
+    job: string;
+    media_type: 'movie';
+}
+export interface PersonCombinedCrewTV extends TVSummary {
+    credit_id: string;
+    department: string;
+    job: string;
+    media_type: 'tv';
+}
+export type PersonCombinedCrew = PersonCombinedCrewMovie | PersonCombinedCrewTV;
+export interface PersonCombinedCreditsResponse {
+    cast: PersonCombinedCast[];
+    crew: PersonCombinedCrew[];
+    id: number;
+}
+export interface MovieSearchResult extends MovieSummary {
+    media_type?: 'movie';
+}
+export interface TVSearchResult extends TVSummary {
+    media_type?: 'tv';
+}
+export interface PersonSearchResult extends PersonSummary {
+    media_type?: 'person';
+}
+export type SearchMultiResult = (MovieSummary & {
+    media_type: 'movie';
+}) | (TVSummary & {
+    media_type: 'tv';
+}) | (PersonSummary & {
+    media_type: 'person';
+});
+/** A single multi-search result narrowed to a specific media type. */
+export type MovieMultiResult = MovieSummary & {
+    media_type: 'movie';
+};
+export type TVMultiResult = TVSummary & {
+    media_type: 'tv';
+};
+export type PersonMultiResult = PersonSummary & {
+    media_type: 'person';
+};
+export type TrendingResult = SearchMultiResult;
+export 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;
+}
+export 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;
+}
+export interface CreditsResponse {
+    id: number;
+    cast: CreditCastMember[];
+    crew: CreditCrewMember[];
+}
+export 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;
+}
+export interface VideosResponse {
+    id: number;
+    results: Video[];
+}
+export interface ImageItem {
+    aspect_ratio: number;
+    height: number;
+    iso_639_1: string | null;
+    file_path: string;
+    vote_average: number;
+    vote_count: number;
+    width: number;
+}
+export interface ImagesResponse {
+    id: number;
+    backdrops: ImageItem[];
+    logos?: ImageItem[];
+    posters: ImageItem[];
+}
+export interface ConfigurationImages {
+    base_url: string;
+    secure_base_url: string;
+    backdrop_sizes: string[];
+    logo_sizes: string[];
+    poster_sizes: string[];
+    profile_sizes: string[];
+    still_sizes: string[];
+}
+export interface Configuration {
+    images: ConfigurationImages;
+    change_keys: string[];
+}
+export interface Country {
+    iso_3166_1: string;
+    english_name: string;
+    native_name: string;
+}
+export interface Language {
+    iso_639_1: string;
+    english_name: string;
+    name: string;
+}
+export interface Timezone {
+    iso_3166_1: string;
+    zones: string[];
+}
+export interface JobDepartment {
+    department: string;
+    jobs: string[];
+}
+export interface GenresResponse {
+    genres: Genre[];
+}
+export type BackdropSize = 'w300' | 'w780' | 'w1280' | 'original' | (string & {});
+export type LogoSize = 'w45' | 'w92' | 'w154' | 'w185' | 'w300' | 'w500' | 'original' | (string & {});
+export type PosterSize = 'w92' | 'w154' | 'w185' | 'w342' | 'w500' | 'w780' | 'original' | (string & {});
+export type ProfileSize = 'w45' | 'w185' | 'h632' | 'original' | (string & {});
+export type StillSize = 'w92' | 'w185' | 'w300' | 'original' | (string & {});
+export type ImageSize = BackdropSize | LogoSize | PosterSize | ProfileSize | StillSize;
+/**
+ * Public set of image sizes TMDB currently documents. The SDK does not
+ * pin to a static copy of the TMDB docs — TMDB has added new sizes in
+ * the past (e.g. `h632` for profile) without notice — but exposing the
+ * canonical list lets callers:
+ *
+ * - iterate over the set to build a size picker
+ * - validate user-supplied sizes with `isKnownBackdropSize(...)` etc.
+ * - type a variable as a "known" size without giving up the
+ *   `(string & {})` escape hatch for forward-compatibility
+ *
+ * If TMDB publishes a new size, the SDK will still accept it at runtime
+ * (every helper is `(string & {})` permissive), but you will need to
+ * add the literal to these constants to get autocomplete on it.
+ */
+export declare const KNOWN_BACKDROP_SIZES: readonly ['w300', 'w780', 'w1280', 'original'];
+export declare const KNOWN_LOGO_SIZES: readonly ['w45', 'w92', 'w154', 'w185', 'w300', 'w500', 'original'];
+export declare const KNOWN_POSTER_SIZES: readonly [
+    'w92',
+    'w154',
+    'w185',
+    'w342',
+    'w500',
+    'w780',
+    'original'
+];
+export declare const KNOWN_PROFILE_SIZES: readonly ['w45', 'w185', 'h632', 'original'];
+export declare const KNOWN_STILL_SIZES: readonly ['w92', 'w185', 'w300', 'original'];
+export type KnownBackdropSize = (typeof KNOWN_BACKDROP_SIZES)[number];
+export type KnownLogoSize = (typeof KNOWN_LOGO_SIZES)[number];
+export type KnownPosterSize = (typeof KNOWN_POSTER_SIZES)[number];
+export type KnownProfileSize = (typeof KNOWN_PROFILE_SIZES)[number];
+export type KnownStillSize = (typeof KNOWN_STILL_SIZES)[number];
+export type KnownImageSize = KnownBackdropSize | KnownLogoSize | KnownPosterSize | KnownProfileSize | KnownStillSize;
+/** Union of every documented image size. */
+export declare const KNOWN_IMAGE_SIZES: readonly KnownImageSize[];
+export declare function isKnownBackdropSize(value: string): value is KnownBackdropSize;
+export declare function isKnownLogoSize(value: string): value is KnownLogoSize;
+export declare function isKnownPosterSize(value: string): value is KnownPosterSize;
+export declare function isKnownProfileSize(value: string): value is KnownProfileSize;
+export declare function isKnownStillSize(value: string): value is KnownStillSize;
+/** True if `value` is in any documented size set. */
+export declare function isKnownImageSize(value: string): value is KnownImageSize;
+export type MovieAppendToResponse = 'account_states' | 'alternative_titles' | 'changes' | 'credits' | 'external_ids' | 'images' | 'keywords' | 'lists' | 'recommendations' | 'release_dates' | 'reviews' | 'similar' | 'translations' | 'videos' | 'watch/providers' | (string & {});
+export 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 & {});
+export interface ListOptions {
+    language?: LanguageCode;
+    page?: number;
+    region?: RegionCode;
+}
+export interface LanguageOptions {
+    language?: LanguageCode;
+}
+export interface MovieDetailsOptions extends LanguageOptions {
+    appendToResponse?: MovieAppendToResponse | readonly MovieAppendToResponse[];
+}
+export interface TVDetailsOptions extends LanguageOptions {
+    appendToResponse?: TVAppendToResponse | readonly TVAppendToResponse[];
+}
+export interface MovieSearchOptions extends ListOptions {
+    includeAdult?: boolean;
+    primaryReleaseYear?: string | number;
+    year?: string | number;
+}
+export interface TVSearchOptions extends Omit<ListOptions, 'region'> {
+    firstAirDateYear?: string | number;
+    includeAdult?: boolean;
+    year?: string | number;
+}
+export interface MultiSearchOptions extends Omit<ListOptions, 'region'> {
+    includeAdult?: boolean;
+    /**
+     * Media types to exclude from a `search.multi()` response. Filtering is
+     * performed client-side because the TMDB multi-search endpoint does not
+     * support a server-side media_type filter.
+     */
+    exclude?: ReadonlyArray<MediaType>;
+}
+export interface ImageQueryOptions extends LanguageOptions {
+    includeImageLanguage?: string | readonly string[];
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "tmdb-kit",
   "type": "module",
-  "version": "1.0.0",
-  "description": "A tiny, typed, zero-runtime-dependency TMDB SDK for Node.js, Bun, Deno, and edge runtimes.",
+  "version": "1.1.0",
+  "description": "A tiny, typed, zero-runtime-dependency TMDB SDK and CLI for Node.js, Bun, Deno, and edge runtimes.",
   "author": "isaced",
   "license": "MIT",
   "homepage": "https://github.com/isaced/tmdb-kit#readme",
@@ -13,6 +13,7 @@
     "typescript",
     "node",
     "bun",
+    "cli",
     "deno",
     "edge",
     "esm",
@@ -29,7 +30,7 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "npm@11.12.1",
+  "packageManager": "bun@1.4.4",
   "exports": {
     ".": {
       "import": {
@@ -47,6 +48,10 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "tmdb": "./dist/cli.js",
+    "tmdb-kit": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md"
@@ -56,26 +61,28 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run",
-    "test:resources": "vitest run tests/resources",
-    "test:unit": "vitest run tests/unit",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:integration": "vitest run --config vitest.integration.config.ts",
-    "typecheck": "tsc --noEmit",
-    "ci": "npm run typecheck && npm run test:coverage && npm run build",
+    "build": "bun run scripts/build.ts",
+    "build:cli": "bun run scripts/build.ts --cli",
+    "cli": "bun run build:cli && bun ./dist/cli.js",
+    "dev": "bun build ./src/index.ts --outdir ./dist --entry-naming '[name].js' --format esm --target browser --sourcemap=linked --watch",
+    "test": "bun test --isolate tests/unit tests/resources tests/cli",
+    "test:resources": "bun test --isolate tests/resources",
+    "test:unit": "bun test --isolate tests/unit",
+    "test:watch": "bun test --isolate --watch tests/unit tests/resources tests/cli",
+    "test:coverage": "bun test --isolate --coverage tests/unit tests/resources tests/cli",
+    "test:integration": "bun test --isolate tests/integration",
+    "typecheck": "bun check",
+    "format": "bun fmt",
+    "format:check": "bun fmt --check",
+    "ci": "bun run format:check && bun run typecheck && bun run test:coverage && bun run build",
     "release": "bumpp",
-    "prepublishOnly": "npm run ci"
+    "prepublishOnly": "bun run ci"
   },
   "devDependencies": {
+    "@types/bun": "^1.4.4",
     "@types/node": "^25.6.2",
-    "@vitest/coverage-v8": "^4.1.5",
-    "@typescript/native-preview": "7.0.0-dev.20260509.2",
     "bumpp": "^11.1.0",
-    "tsdown": "^0.22.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "citty": "^0.2.2",
+    "typescript": "^6.0.3"
   }
 }