@lorenzopant/tmdb 1.18.0 → 1.19.0

package/dist/index.d.mts

@@ -477,6 +477,14 @@ type ImagesConfig = {
    * 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;
 };
 //#endregion
 //#region src/errors/tmdb.d.ts
@@ -3351,6 +3359,47 @@ type PersonImagesParams = PersonBaseParam;
 type PersonTranslationsParams = PersonBaseParam;
 type PersonTaggedImagesParams = Prettify<PersonBaseParam & WithPage>;
 //#endregion
+//#region src/types/v4/auth.d.ts
+/** Optional request body for POST /4/auth/request_token. */
+type V4AuthCreateRequestTokenBody = {
+  /** URL to redirect the user back to after they approve the request token on TMDB. */redirect_to?: string;
+};
+/**
+ * Response from POST /4/auth/request_token.
+ * Contains a short-lived request token the user must approve at the TMDB website.
+ */
+type V4AuthRequestTokenResponse = {
+  /** Always `true` on success. */success: boolean;
+  /** The generated request token. Redirect the user to:
+   * `https://www.themoviedb.org/auth/access?request_token={request_token}` to approve it. */
+  request_token: string;
+};
+/** Request body for POST /4/auth/access_token. */
+type V4AuthCreateAccessTokenBody = {
+  /** The request token that the user has approved at the TMDB website. */request_token: string;
+};
+/**
+ * Response from POST /4/auth/access_token.
+ * Contains the permanent user access token and the TMDB account ID.
+ */
+type V4AuthAccessTokenResponse = {
+  /** Always `true` on success. */success: boolean; /** The permanent user access token (Bearer token). Store this securely — treat it like a password. */
+  access_token: string; /** The TMDB account ID associated with this access token. Used by v4 account endpoints. */
+  account_id: string;
+};
+/** Request body for DELETE /4/auth/access_token. */
+type V4AuthDeleteAccessTokenBody = {
+  /** The access token to invalidate. */access_token: string;
+};
+/**
+ * Response from DELETE /4/auth/access_token.
+ */
+type V4AuthDeleteAccessTokenResponse = {
+  /** `true` if the access token was successfully deleted. */success: boolean; /** TMDB internal status code. */
+  status_code: number; /** Human-readable status message. */
+  status_message: string;
+};
+//#endregion
 //#region src/client.d.ts
 declare class ApiClient {
   private accessToken;
@@ -3367,9 +3416,12 @@ declare class ApiClient {
   private requestInterceptors;
   private onSuccessInterceptor?;
   private onErrorInterceptor?;
+  private imageApi?;
   constructor(accessToken: string, options?: {
+    /** @internal API version to target. Used by TMDBv4 — not exposed in TMDBOptions. */version?: 3 | 4;
     logger?: boolean | TMDBLoggerFn;
     deduplication?: boolean;
+    images?: ImagesConfig;
     interceptors?: {
       request?: RequestInterceptor | RequestInterceptor[];
       response?: {
@@ -4459,6 +4511,26 @@ declare class ImageAPI {
   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;
+  private isImageCollectionKey;
+  private isFullUrl;
+  private buildImageUrl;
+  private transformPathValue;
 }
 //#endregion
 //#region src/endpoints/networks.d.ts
@@ -5079,9 +5151,89 @@ declare class AuthenticationAPI extends TMDBAPIBase {
   delete_session(body: AuthDeleteSessionBody): Promise<AuthDeleteSessionResponse>;
 }
 //#endregion
+//#region src/endpoints/v4/auth.d.ts
+declare class V4AuthAPI extends TMDBAPIBase {
+  /**
+   * Create Request Token
+   * POST - https://api.themoviedb.org/4/auth/request_token
+   *
+   * Generate a request token that the user must approve at the TMDB website to begin
+   * the v4 OAuth-style flow. Redirect the user to:
+   * `https://www.themoviedb.org/auth/access?request_token={request_token}`
+   *
+   * Once approved, exchange the token for an access token using `create_access_token`.
+   * @param body Optional body with a `redirect_to` URL for post-approval redirect.
+   * @reference https://developer.themoviedb.org/reference/create-request-token
+   */
+  create_request_token(body?: V4AuthCreateRequestTokenBody): Promise<V4AuthRequestTokenResponse>;
+  /**
+   * Create Access Token
+   * POST - https://api.themoviedb.org/4/auth/access_token
+   *
+   * Exchange a user-approved request token for a permanent user access token and
+   * TMDB account ID. Store the returned `access_token` securely — it is valid
+   * indefinitely until explicitly deleted with `delete_access_token`.
+   * @param body An object containing the approved `request_token`.
+   * @reference https://developer.themoviedb.org/reference/create-access-token
+   */
+  create_access_token(body: V4AuthCreateAccessTokenBody): Promise<V4AuthAccessTokenResponse>;
+  /**
+   * Delete Access Token (Logout)
+   * DELETE - https://api.themoviedb.org/4/auth/access_token
+   *
+   * Invalidate a user access token. Use this to log a user out of your application.
+   * @param body An object containing the `access_token` to delete.
+   * @reference https://developer.themoviedb.org/reference/delete-access-token
+   */
+  delete_access_token(body: V4AuthDeleteAccessTokenBody): Promise<V4AuthDeleteAccessTokenResponse>;
+}
+//#endregion
+//#region src/endpoints/v4/account.d.ts
+declare class V4AccountAPI extends TMDBAPIBase {}
+//#endregion
+//#region src/endpoints/v4/lists.d.ts
+declare class V4ListsAPI extends TMDBAPIBase {}
+//#endregion
+//#region src/tmdb.v4.d.ts
+/**
+ * Aggregator for all TMDB API v4 namespaces.
+ *
+ * Access via `tmdb.v4` — the v4 client is backed by `https://api.themoviedb.org/4`
+ * and inherits the same access token and options as the parent TMDB instance.
+ *
+ * @example
+ * ```ts
+ * const tmdb = new TMDB(accessToken);
+ *
+ * // v4 auth flow
+ * const { request_token } = await tmdb.v4.auth.create_request_token();
+ * // ... user approves at https://www.themoviedb.org/auth/access?request_token=...
+ * const { access_token, account_id } = await tmdb.v4.auth.create_access_token({ request_token });
+ *
+ * // v4 account (account_id is a string from the access token response)
+ * const profile   = await tmdb.v4.account.details(account_id);
+ * const favorites = await tmdb.v4.account.favorite_movies({ account_id, page: 1 });
+ *
+ * // v4 lists (full CRUD)
+ * const list = await tmdb.v4.lists.create({ name: "My list", iso_639_1: "en" });
+ * await tmdb.v4.lists.add_items(list.id, { items: [{ media_type: "movie", media_id: 550 }] });
+ * ```
+ */
+declare class TMDBv4 {
+  private client;
+  /** v4 authentication — request token → access token → logout. */
+  auth: V4AuthAPI;
+  /** v4 account — details, lists, favorites, watchlist, rated. */
+  account: V4AccountAPI;
+  /** v4 lists — full CRUD for user-created lists. */
+  lists: V4ListsAPI;
+  constructor(accessToken: string, options?: TMDBOptions);
+}
+//#endregion
 //#region src/tmdb.d.ts
 declare class TMDB {
   private client;
+  private accessToken;
   private options;
   movies: MoviesAPI;
   movie_lists: MovieListsAPI;
@@ -5110,6 +5262,12 @@ declare class TMDB {
   people: PeopleAPI;
   account: AccountAPI;
   authentication: AuthenticationAPI;
+  /**
+   * TMDB API v4 namespaces. Access via `tmdb.v4.auth`, `tmdb.v4.account`, `tmdb.v4.lists`.
+   * Requires a Bearer (JWT) access token — throws if the instance was created with an API key.
+   */
+  get v4(): TMDBv4;
+  private _v4;
   /**
    * Creates a new TMDB instance.
    * @param accessToken The TMDB API access token.
@@ -5121,7 +5279,18 @@ declare class TMDB {
 //#region src/utils/jwt.d.ts
 declare function isJwt(token: string): boolean;
 //#endregion
-//#region src/utils/index.d.ts
+//#region src/utils/types.d.ts
+/**
+ * Typeguard that checks if a value is a record object.
+ * @param value - The value to check
+ * @returns `true` if the value is a non-null object that is not an array, `false` otherwise
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Typeguard that checks whether a value is a plain object.
+ * Plain objects are objects whose prototype is `Object.prototype` or `null`.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 /** Utility type guard to check if an object has a poster_path property */
 declare function hasPosterPath(data: unknown): data is {
   poster_path: string;
@@ -5143,4 +5312,4 @@ declare function hasLogoPath(data: unknown): data is {
   logo_path: string;
 };
 //#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, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, 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, 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, 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, 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, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV };
+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, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, 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, 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, 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, V4AuthAPI, V4AuthAccessTokenResponse, V4AuthCreateAccessTokenBody, V4AuthCreateRequestTokenBody, V4AuthDeleteAccessTokenBody, V4AuthDeleteAccessTokenResponse, V4AuthRequestTokenResponse, V4ListsAPI, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };

package/dist/index.mjs

@@ -39,6 +39,46 @@ var TMDBError = class extends Error {
 	}
 };
 //#endregion
+//#region src/types/config/images.ts
+const IMAGE_BASE_URL = "http://image.tmdb.org/t/p/";
+const IMAGE_SECURE_BASE_URL = "https://image.tmdb.org/t/p/";
+const BACKDROP_SIZES = [
+	"w300",
+	"w780",
+	"w1280",
+	"original"
+];
+const LOGO_SIZES = [
+	"w45",
+	"w92",
+	"w154",
+	"w185",
+	"w300",
+	"w500",
+	"original"
+];
+const POSTER_SIZES = [
+	"w92",
+	"w154",
+	"w185",
+	"w342",
+	"w500",
+	"w780",
+	"original"
+];
+const PROFILE_SIZES = [
+	"w45",
+	"w185",
+	"h632",
+	"original"
+];
+const STILL_SIZES = [
+	"w92",
+	"w185",
+	"w300",
+	"original"
+];
+//#endregion
 //#region src/utils/logger.ts
 var TMDBLogger = class TMDBLogger {
 	logger;
@@ -124,7 +164,24 @@ function isJwt(token) {
 	return true;
 }
 //#endregion
-//#region src/utils/index.ts
+//#region src/utils/types.ts
+/**
+* Typeguard that checks if a value is a record object.
+* @param value - The value to check
+* @returns `true` if the value is a non-null object that is not an array, `false` otherwise
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Typeguard that checks whether a value is a plain object.
+* Plain objects are objects whose prototype is `Object.prototype` or `null`.
+*/
+function isPlainObject(value) {
+	if (!isRecord(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
 /** Utility type guard to check if an object has a poster_path property */
 function hasPosterPath(data) {
 	return typeof data === "object" && data !== null && "poster_path" in data && typeof data.poster_path === "string";
@@ -146,10 +203,103 @@ function hasLogoPath(data) {
 	return typeof data === "object" && data !== null && "logo_path" in data && typeof data.logo_path === "string";
 }
 //#endregion
+//#region src/images/images.ts
+const IMAGE_PATH_BUILDERS = {
+	backdrop_path: "backdrop",
+	logo_path: "logo",
+	poster_path: "poster",
+	profile_path: "profile",
+	still_path: "still"
+};
+const IMAGE_COLLECTION_BUILDERS = {
+	backdrops: "backdrop_path",
+	logos: "logo_path",
+	posters: "poster_path",
+	profiles: "profile_path",
+	stills: "still_path"
+};
+var ImageAPI = class {
+	options;
+	constructor(options = {}) {
+		this.options = {
+			secure_images_url: true,
+			...options
+		};
+	}
+	buildUrl(path, size) {
+		return `${this.options.secure_images_url ? IMAGE_SECURE_BASE_URL : IMAGE_BASE_URL}${size}${path}`;
+	}
+	backdrop(path, size = this.options.default_image_sizes?.backdrops || "w780") {
+		return this.buildUrl(path, size);
+	}
+	logo(path, size = this.options.default_image_sizes?.logos || "w185") {
+		return this.buildUrl(path, size);
+	}
+	poster(path, size = this.options.default_image_sizes?.posters || "w500") {
+		return this.buildUrl(path, size);
+	}
+	profile(path, size = this.options.default_image_sizes?.profiles || "w185") {
+		return this.buildUrl(path, size);
+	}
+	still(path, size = this.options.default_image_sizes?.still || "w300") {
+		return this.buildUrl(path, size);
+	}
+	/**
+	* 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(value, collectionKey) {
+		if (Array.isArray(value)) return value.map((entry) => this.autocompleteImagePaths(entry, collectionKey));
+		if (!isPlainObject(value)) return value;
+		const transformed = Object.create(null);
+		for (const [key, entry] of Object.entries(value)) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") {
+				transformed[key] = entry;
+				continue;
+			}
+			if (typeof entry === "string") {
+				transformed[key] = this.transformPathValue(key, entry, collectionKey);
+				continue;
+			}
+			const nextCollectionKey = this.isImageCollectionKey(key) ? key : collectionKey;
+			transformed[key] = this.autocompleteImagePaths(entry, nextCollectionKey);
+		}
+		return transformed;
+	}
+	isImageCollectionKey(value) {
+		return Object.hasOwn(IMAGE_COLLECTION_BUILDERS, value);
+	}
+	isFullUrl(path) {
+		return /^https?:\/\//.test(path);
+	}
+	buildImageUrl(key, path) {
+		const method = IMAGE_PATH_BUILDERS[key];
+		if (Object.hasOwn(this, method) || typeof this[method] !== "function") {}
+		return this[method](path);
+	}
+	transformPathValue(key, value, collectionKey) {
+		if (!value.startsWith("/") || this.isFullUrl(value)) return value;
+		if (Object.hasOwn(IMAGE_PATH_BUILDERS, key)) return this.buildImageUrl(key, value);
+		if (key === "file_path" && collectionKey) return this.buildImageUrl(IMAGE_COLLECTION_BUILDERS[collectionKey], value);
+		return value;
+	}
+};
+//#endregion
 //#region src/client.ts
 var ApiClient = class {
 	accessToken;
-	baseUrl = "https://api.themoviedb.org/3";
+	baseUrl;
 	logger;
 	/**
 	* Tracks in-flight requests keyed by a deterministic string derived from the endpoint
@@ -162,14 +312,17 @@ var ApiClient = class {
 	requestInterceptors;
 	onSuccessInterceptor;
 	onErrorInterceptor;
+	imageApi;
 	constructor(accessToken, options = {}) {
 		this.accessToken = accessToken;
+		this.baseUrl = `https://api.themoviedb.org/${options.version ?? 3}`;
 		this.logger = TMDBLogger.from(options.logger);
 		this.deduplication = options.deduplication !== false;
 		const raw = options.interceptors?.request;
 		this.requestInterceptors = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
 		this.onSuccessInterceptor = options.interceptors?.response?.onSuccess;
 		this.onErrorInterceptor = options.interceptors?.response?.onError;
+		this.imageApi = options.images?.autocomplete_paths ? new ImageAPI(options.images) : void 0;
 	}
 	/**
 	* Builds a stable, order-independent cache key for a request.
@@ -330,11 +483,12 @@ var ApiClient = class {
 		});
 		const data = await res.json();
 		const sanitized = this.sanitizeNulls(data);
+		const transformed = this.imageApi ? this.imageApi.autocompleteImagePaths(sanitized) : sanitized;
 		if (this.onSuccessInterceptor) {
-			const result = await this.onSuccessInterceptor(sanitized);
-			return result !== void 0 ? result : sanitized;
+			const result = await this.onSuccessInterceptor(transformed);
+			return result !== void 0 ? result : transformed;
 		}
-		return sanitized;
+		return transformed;
 	}
 };
 //#endregion
@@ -509,6 +663,31 @@ const ENDPOINTS = {
 	REVIEWS: { DETAILS: "/review" },
 	PEOPLE_LISTS: { POPULAR: "/person/popular" }
 };
+/**
+* TMDB API v4 endpoint fragments.
+* These are combined with `https://api.themoviedb.org/4` by the v4 ApiClient.
+*/
+const ENDPOINTS_V4 = {
+	AUTH: {
+		REQUEST_TOKEN: "/auth/request_token",
+		ACCESS_TOKEN: "/auth/access_token"
+	},
+	ACCOUNT: {
+		DETAILS: "/account",
+		LISTS: "/lists",
+		FAVORITE_MOVIES: "/favorite/movies",
+		FAVORITE_TV: "/favorite/tv",
+		WATCHLIST_MOVIES: "/watchlist/movies",
+		WATCHLIST_TV: "/watchlist/tv",
+		RATED_MOVIES: "/rated/movies",
+		RATED_TV: "/rated/tv"
+	},
+	LISTS: {
+		DETAILS: "/list",
+		ITEMS: "/items",
+		ITEM_STATUS: "/item_status"
+	}
+};
 //#endregion
 //#region src/errors/messages.ts
 /**
@@ -517,7 +696,8 @@ const ENDPOINTS = {
 */
 const Errors = {
 	NO_ACCESS_TOKEN: "TMDB requires a valid access token, please provide one.",
-	INVALID_CLIENT: "TMDB received an invalid ApiClient instance. Pass a valid ApiClient or an access token string."
+	INVALID_CLIENT: "TMDB received an invalid ApiClient instance. Pass a valid ApiClient or an access token string.",
+	V4_REQUIRES_JWT: "TMDB v4 requires a Bearer (JWT) access token. API key strings are not supported for v4 endpoints."
 };
 //#endregion
 //#region src/endpoints/base.ts
@@ -1894,75 +2074,6 @@ var WatchProvidersAPI = class extends TMDBAPIBase {
 	}
 };
 //#endregion
-//#region src/types/config/images.ts
-const IMAGE_BASE_URL = "http://image.tmdb.org/t/p/";
-const IMAGE_SECURE_BASE_URL = "https://image.tmdb.org/t/p/";
-const BACKDROP_SIZES = [
-	"w300",
-	"w780",
-	"w1280",
-	"original"
-];
-const LOGO_SIZES = [
-	"w45",
-	"w92",
-	"w154",
-	"w185",
-	"w300",
-	"w500",
-	"original"
-];
-const POSTER_SIZES = [
-	"w92",
-	"w154",
-	"w185",
-	"w342",
-	"w500",
-	"w780",
-	"original"
-];
-const PROFILE_SIZES = [
-	"w45",
-	"w185",
-	"h632",
-	"original"
-];
-const STILL_SIZES = [
-	"w92",
-	"w185",
-	"w300",
-	"original"
-];
-//#endregion
-//#region src/images/images.ts
-var ImageAPI = class {
-	options;
-	constructor(options = {}) {
-		this.options = {
-			secure_images_url: true,
-			...options
-		};
-	}
-	buildUrl(path, size) {
-		return `${this.options.secure_images_url ? IMAGE_SECURE_BASE_URL : IMAGE_BASE_URL}${size}${path}`;
-	}
-	backdrop(path, size = this.options.default_image_sizes?.backdrops || "w780") {
-		return this.buildUrl(path, size);
-	}
-	logo(path, size = this.options.default_image_sizes?.logos || "w185") {
-		return this.buildUrl(path, size);
-	}
-	poster(path, size = this.options.default_image_sizes?.posters || "w500") {
-		return this.buildUrl(path, size);
-	}
-	profile(path, size = this.options.default_image_sizes?.profiles || "w185") {
-		return this.buildUrl(path, size);
-	}
-	still(path, size = this.options.default_image_sizes?.still || "w300") {
-		return this.buildUrl(path, size);
-	}
-};
-//#endregion
 //#region src/endpoints/networks.ts
 var NetworksAPI = class extends TMDBAPIBase {
 	networkPath(network_id) {
@@ -2798,9 +2909,107 @@ var AuthenticationAPI = class extends TMDBAPIBase {
 	}
 };
 //#endregion
+//#region src/endpoints/v4/auth.ts
+var V4AuthAPI = class extends TMDBAPIBase {
+	/**
+	* Create Request Token
+	* POST - https://api.themoviedb.org/4/auth/request_token
+	*
+	* Generate a request token that the user must approve at the TMDB website to begin
+	* the v4 OAuth-style flow. Redirect the user to:
+	* `https://www.themoviedb.org/auth/access?request_token={request_token}`
+	*
+	* Once approved, exchange the token for an access token using `create_access_token`.
+	* @param body Optional body with a `redirect_to` URL for post-approval redirect.
+	* @reference https://developer.themoviedb.org/reference/create-request-token
+	*/
+	async create_request_token(body) {
+		return this.client.mutate("POST", ENDPOINTS_V4.AUTH.REQUEST_TOKEN, body ?? {});
+	}
+	/**
+	* Create Access Token
+	* POST - https://api.themoviedb.org/4/auth/access_token
+	*
+	* Exchange a user-approved request token for a permanent user access token and
+	* TMDB account ID. Store the returned `access_token` securely — it is valid
+	* indefinitely until explicitly deleted with `delete_access_token`.
+	* @param body An object containing the approved `request_token`.
+	* @reference https://developer.themoviedb.org/reference/create-access-token
+	*/
+	async create_access_token(body) {
+		return this.client.mutate("POST", ENDPOINTS_V4.AUTH.ACCESS_TOKEN, body);
+	}
+	/**
+	* Delete Access Token (Logout)
+	* DELETE - https://api.themoviedb.org/4/auth/access_token
+	*
+	* Invalidate a user access token. Use this to log a user out of your application.
+	* @param body An object containing the `access_token` to delete.
+	* @reference https://developer.themoviedb.org/reference/delete-access-token
+	*/
+	async delete_access_token(body) {
+		return this.client.mutate("DELETE", ENDPOINTS_V4.AUTH.ACCESS_TOKEN, body);
+	}
+};
+//#endregion
+//#region src/endpoints/v4/account.ts
+var V4AccountAPI = class extends TMDBAPIBase {};
+//#endregion
+//#region src/endpoints/v4/lists.ts
+var V4ListsAPI = class extends TMDBAPIBase {};
+//#endregion
+//#region src/tmdb.v4.ts
+/**
+* Aggregator for all TMDB API v4 namespaces.
+*
+* Access via `tmdb.v4` — the v4 client is backed by `https://api.themoviedb.org/4`
+* and inherits the same access token and options as the parent TMDB instance.
+*
+* @example
+* ```ts
+* const tmdb = new TMDB(accessToken);
+*
+* // v4 auth flow
+* const { request_token } = await tmdb.v4.auth.create_request_token();
+* // ... user approves at https://www.themoviedb.org/auth/access?request_token=...
+* const { access_token, account_id } = await tmdb.v4.auth.create_access_token({ request_token });
+*
+* // v4 account (account_id is a string from the access token response)
+* const profile   = await tmdb.v4.account.details(account_id);
+* const favorites = await tmdb.v4.account.favorite_movies({ account_id, page: 1 });
+*
+* // v4 lists (full CRUD)
+* const list = await tmdb.v4.lists.create({ name: "My list", iso_639_1: "en" });
+* await tmdb.v4.lists.add_items(list.id, { items: [{ media_type: "movie", media_id: 550 }] });
+* ```
+*/
+var TMDBv4 = class {
+	client;
+	/** v4 authentication — request token → access token → logout. */
+	auth;
+	/** v4 account — details, lists, favorites, watchlist, rated. */
+	account;
+	/** v4 lists — full CRUD for user-created lists. */
+	lists;
+	constructor(accessToken, options = {}) {
+		if (!accessToken) throw new Error(Errors.NO_ACCESS_TOKEN);
+		this.client = new ApiClient(accessToken, {
+			version: 4,
+			logger: options.logger,
+			deduplication: options.deduplication,
+			images: options.images,
+			interceptors: options.interceptors
+		});
+		this.auth = new V4AuthAPI(this.client, options);
+		this.account = new V4AccountAPI(this.client, options);
+		this.lists = new V4ListsAPI(this.client, options);
+	}
+};
+//#endregion
 //#region src/tmdb.ts
 var TMDB = class {
 	client;
+	accessToken;
 	options;
 	movies;
 	movie_lists;
@@ -2830,16 +3039,28 @@ var TMDB = class {
 	account;
 	authentication;
 	/**
+	* TMDB API v4 namespaces. Access via `tmdb.v4.auth`, `tmdb.v4.account`, `tmdb.v4.lists`.
+	* Requires a Bearer (JWT) access token — throws if the instance was created with an API key.
+	*/
+	get v4() {
+		if (!isJwt(this.accessToken)) throw new Error(Errors.V4_REQUIRES_JWT);
+		if (!this._v4) this._v4 = new TMDBv4(this.accessToken, this.options);
+		return this._v4;
+	}
+	_v4;
+	/**
 	* Creates a new TMDB instance.
 	* @param accessToken The TMDB API access token.
 	* @param options Optional default options (e.g., language) for all requests.
 	*/
 	constructor(accessToken, options = {}) {
 		if (!accessToken) throw new Error(Errors.NO_ACCESS_TOKEN);
+		this.accessToken = accessToken;
 		this.options = options;
 		this.client = new ApiClient(accessToken, {
 			logger: options.logger,
 			deduplication: options.deduplication,
+			images: options.images,
 			interceptors: options.interceptors
 		});
 		this.movies = new MoviesAPI(this.client, this.options);
@@ -4187,4 +4408,4 @@ let TVEpisodeGroupType = /* @__PURE__ */ function(TVEpisodeGroupType) {
 	return TVEpisodeGroupType;
 }({});
 //#endregion
-export { AccountAPI, AuthenticationAPI, BACKDROP_SIZES, CertificationsAPI, ChangesAPI, CollectionsAPI, CompaniesAPI, ConfigurationAPI, CreditsAPI, DiscoverAPI, DiscoverTVStatus, DiscoverTVType, FindAPI, GenresAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, KeywordsAPI, LOGO_SIZES, MovieListsAPI, MoviesAPI, NetworksAPI, POSTER_SIZES, PROFILE_SIZES, PeopleAPI, PeopleListsAPI, ReviewsAPI, STILL_SIZES, SearchAPI, TMDB, TMDBCountries, TMDBError, TMDBLogger, TVEpisodeGroupType, TVEpisodeGroupsAPI, TVEpisodesAPI, TVSeasonsAPI, TVSeriesAPI, TVSeriesListsAPI, TrendingAPI, WatchProvidersAPI, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV };
+export { AccountAPI, AuthenticationAPI, BACKDROP_SIZES, CertificationsAPI, ChangesAPI, CollectionsAPI, CompaniesAPI, ConfigurationAPI, CreditsAPI, DiscoverAPI, DiscoverTVStatus, DiscoverTVType, FindAPI, GenresAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, KeywordsAPI, LOGO_SIZES, MovieListsAPI, MoviesAPI, NetworksAPI, POSTER_SIZES, PROFILE_SIZES, PeopleAPI, PeopleListsAPI, ReviewsAPI, STILL_SIZES, SearchAPI, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBv4, TVEpisodeGroupType, TVEpisodeGroupsAPI, TVEpisodesAPI, TVSeasonsAPI, TVSeriesAPI, TVSeriesListsAPI, TrendingAPI, V4AccountAPI, V4AuthAPI, V4ListsAPI, WatchProvidersAPI, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.18.0",
+	"version": "1.19.0",
 	"description": "A completely type-safe The Movie Database (TMDB) API wrapper for typescript applications.",
 	"keywords": [
 		"api",
@@ -51,17 +51,15 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@types/node": "^22.19.11",
-		"@vitest/coverage-v8": "^4.0.9",
-		"@vitest/ui": "^4.0.10",
+		"@types/node": "^25.5.0",
+		"@vitest/coverage-v8": "^4.1.2",
+		"@vitest/ui": "^4.1.2",
 		"dotenv": "^16.5.0",
-		"release-it": "^19.0.3",
-		"release-it-pnpm": "^4.6.6",
 		"ts-morph": "^27.0.2",
 		"tsdown": "^0.21.7",
 		"tsx": "^4.21.0",
 		"typescript": "^5.8.3",
-		"vite": "^7.0.0",
-		"vitest": "^4.0.9"
+		"vite": "^8.0.3",
+		"vitest": "^4.1.2"
 	}
 }