@lorenzopant/tmdb 1.21.0 → 1.21.2

package/dist/index.d.mts

@@ -2237,7 +2237,7 @@ type MovieDetails = {
 /**
  * Available endpoints that can be appended to movie details requests
  */
-type MovieAppendToResponseNamespace = "alternative_titles" | "changes" | "credits" | "external_ids" | "images" | "keywords" | "recommendations" | "release_dates" | "reviews" | "similar" | "translations" | "videos";
+type MovieAppendToResponseNamespace = "alternative_titles" | "changes" | "credits" | "external_ids" | "images" | "keywords" | "recommendations" | "release_dates" | "reviews" | "similar" | "translations" | "videos" | "watch/providers";
 /**
  * Mapping of append-to-response keys to their return types
  */
@@ -2254,6 +2254,7 @@ type MovieAppendableMap = {
   similar: MovieSimilar;
   translations: MovieTranslations;
   videos: MovieVideos;
+  "watch/providers": MovieWatchProviders;
 };
 /**
  * Movie details with additional appended data
@@ -2288,7 +2289,8 @@ type MovieCredits = {
  */
 type MovieExternalIDs = {
   /** Movie identifier in TMDB */id: number; /** IMDb identifier (e.g., "tt0133093"), null if not available */
-  imdb_id?: string; /** Facebook page identifier, null if not available */
+  imdb_id?: string; /** Wikidata identifier (e.g., "Q190050"), null if not available */
+  wikidata_id?: string; /** Facebook page identifier, null if not available */
   facebook_id?: string; /** Twitter/X handle, null if not available */
   twitter_id?: string; /** Instagram handle, null if not available */
   instagram_id?: string;
@@ -2359,6 +2361,12 @@ type MovieTranslationData = {
  * Collection of videos (trailers, teasers, clips) for a movie
  */
 type MovieVideos = VideoResults;
+/**
+ * Watch provider availability for a movie across different countries
+ */
+type MovieWatchProviders = {
+  results: Record<CountryISO3166_1, WatchProvider>;
+};
 /**
  * Parameters for movie list endpoints (popular, top rated, now playing, upcoming).
  */
@@ -6171,4 +6179,4 @@ type PageInfo = {
  */
 declare function getPageInfo(response: PaginatedResponse<unknown>): PageInfo;
 //#endregion
-export { AccountAPI, AccountAddFavoriteBody, AccountAddToWatchlistBody, AccountAvatar, AccountDetails, AccountDetailsParams, AccountListItem, AccountListsParams, AccountListsResponse, AccountMediaListParams, AccountMovieItem, AccountMovieListResponse, AccountMutationParams, AccountMutationResponse, AccountRatedEpisodeItem, AccountRatedEpisodesResponse, AccountRatedMovieItem, AccountRatedMoviesResponse, AccountRatedTVItem, AccountRatedTVResponse, AccountSortBy, AccountTVItem, AccountTVListResponse, AlternativeName, AlternativeNamesResult, AlternativeTitle, AuthCreateSessionBody, AuthCreateSessionResponse, AuthCreateSessionWithLoginBody, AuthDeleteSessionBody, AuthDeleteSessionResponse, AuthGuestSessionResponse, AuthRequestTokenResponse, AuthValidateKeyResponse, AuthenticationAPI, BACKDROP_SIZES, BackdropSize, Cast, CertificationItem, Certifications, CertificationsAPI, Change, ChangeItem, ChangeResultItem, Changes, ChangesAPI, Collection, CollectionBaseParam, CollectionDetailsParams, CollectionImages, CollectionImagesParams, CollectionItem, CollectionResultItem, CollectionTranslationData, CollectionTranslations, CollectionsAPI, CompaniesAPI, Company, CompanyAlternativeName, CompanyAlternativeNames, CompanyAlternativeNamesParams, CompanyBaseParam, CompanyDetailsParams, CompanyImages, CompanyImagesParams, CompanyResultItem, CompanySummary, ConfigurationAPI, ConfigurationCountriesParams, ConfigurationCountry, ConfigurationJob, ConfigurationLanguage, ConfigurationResponse, ConfigurationTimezone, ContentRating, CountryISO3166_1, Credit, CreditBaseParam, CreditDetails, CreditDetailsMedia, CreditDetailsMovieMedia, CreditDetailsParams, CreditDetailsPerson, CreditDetailsTVEpisode, CreditDetailsTVMedia, CreditDetailsTVSeason, CreditsAPI, Crew, DateRange, DefaultImageSizesConfig, DiscoverAPI, DiscoverFilterExpression, DiscoverMovieParams, DiscoverMovieSortBy, DiscoverTVParams, DiscoverTVResultItem, DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, FetchAllPagesOptions, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, GuestSessionRatedEpisodesResponse, GuestSessionRatedMoviesResponse, GuestSessionRatedParams, GuestSessionRatedTVResponse, GuestSessionsAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageLanguagePriorityConfig, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, ListClearParams, ListCreateBody, ListCreateParams, ListCreateResponse, ListDetails, ListDetailsParams, ListItem, ListItemStatusParams, ListItemStatusResponse, ListMovieBody, ListMutationParams, ListMutationResponse, ListsAPI, LiteralUnion, LogoSize, MediaType, MediaWatchProviders, MovieAlternativeTitles, MovieAlternativeTitlesParams, MovieAppendToResponseNamespace, MovieAppendableMap, MovieChanges, MovieChangesParams, MovieCollection, MovieCredits, MovieCreditsParams, MovieDetails, MovieDetailsParams, MovieDetailsWithAppends, MovieExternalIDs, MovieExternalIDsParams, MovieImages, MovieImagesParams, MovieKeywords, MovieKeywordsParams, MovieListParams, MovieListsAPI, MovieRecommendations, MovieRecommendationsParams, MovieReleaseDate, MovieReleaseDateResult, MovieReleaseDates, MovieReleaseDatesParams, MovieResultItem, MovieReviews, MovieReviewsParams, MovieSimilar, MovieSimilarParams, MovieTranslationData, MovieTranslations, MovieTranslationsParams, MovieVideos, MovieVideosParams, MovieWatchProvidersParams, MoviesAPI, MultiSearchResultItem, Network, NetworkBaseParams, NetworkImages, NetworkItem, NetworksAPI, OrganizationImage, POSTER_SIZES, PROFILE_SIZES, PageInfo, PaginatedResponse, PeopleAPI, PeopleListParams, PeopleListsAPI, PersonAppendToResponseNamespace, PersonAppendableMap, PersonBaseParam, PersonChanges, PersonChangesParams, PersonCombinedCastCredit, PersonCombinedCredits, PersonCombinedCrewCredit, PersonCreditsParams, PersonDetails, PersonDetailsParams, PersonDetailsWithAppends, PersonExternalIDs, PersonExternalIDsParams, PersonImages, PersonImagesParams, PersonMovieCastCredit, PersonMovieCredits, PersonMovieCrewCredit, PersonResultItem, PersonTVCastCredit, PersonTVCredits, PersonTVCrewCredit, PersonTaggedImage, PersonTaggedImageMedia, PersonTaggedImages, PersonTaggedImagesParams, PersonTranslationData, PersonTranslations, PersonTranslationsParams, PosterSize, Prettify, PrimaryTranslations, ProductionCompany, ProductionCountry, ProfileSize, RequestInterceptor, RequestInterceptorContext, ResponseErrorInterceptor, ResponseSuccessInterceptor, RetryOptions, Review, ReviewAuthorDetails, ReviewDetails, ReviewDetailsParams, ReviewsAPI, STILL_SIZES, SearchAPI, SearchCollectionsParams, SearchCompanyParams, SearchKeywordsParams, SearchMoviesParams, SearchMultiParams, SearchPersonParams, SearchTVSeriesParams, SpokenLanguage, StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBLoggerEntry, TMDBLoggerFn, TMDBOptions, TMDBQueryParams, TMDBv4, TVAggregateCredits, TVAggregateCreditsCastItem, TVAggregateCreditsCrewItem, TVAggregateCreditsParams, TVAlternativeTitles, TVAppendToResponseNamespace, TVAppendableMap, TVBaseParam, TVChangeParams, TVContentRatings, TVCreditJob, TVCreditRole, TVCredits, TVCreditsParams, TVDetailsParams, TVDetailsWithAppends, TVEpisode, TVEpisodeAppendToResponseNamespace, TVEpisodeAppendableMap, TVEpisodeBaseParams, TVEpisodeCredits, TVEpisodeCreditsParams, TVEpisodeDetailsParams, TVEpisodeDetailsWithAppends, TVEpisodeExternalIDs, TVEpisodeGroupDetails, TVEpisodeGroupDetailsItem, TVEpisodeGroupEpisode, TVEpisodeGroupItem, TVEpisodeGroupParams, TVEpisodeGroupType, TVEpisodeGroups, TVEpisodeGroupsAPI, TVEpisodeId, TVEpisodeImages, TVEpisodeImagesParams, TVEpisodeItem, TVEpisodeTranslationData, TVEpisodeTranslations, TVEpisodeVideos, TVEpisodesAPI, TVExternalIDs, TVImageItem, TVImages, TVImagesParams, TVKeywords, TVRecommendations, TVRecommendationsParams, TVReviews, TVReviewsParams, TVScreenedTheatrically, TVScreeningItem, TVSeason, TVSeasonAggregateCredits, TVSeasonAggregateCreditsParams, TVSeasonAppendToResponseNamespace, TVSeasonAppendableMap, TVSeasonBaseParams, TVSeasonChanges, TVSeasonChangesParams, TVSeasonCredits, TVSeasonCreditsParams, TVSeasonDetailsParams, TVSeasonDetailsWithAppends, TVSeasonEpisode, TVSeasonExternalIDs, TVSeasonId, TVSeasonImages, TVSeasonImagesParams, TVSeasonItem, TVSeasonTranslationData, TVSeasonTranslations, TVSeasonVideos, TVSeasonVideosParams, TVSeasonWatchProvidersParams, TVSeasonsAPI, TVSeriesAPI, TVSeriesChanges, TVSeriesDetails, TVSeriesListItem, TVSeriesListParams, TVSeriesLists, TVSeriesListsAPI, TVSeriesListsParams, TVSeriesResultItem, TVSimilar, TVSimilarParams, TVTranslationData, TVTranslations, TVVideos, Timezone, Translation, TranslationResults, TrendingAPI, TrendingAllResult, TrendingMovieResult, TrendingParams, TrendingPersonResult, TrendingTVResult, TrendingTimeWindow, V4AccountAPI, V4AddListItemsBody, V4AddListItemsResponse, V4AuthAPI, V4AuthAccessTokenResponse, V4AuthCreateAccessTokenBody, V4AuthCreateRequestTokenBody, V4AuthDeleteAccessTokenBody, V4AuthDeleteAccessTokenResponse, V4AuthRequestTokenResponse, V4CreateListBody, V4CreateListResponse, V4DeleteListParams, V4ListDetails, V4ListDetailsParams, V4ListItemInput, V4ListItemResult, V4ListItemStatusParams, V4ListItemStatusResponse, V4ListMediaType, V4ListResult, V4ListStatusResponse, V4ListsAPI, V4RemoveListItemsBody, V4UpdateListBody, V4UpdateListItemsBody, V4UpdateListItemsResponse, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, fetchAllPages, getPageInfo, hasBackdropPath, hasLogoPath, hasNextPage, hasPosterPath, hasPreviousPage, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord, paginate };
+export { AccountAPI, AccountAddFavoriteBody, AccountAddToWatchlistBody, AccountAvatar, AccountDetails, AccountDetailsParams, AccountListItem, AccountListsParams, AccountListsResponse, AccountMediaListParams, AccountMovieItem, AccountMovieListResponse, AccountMutationParams, AccountMutationResponse, AccountRatedEpisodeItem, AccountRatedEpisodesResponse, AccountRatedMovieItem, AccountRatedMoviesResponse, AccountRatedTVItem, AccountRatedTVResponse, AccountSortBy, AccountTVItem, AccountTVListResponse, AlternativeName, AlternativeNamesResult, AlternativeTitle, AuthCreateSessionBody, AuthCreateSessionResponse, AuthCreateSessionWithLoginBody, AuthDeleteSessionBody, AuthDeleteSessionResponse, AuthGuestSessionResponse, AuthRequestTokenResponse, AuthValidateKeyResponse, AuthenticationAPI, BACKDROP_SIZES, BackdropSize, Cast, CertificationItem, Certifications, CertificationsAPI, Change, ChangeItem, ChangeResultItem, Changes, ChangesAPI, Collection, CollectionBaseParam, CollectionDetailsParams, CollectionImages, CollectionImagesParams, CollectionItem, CollectionResultItem, CollectionTranslationData, CollectionTranslations, CollectionsAPI, CompaniesAPI, Company, CompanyAlternativeName, CompanyAlternativeNames, CompanyAlternativeNamesParams, CompanyBaseParam, CompanyDetailsParams, CompanyImages, CompanyImagesParams, CompanyResultItem, CompanySummary, ConfigurationAPI, ConfigurationCountriesParams, ConfigurationCountry, ConfigurationJob, ConfigurationLanguage, ConfigurationResponse, ConfigurationTimezone, ContentRating, CountryISO3166_1, Credit, CreditBaseParam, CreditDetails, CreditDetailsMedia, CreditDetailsMovieMedia, CreditDetailsParams, CreditDetailsPerson, CreditDetailsTVEpisode, CreditDetailsTVMedia, CreditDetailsTVSeason, CreditsAPI, Crew, DateRange, DefaultImageSizesConfig, DiscoverAPI, DiscoverFilterExpression, DiscoverMovieParams, DiscoverMovieSortBy, DiscoverTVParams, DiscoverTVResultItem, DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, FetchAllPagesOptions, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, GuestSessionRatedEpisodesResponse, GuestSessionRatedMoviesResponse, GuestSessionRatedParams, GuestSessionRatedTVResponse, GuestSessionsAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageLanguagePriorityConfig, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, ListClearParams, ListCreateBody, ListCreateParams, ListCreateResponse, ListDetails, ListDetailsParams, ListItem, ListItemStatusParams, ListItemStatusResponse, ListMovieBody, ListMutationParams, ListMutationResponse, ListsAPI, LiteralUnion, LogoSize, MediaType, MediaWatchProviders, MovieAlternativeTitles, MovieAlternativeTitlesParams, MovieAppendToResponseNamespace, MovieAppendableMap, MovieChanges, MovieChangesParams, MovieCollection, MovieCredits, MovieCreditsParams, MovieDetails, MovieDetailsParams, MovieDetailsWithAppends, MovieExternalIDs, MovieExternalIDsParams, MovieImages, MovieImagesParams, MovieKeywords, MovieKeywordsParams, MovieListParams, MovieListsAPI, MovieRecommendations, MovieRecommendationsParams, MovieReleaseDate, MovieReleaseDateResult, MovieReleaseDates, MovieReleaseDatesParams, MovieResultItem, MovieReviews, MovieReviewsParams, MovieSimilar, MovieSimilarParams, MovieTranslationData, MovieTranslations, MovieTranslationsParams, MovieVideos, MovieVideosParams, MovieWatchProviders, MovieWatchProvidersParams, MoviesAPI, MultiSearchResultItem, Network, NetworkBaseParams, NetworkImages, NetworkItem, NetworksAPI, OrganizationImage, POSTER_SIZES, PROFILE_SIZES, PageInfo, PaginatedResponse, PeopleAPI, PeopleListParams, PeopleListsAPI, PersonAppendToResponseNamespace, PersonAppendableMap, PersonBaseParam, PersonChanges, PersonChangesParams, PersonCombinedCastCredit, PersonCombinedCredits, PersonCombinedCrewCredit, PersonCreditsParams, PersonDetails, PersonDetailsParams, PersonDetailsWithAppends, PersonExternalIDs, PersonExternalIDsParams, PersonImages, PersonImagesParams, PersonMovieCastCredit, PersonMovieCredits, PersonMovieCrewCredit, PersonResultItem, PersonTVCastCredit, PersonTVCredits, PersonTVCrewCredit, PersonTaggedImage, PersonTaggedImageMedia, PersonTaggedImages, PersonTaggedImagesParams, PersonTranslationData, PersonTranslations, PersonTranslationsParams, PosterSize, Prettify, PrimaryTranslations, ProductionCompany, ProductionCountry, ProfileSize, RequestInterceptor, RequestInterceptorContext, ResponseErrorInterceptor, ResponseSuccessInterceptor, RetryOptions, Review, ReviewAuthorDetails, ReviewDetails, ReviewDetailsParams, ReviewsAPI, STILL_SIZES, SearchAPI, SearchCollectionsParams, SearchCompanyParams, SearchKeywordsParams, SearchMoviesParams, SearchMultiParams, SearchPersonParams, SearchTVSeriesParams, SpokenLanguage, StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBLoggerEntry, TMDBLoggerFn, TMDBOptions, TMDBQueryParams, TMDBv4, TVAggregateCredits, TVAggregateCreditsCastItem, TVAggregateCreditsCrewItem, TVAggregateCreditsParams, TVAlternativeTitles, TVAppendToResponseNamespace, TVAppendableMap, TVBaseParam, TVChangeParams, TVContentRatings, TVCreditJob, TVCreditRole, TVCredits, TVCreditsParams, TVDetailsParams, TVDetailsWithAppends, TVEpisode, TVEpisodeAppendToResponseNamespace, TVEpisodeAppendableMap, TVEpisodeBaseParams, TVEpisodeCredits, TVEpisodeCreditsParams, TVEpisodeDetailsParams, TVEpisodeDetailsWithAppends, TVEpisodeExternalIDs, TVEpisodeGroupDetails, TVEpisodeGroupDetailsItem, TVEpisodeGroupEpisode, TVEpisodeGroupItem, TVEpisodeGroupParams, TVEpisodeGroupType, TVEpisodeGroups, TVEpisodeGroupsAPI, TVEpisodeId, TVEpisodeImages, TVEpisodeImagesParams, TVEpisodeItem, TVEpisodeTranslationData, TVEpisodeTranslations, TVEpisodeVideos, TVEpisodesAPI, TVExternalIDs, TVImageItem, TVImages, TVImagesParams, TVKeywords, TVRecommendations, TVRecommendationsParams, TVReviews, TVReviewsParams, TVScreenedTheatrically, TVScreeningItem, TVSeason, TVSeasonAggregateCredits, TVSeasonAggregateCreditsParams, TVSeasonAppendToResponseNamespace, TVSeasonAppendableMap, TVSeasonBaseParams, TVSeasonChanges, TVSeasonChangesParams, TVSeasonCredits, TVSeasonCreditsParams, TVSeasonDetailsParams, TVSeasonDetailsWithAppends, TVSeasonEpisode, TVSeasonExternalIDs, TVSeasonId, TVSeasonImages, TVSeasonImagesParams, TVSeasonItem, TVSeasonTranslationData, TVSeasonTranslations, TVSeasonVideos, TVSeasonVideosParams, TVSeasonWatchProvidersParams, TVSeasonsAPI, TVSeriesAPI, TVSeriesChanges, TVSeriesDetails, TVSeriesListItem, TVSeriesListParams, TVSeriesLists, TVSeriesListsAPI, TVSeriesListsParams, TVSeriesResultItem, TVSimilar, TVSimilarParams, TVTranslationData, TVTranslations, TVVideos, Timezone, Translation, TranslationResults, TrendingAPI, TrendingAllResult, TrendingMovieResult, TrendingParams, TrendingPersonResult, TrendingTVResult, TrendingTimeWindow, V4AccountAPI, V4AddListItemsBody, V4AddListItemsResponse, V4AuthAPI, V4AuthAccessTokenResponse, V4AuthCreateAccessTokenBody, V4AuthCreateRequestTokenBody, V4AuthDeleteAccessTokenBody, V4AuthDeleteAccessTokenResponse, V4AuthRequestTokenResponse, V4CreateListBody, V4CreateListResponse, V4DeleteListParams, V4ListDetails, V4ListDetailsParams, V4ListItemInput, V4ListItemResult, V4ListItemStatusParams, V4ListItemStatusResponse, V4ListMediaType, V4ListResult, V4ListStatusResponse, V4ListsAPI, V4RemoveListItemsBody, V4UpdateListBody, V4UpdateListItemsBody, V4UpdateListItemsResponse, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, fetchAllPages, getPageInfo, hasBackdropPath, hasLogoPath, hasNextPage, hasPosterPath, hasPreviousPage, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord, paginate };

package/llms-full.txt

@@ -0,0 +1,316 @@
+# @lorenzopant/tmdb
+
+`@lorenzopant/tmdb` is a fully typed TypeScript SDK for The Movie Database (TMDB) API. It wraps TMDB v3 endpoints in a single `TMDB` client and exposes TMDB v4 auth/account/list APIs through `tmdb.v4` when the client is created with a JWT bearer token.
+
+## Install
+
+```bash
+npm install @lorenzopant/tmdb
+```
+
+## Primary entrypoints
+
+```ts
+import { TMDB, TMDBError } from "@lorenzopant/tmdb";
+```
+
+Main public exports include:
+- `TMDB`
+- `TMDBv4`
+- `TMDBError`
+- Standalone endpoint classes such as `MoviesAPI`, `SearchAPI`, `GenresAPI`, `PeopleAPI`, `ListsAPI`, `AuthenticationAPI`, `V4AuthAPI`, `V4AccountAPI`, and `V4ListsAPI`
+- Package types via the root entrypoint and `@lorenzopant/tmdb/types`
+- Utility exports from `@lorenzopant/tmdb`, including pagination helpers and retry types
+
+## Quick start
+
+```ts
+import { TMDB } from "@lorenzopant/tmdb";
+
+const tmdb = new TMDB(process.env.TMDB_ACCESS_TOKEN!, {
+	language: "en-US",
+	region: "US",
+});
+
+const movie = await tmdb.movies.details({ movie_id: 550 });
+console.log(movie.title);
+```
+
+## Constructor
+
+```ts
+const tmdb = new TMDB(accessToken, options?);
+```
+
+`accessToken` is required. Supported options include:
+- `language`: default ISO 639-1 language for requests
+- `region`: default ISO 3166-1 region
+- `timezone`: default timezone for supported TV queries
+- `images`: image URL behavior and image-language prioritization
+- `logger`: `true` for built-in logging or a custom logger function
+- `deduplication`: defaults to `true`
+- `interceptors`: request and response hooks
+- `rate_limit`: `true` or `{ max_requests, per_ms }`
+- `retry`: `true` or a `RetryOptions` object
+- `cache`: `true` or a cache options object
+
+Important defaults and constraints:
+- `deduplication` is on by default
+- `cache`, `retry`, and `rate_limit` are off by default
+- `tmdb.v4` requires a JWT bearer token and throws if the client was created with a non-JWT token
+- `tmdb.cache` is only available when caching is enabled
+
+## Namespaces
+
+The `TMDB` instance exposes modular namespaces that map closely to TMDB APIs:
+- `movies`
+- `movie_lists`
+- `tv_series`
+- `tv_lists`
+- `tv_seasons`
+- `tv_episodes`
+- `tv_episode_groups`
+- `search`
+- `discover`
+- `trending`
+- `people`
+- `people_lists`
+- `collections`
+- `companies`
+- `networks`
+- `genres`
+- `keywords`
+- `reviews`
+- `credits`
+- `configuration`
+- `changes`
+- `find`
+- `watch_providers`
+- `authentication`
+- `account`
+- `guest_sessions`
+- `lists`
+- `images`
+- `v4`
+
+The `tmdb.v4` namespace exposes:
+- `tmdb.v4.auth`
+- `tmdb.v4.account`
+- `tmdb.v4.lists`
+
+## Common usage patterns
+
+### Fetch a movie
+
+```ts
+const movie = await tmdb.movies.details({ movie_id: 550 });
+console.log(movie.title);
+```
+
+### Search
+
+```ts
+const results = await tmdb.search.movies({
+	query: "Inception",
+	page: 1,
+	language: "en-US",
+});
+```
+
+### Discover
+
+```ts
+const response = await tmdb.discover.movies({
+	with_genres: "28",
+	sort_by: "vote_average.desc",
+	"vote_count.gte": 1000,
+});
+```
+
+### TV series and seasons
+
+```ts
+const show = await tmdb.tv_series.details({ series_id: 1396 });
+const season = await tmdb.tv_seasons.details({
+	series_id: 1396,
+	season_number: 1,
+});
+```
+
+### Append related resources
+
+```ts
+const movie = await tmdb.movies.details({
+	movie_id: 550,
+	append_to_response: ["credits", "videos"],
+});
+
+console.log(movie.credits.cast[0]?.name);
+console.log(movie.videos.results[0]?.key);
+```
+
+### Build image URLs
+
+```ts
+const movie = await tmdb.movies.details({ movie_id: 550 });
+
+const posterUrl = tmdb.images.poster(movie.poster_path!, "w500");
+const backdropUrl = tmdb.images.backdrop(movie.backdrop_path!, "w1280");
+```
+
+### Auto-enrich image paths in API responses
+
+```ts
+const tmdb = new TMDB(token, {
+	images: {
+		autocomplete_paths: true,
+		default_image_sizes: { posters: "original" },
+	},
+});
+```
+
+### Paginate through any paginated endpoint
+
+```ts
+import { paginate, fetchAllPages, getPageInfo } from "@lorenzopant/tmdb";
+
+for await (const page of paginate((p) => tmdb.search.movies({ query: "batman", page: p }))) {
+	console.log(getPageInfo(page));
+}
+
+const movies = await fetchAllPages((p) => tmdb.movie_lists.now_playing({ page: p }), {
+	maxPages: 3,
+	deduplicateBy: (movie) => movie.id,
+});
+```
+
+### Retry transient failures
+
+```ts
+const tmdb = new TMDB(token, { retry: true });
+```
+
+Custom retry:
+
+```ts
+import { TMDB, TMDBError } from "@lorenzopant/tmdb";
+
+const tmdb = new TMDB(token, {
+	retry: {
+		max_retries: 5,
+		base_delay_ms: 200,
+		shouldRetry: (error, attempt) => {
+			if (error instanceof TMDBError) return error.http_status_code >= 500 || error.http_status_code === 429;
+			return attempt <= 2;
+		},
+	},
+});
+```
+
+### Enable in-memory caching
+
+```ts
+const tmdb = new TMDB(token, {
+	cache: {
+		ttl: 60_000,
+		max_size: 500,
+	},
+});
+
+tmdb.cache?.invalidate("/movie/now_playing");
+tmdb.cache?.clear();
+console.log(tmdb.cache?.size);
+```
+
+### Enable rate limiting
+
+```ts
+const tmdb = new TMDB(token, {
+	rate_limit: { max_requests: 20, per_ms: 1_000 },
+});
+```
+
+### Add interceptors
+
+```ts
+const tmdb = new TMDB(token, {
+	interceptors: {
+		request: (ctx) => ({
+			...ctx,
+			params: { ...ctx.params, include_adult: false },
+		}),
+		response: {
+			onError: (error) => {
+				console.error(error.message);
+			},
+		},
+	},
+});
+```
+
+### Handle errors
+
+```ts
+import { TMDB, TMDBError } from "@lorenzopant/tmdb";
+
+try {
+	await tmdb.movies.details({ movie_id: 0 });
+} catch (error) {
+	if (error instanceof TMDBError) {
+		console.error(error.message);
+		console.error(error.http_status_code);
+		console.error(error.tmdb_status_code);
+	}
+}
+```
+
+## v4 usage
+
+Use `tmdb.v4` only when the `TMDB` instance was created with a JWT bearer token.
+
+```ts
+const { request_token } = await tmdb.v4.auth.create_request_token({
+	redirect_to: "https://yourapp.com/callback",
+});
+
+const { access_token, account_id } = await tmdb.v4.auth.create_access_token({
+	request_token,
+});
+
+const profile = await tmdb.v4.account.details(account_id);
+
+const list = await tmdb.v4.lists.create({
+	name: "My list",
+	iso_639_1: "en",
+});
+```
+
+## Package behavior summary
+
+- Strong typing is a primary goal; endpoint params and responses are exported as TypeScript types
+- The client groups endpoints by domain instead of exposing a generic low-level fetch wrapper
+- Standalone endpoint classes are also exported if you do not want the full `TMDB` aggregator
+- Image URL helpers are available even when you do not call an API endpoint
+- Pagination helpers are exported separately and can wrap any paginated method
+- Cache only applies to `GET` requests
+- Response interceptors cannot suppress thrown `TMDBError` values
+
+## Best practices for AI agents and code generators
+
+- Prefer `new TMDB(token, options)` unless there is a strong reason to instantiate standalone endpoint classes
+- Use `tmdb.v4` only when you know the token is a JWT bearer token
+- When showing examples, prefer real namespace names from the package such as `movie_lists`, `tv_series`, `tv_lists`, and `watch_providers`
+- For bulk reads, consider `rate_limit`, `retry`, `cache`, and pagination helpers together
+- For image URLs, use `tmdb.images.poster(...)`, `backdrop(...)`, `profile(...)`, `logo(...)`, or `still(...)`
+- For localized data, set `language`, `region`, and `timezone` at the client level when appropriate
+
+## Documentation links
+
+- Docs home: https://lorenzopant-tmdb-docs.vercel.app/docs
+- Getting started: https://lorenzopant-tmdb-docs.vercel.app/docs/getting-started
+- Authentication guide: https://lorenzopant-tmdb-docs.vercel.app/docs/getting-started/authentication
+- Pagination guide: https://lorenzopant-tmdb-docs.vercel.app/docs/getting-started/pagination
+- Options reference: https://lorenzopant-tmdb-docs.vercel.app/docs/getting-started/options
+- API reference index: https://lorenzopant-tmdb-docs.vercel.app/docs/api-reference
+- Types index: https://lorenzopant-tmdb-docs.vercel.app/docs/types
+- Changelog: https://lorenzopant-tmdb-docs.vercel.app/docs/changelog

package/llms.txt

@@ -0,0 +1,63 @@
+# @lorenzopant/tmdb
+
+`@lorenzopant/tmdb` is a TypeScript-first SDK for The Movie Database (TMDB) API.
+
+Use this package when you need:
+- Fully typed TMDB API access from TypeScript
+- A single `TMDB` client with modular namespaces like `movies`, `tv_series`, `search`, and `discover`
+- Built-in helpers for images, pagination, caching, retry, rate limiting, and interceptors
+- Access to TMDB v4 auth/account/list APIs through `tmdb.v4` when using a JWT bearer token
+
+Install:
+```bash
+npm install @lorenzopant/tmdb
+```
+
+Basic usage:
+```ts
+import { TMDB } from "@lorenzopant/tmdb";
+
+const tmdb = new TMDB(process.env.TMDB_ACCESS_TOKEN!, {
+	language: "en-US",
+	region: "US",
+});
+
+const movie = await tmdb.movies.details({ movie_id: 550 });
+console.log(movie.title);
+```
+
+Main exports:
+- `TMDB`
+- `TMDBv4`
+- `TMDBError`
+- Standalone endpoint classes like `MoviesAPI`, `SearchAPI`, `PeopleAPI`, `ListsAPI`, and `V4ListsAPI`
+- Utility exports including pagination helpers and `RetryOptions`
+- All public request/response types via `@lorenzopant/tmdb` and `@lorenzopant/tmdb/types`
+
+Core namespaces on `TMDB`:
+- `movies`, `movie_lists`
+- `tv_series`, `tv_lists`, `tv_seasons`, `tv_episodes`, `tv_episode_groups`
+- `search`, `discover`, `trending`
+- `people`, `people_lists`
+- `collections`, `companies`, `networks`
+- `genres`, `keywords`, `reviews`, `credits`
+- `configuration`, `changes`, `find`, `watch_providers`
+- `authentication`, `account`, `guest_sessions`, `lists`
+- `images`
+- `v4`
+
+Important behavior:
+- Constructor signature: `new TMDB(accessToken, options?)`
+- `tmdb.v4` requires a JWT bearer token; it throws if the client was created with an API key
+- `cache`, `rate_limit`, and `retry` are opt-in
+- `deduplication` is enabled by default
+- `tmdb.cache` is available only when caching is enabled
+
+Useful docs:
+- Docs home: https://lorenzopant-tmdb-docs.vercel.app/docs
+- Getting started: https://lorenzopant-tmdb-docs.vercel.app/docs/getting-started
+- API reference: https://lorenzopant-tmdb-docs.vercel.app/docs/api-reference
+- Types: https://lorenzopant-tmdb-docs.vercel.app/docs/types
+- Changelog: https://lorenzopant-tmdb-docs.vercel.app/docs/changelog
+
+For fuller package guidance, examples, and AI-oriented reference, see `llms-full.txt`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.21.0",
+	"version": "1.21.2",
 	"description": "A completely type-safe The Movie Database (TMDB) API wrapper for typescript applications.",
 	"keywords": [
 		"api",
@@ -8,7 +8,7 @@
 		"tmdb",
 		"typescript"
 	],
-	"homepage": "https://lorenzopant-tmdb-docs.vercel.app",
+	"homepage": "https://tmdb.lorenzopant.dev",
 	"bugs": {
 		"url": "https://github.com/lorenzopant/tmdb/issues"
 	},
@@ -20,7 +20,9 @@
 	},
 	"files": [
 		"dist",
-		"README.md"
+		"README.md",
+		"llms.txt",
+		"llms-full.txt"
 	],
 	"type": "module",
 	"main": "dist/index.mjs",