@tdanks2000/tmdb-wrapper 1.0.0 → 1.0.2

package/src/endpoints/movies.ts

@@ -14,6 +14,7 @@ import {
   MovieChangeValue,
   MovieDetails,
   MovieLists,
+  MoviesImageSearchOptions,
   MoviesPlayingNow,
   PageOption,
   PopularMovies,
@@ -31,18 +32,25 @@ import {
 
 const BASE_MOVIE = '/movie';
 
-export interface MoviesImageSearchOptions extends LanguageOption {
+/**
+ * Represents an endpoint for accessing movie-related information.
+ */
+export class MoviesEndpoint extends BaseEndpoint {
   /**
-   * a list of ISO-639-1 values to query
+   * Constructs a new MoviesEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
    */
-  include_image_language?: string[];
-}
-
-export class MoviesEndpoint extends BaseEndpoint {
   constructor(protected readonly access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {AppendToResponseMovieKey[]} [appendToResponse] - Optional keys to append to the response.
+   * @param {string} [language] - Optional parameter for specifying the language.
+   * @returns {Promise<AppendToResponse<MovieDetails, AppendToResponseMovieKey[], 'movie'>>} A Promise that resolves with the details of the movie.
+   */
   async details<T extends AppendToResponseMovieKey[] | undefined>(id: number, appendToResponse?: T, language?: string) {
     const options = {
       append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
@@ -52,22 +60,50 @@ export class MoviesEndpoint extends BaseEndpoint {
     return await this.api.get<AppendToResponse<MovieDetails, T, 'movie'>>(`${BASE_MOVIE}/${id}`, options);
   }
 
+  /**
+   * Retrieves alternative titles of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<AlternativeTitles>} A Promise that resolves with the alternative titles of the movie.
+   */
   async alternativeTitles(id: number): Promise<AlternativeTitles> {
     return await this.api.get<AlternativeTitles>(`${BASE_MOVIE}/${id}/alternative_titles`);
   }
 
+  /**
+   * Retrieves changes made to a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {ChangeOption} [options] - Optional parameters for filtering changes.
+   * @returns {Promise<Changes<MovieChangeValue>>} A Promise that resolves with the changes made to the movie.
+   */
   async changes(id: number, options?: ChangeOption): Promise<Changes<MovieChangeValue>> {
     return await this.api.get<Changes<MovieChangeValue>>(`${BASE_MOVIE}/${id}/changes`, options);
   }
 
+  /**
+   * Retrieves credits of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<Credits>} A Promise that resolves with the credits of the movie.
+   */
   async credits(id: number, options?: LanguageOption): Promise<Credits> {
     return await this.api.get<Credits>(`${BASE_MOVIE}/${id}/credits`, options);
   }
 
+  /**
+   * Retrieves external IDs of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<ExternalIds>} A Promise that resolves with the external IDs of the movie.
+   */
   async externalIds(id: number): Promise<ExternalIds> {
     return await this.api.get<ExternalIds>(`${BASE_MOVIE}/${id}/external_ids`);
   }
 
+  /**
+   * Retrieves images of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {MoviesImageSearchOptions} [options] - Optional parameters for specifying image search options.
+   * @returns {Promise<Images>} A Promise that resolves with the images of the movie.
+   */
   async images(id: number, options?: MoviesImageSearchOptions): Promise<Images> {
     const computedOptions = {
       include_image_language: options?.include_image_language?.join(','),
@@ -76,62 +112,132 @@ export class MoviesEndpoint extends BaseEndpoint {
     return await this.api.get<Images>(`${BASE_MOVIE}/${id}/images`, computedOptions);
   }
 
+  /**
+   * Retrieves keywords of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<Keywords>} A Promise that resolves with the keywords of the movie.
+   */
   async keywords(id: number): Promise<Keywords> {
     return await this.api.get<Keywords>(`${BASE_MOVIE}/${id}/keywords`);
   }
 
+  /**
+   * Retrieves lists containing a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<MovieLists>} A Promise that resolves with the lists containing the movie.
+   */
   async lists(id: number, options?: LanguageOption & PageOption): Promise<MovieLists> {
     return await this.api.get<MovieLists>(`${BASE_MOVIE}/${id}/lists`, options);
   }
 
+  /**
+   * Retrieves recommendations for a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<Recommendations>} A Promise that resolves with the recommendations for the movie.
+   */
   async recommendations(id: number, options?: LanguageOption & PageOption): Promise<Recommendations> {
     return await this.api.get<Recommendations>(`${BASE_MOVIE}/${id}/recommendations`, options);
   }
 
+  /**
+   * Retrieves release dates of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<ReleaseDates>} A Promise that resolves with the release dates of the movie.
+   */
   async releaseDates(id: number): Promise<ReleaseDates> {
     return await this.api.get<ReleaseDates>(`${BASE_MOVIE}/${id}/release_dates`);
   }
 
+  /**
+   * Retrieves reviews for a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<Reviews>} A Promise that resolves with the reviews for the movie.
+   */
   async reviews(id: number, options?: LanguageOption & PageOption): Promise<Reviews> {
     return await this.api.get<Reviews>(`${BASE_MOVIE}/${id}/reviews`, options);
   }
 
+  /**
+   * Retrieves similar movies for a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<SimilarMovies>} A Promise that resolves with the similar movies for the movie.
+   */
   async similar(id: number, options?: LanguageOption & PageOption): Promise<SimilarMovies> {
     return await this.api.get<SimilarMovies>(`${BASE_MOVIE}/${id}/similar`, options);
   }
 
+  /**
+   * Retrieves translations of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<Translations>} A Promise that resolves with the translations of the movie.
+   */
   async translations(id: number): Promise<Translations> {
     return await this.api.get<Translations>(`${BASE_MOVIE}/${id}/translations`);
   }
 
+  /**
+   * Retrieves videos of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<Videos>} A Promise that resolves with the videos of the movie.
+   */
   async videos(id: number, options?: LanguageOption): Promise<Videos> {
     return await this.api.get<Videos>(`${BASE_MOVIE}/${id}/videos`, options);
   }
 
   /**
-   * Powered by JustWatch
-   * @param id
+   * Retrieves watch providers of a specific movie asynchronously.
+   * @param {number} id - The ID of the movie.
+   * @returns {Promise<WatchProviders>} A Promise that resolves with the watch providers of the movie.
    */
   async watchProviders(id: number): Promise<WatchProviders> {
     return await this.api.get<WatchProviders>(`${BASE_MOVIE}/${id}/watch/providers`);
   }
 
+  /**
+   * Retrieves details of the latest movie asynchronously.
+   * @returns {Promise<LatestMovie>} A Promise that resolves with the details of the latest movie.
+   */
   async latest(): Promise<LatestMovie> {
     return await this.api.get<LatestMovie>(`${BASE_MOVIE}/latest`);
   }
 
+  /**
+   * Retrieves movies playing now asynchronously.
+   * @param {PageOption & LanguageOption & RegionOption} [options] - Optional parameters for specifying language, region, and pagination options.
+   * @returns {Promise<MoviesPlayingNow>} A Promise that resolves with the movies playing now.
+   */
   async nowPlaying(options?: PageOption & LanguageOption & RegionOption): Promise<MoviesPlayingNow> {
     return await this.api.get<MoviesPlayingNow>(`${BASE_MOVIE}/now_playing`, options);
   }
 
+  /**
+   * Retrieves popular movies asynchronously.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<PopularMovies>} A Promise that resolves with the popular movies.
+   */
   async popular(options?: LanguageOption & PageOption): Promise<PopularMovies> {
     return await this.api.get<PopularMovies>(`${BASE_MOVIE}/popular`, options);
   }
 
+  /**
+   * Retrieves top rated movies asynchronously.
+   * @param {PageOption & LanguageOption & RegionOption} [options] - Optional parameters for specifying language, region, and pagination options.
+   * @returns {Promise<TopRatedMovies>} A Promise that resolves with the top rated movies.
+   */
   async topRated(options?: PageOption & LanguageOption & RegionOption): Promise<TopRatedMovies> {
     return await this.api.get<TopRatedMovies>(`${BASE_MOVIE}/top_rated`, options);
   }
 
+  /**
+   * Retrieves upcoming movies asynchronously.
+   * @param {PageOption & LanguageOption & RegionOption} [options] - Optional parameters for specifying language, region, and pagination options.
+   * @returns {Promise<UpcomingMovies>} A Promise that resolves with the upcoming movies.
+   */
   async upcoming(options?: PageOption & LanguageOption & RegionOption): Promise<UpcomingMovies> {
     return await this.api.get<UpcomingMovies>(`${BASE_MOVIE}/upcoming`, options);
   }

package/src/endpoints/networks.ts

@@ -1,18 +1,40 @@
 import { AlternativeNames, BaseEndpoint, NetworkDetails, NetworkImages } from '@/@types';
 
+/**
+ * Represents an endpoint for accessing network details.
+ */
 export class NetworksEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new NetworksEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(protected readonly access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific network asynchronously.
+   * @param {number} id - The ID of the network.
+   * @returns {Promise<NetworkDetails>} A Promise that resolves with the details of the network.
+   */
   async details(id: number): Promise<NetworkDetails> {
     return await this.api.get<NetworkDetails>(`/network/${id}`);
   }
 
+  /**
+   * Retrieves alternative names of a specific network asynchronously.
+   * @param {number} id - The ID of the network.
+   * @returns {Promise<AlternativeNames>} A Promise that resolves with the alternative names of the network.
+   */
   async alternativeNames(id: number): Promise<AlternativeNames> {
     return await this.api.get<AlternativeNames>(`/network/${id}/alternative_names`);
   }
 
+  /**
+   * Retrieves images of a specific network asynchronously.
+   * @param {number} id - The ID of the network.
+   * @returns {Promise<NetworkImages>} A Promise that resolves with the images of the network.
+   */
   async images(id: number): Promise<NetworkImages> {
     return await this.api.get<NetworkImages>(`/network/${id}/images`);
   }

package/src/endpoints/people.ts

@@ -20,11 +20,25 @@ import {
 
 const BASE_PERSON = '/person';
 
+/**
+ * Represents an endpoint for accessing information about people.
+ */
 export class PeopleEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new PeopleEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {AppendToResponsePersonKey[]} [appendToResponse] - Optional keys to append to the response.
+   * @param {string} [language] - Optional parameter for specifying the language.
+   * @returns {Promise<AppendToResponse<PersonDetails, AppendToResponsePersonKey[], 'person'>>} A Promise that resolves with the details of the person.
+   */
   async details<T extends AppendToResponsePersonKey[] | undefined>(
     id: number,
     appendToResponse?: T,
@@ -37,42 +51,96 @@ export class PeopleEndpoint extends BaseEndpoint {
     return await this.api.get<AppendToResponse<PersonDetails, T, 'person'>>(`${BASE_PERSON}/${id}`, options);
   }
 
+  /**
+   * Retrieves changes made to a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {ChangeOption} [options] - Optional parameters for filtering changes.
+   * @returns {Promise<Changes<PersonChangeValue>>} A Promise that resolves with the changes made to the person.
+   */
   async changes(id: number, options?: ChangeOption): Promise<Changes<PersonChangeValue>> {
     return await this.api.get<Changes<PersonChangeValue>>(`${BASE_PERSON}/${id}/changes`, options);
   }
 
+  /**
+   * Retrieves movie credits of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<PersonMovieCredit>} A Promise that resolves with the movie credits of the person.
+   */
   async movieCredits(id: number, options?: LanguageOption): Promise<PersonMovieCredit> {
     return await this.api.get<PersonMovieCredit>(`${BASE_PERSON}/${id}/movie_credits`, options);
   }
 
+  /**
+   * Retrieves TV show credits of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<PersonTvShowCredit>} A Promise that resolves with the TV show credits of the person.
+   */
   async tvShowCredits(id: number, options?: LanguageOption): Promise<PersonTvShowCredit> {
     return await this.api.get<PersonTvShowCredit>(`${BASE_PERSON}/${id}/tv_credits`, options);
   }
 
+  /**
+   * Retrieves combined credits of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<PersonCombinedCredits>} A Promise that resolves with the combined credits of the person.
+   */
   async combinedCredits(id: number, options?: LanguageOption): Promise<PersonCombinedCredits> {
     return await this.api.get<PersonCombinedCredits>(`${BASE_PERSON}/${id}/combined_credits`, options);
   }
 
+  /**
+   * Retrieves external IDs of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @returns {Promise<ExternalIds>} A Promise that resolves with the external IDs of the person.
+   */
   async externalId(id: number): Promise<ExternalIds> {
     return await this.api.get<ExternalIds>(`${BASE_PERSON}/${id}/external_ids`);
   }
 
+  /**
+   * Retrieves images of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @returns {Promise<PeopleImages>} A Promise that resolves with the images of the person.
+   */
   async images(id: number): Promise<PeopleImages> {
     return await this.api.get<PeopleImages>(`${BASE_PERSON}/${id}/images`);
   }
 
+  /**
+   * Retrieves tagged images of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @param {PageOption} [options] - Optional parameters for specifying pagination options.
+   * @returns {Promise<TaggedImages>} A Promise that resolves with the tagged images of the person.
+   */
   async taggedImages(id: number, options?: PageOption): Promise<TaggedImages> {
     return await this.api.get<TaggedImages>(`${BASE_PERSON}/${id}/tagged_images`, options);
   }
 
+  /**
+   * Retrieves translations of a specific person asynchronously.
+   * @param {number} id - The ID of the person.
+   * @returns {Promise<PersonTranslations>} A Promise that resolves with the translations of the person.
+   */
   async translation(id: number): Promise<PersonTranslations> {
     return await this.api.get<PersonTranslations>(`${BASE_PERSON}/${id}/translations`);
   }
 
+  /**
+   * Retrieves details of the latest person asynchronously.
+   * @returns {Promise<PersonDetails>} A Promise that resolves with the details of the latest person.
+   */
   async latest(): Promise<PersonDetails> {
     return await this.api.get<PersonDetails>(`${BASE_PERSON}/latest`);
   }
 
+  /**
+   * Retrieves popular persons asynchronously.
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying language and pagination options.
+   * @returns {Promise<PopularPersons>} A Promise that resolves with the popular persons.
+   */
   async popular(options?: LanguageOption & PageOption): Promise<PopularPersons> {
     return await this.api.get<PopularPersons>(`${BASE_PERSON}/popular`, options);
   }

package/src/endpoints/review.ts

@@ -1,10 +1,22 @@
 import { BaseEndpoint, ReviewDetails } from '@/@types';
 
+/**
+ * Represents an endpoint for accessing review details.
+ */
 export class ReviewEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new ReviewEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific review asynchronously.
+   * @param {string} id - The ID of the review.
+   * @returns {Promise<ReviewDetails>} A Promise that resolves with the details of the review.
+   */
   async details(id: string): Promise<ReviewDetails> {
     return await this.api.get<ReviewDetails>(`/review/${id}`);
   }

package/src/endpoints/search.ts

@@ -2,76 +2,91 @@ import {
   BaseEndpoint,
   Collection,
   Company,
-  LanguageOption,
   Movie,
+  MovieSearchOptions,
+  MultiSearchOptions,
   MultiSearchResult,
-  PageOption,
+  PeopleSearchOptions,
   Person,
-  RegionOption,
   Search,
+  SearchOptions,
   TV,
+  TvSearchOptions,
 } from '@/@types';
 
 const BASE_SEARCH = '/search';
 
-export interface SearchOptions {
-  query: string;
-  page?: number;
-}
-
-export interface MovieSearchOptions extends SearchOptions, LanguageOption, PageOption, RegionOption {
-  include_adult?: boolean;
-  year?: number;
-  primary_release_year?: number;
-}
-
-export interface CollectionSearchOptions extends SearchOptions, LanguageOption, PageOption, RegionOption {
-  include_adult?: boolean;
-}
-
-export interface TvSearchOptions extends SearchOptions, LanguageOption, PageOption {
-  include_adult?: boolean;
-  year?: number;
-  first_air_date_year?: number;
-}
-
-export interface PeopleSearchOptions extends SearchOptions, LanguageOption, PageOption {
-  include_adult?: boolean;
-}
-
-export interface MultiSearchOptions extends SearchOptions, LanguageOption, PageOption {
-  include_adult?: boolean;
-}
-
+/**
+ * Represents an endpoint for performing various search operations.
+ */
 export class SearchEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new SearchEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(protected readonly access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Searches for companies asynchronously.
+   * @param {SearchOptions} options - The search options.
+   * @returns {Promise<Search<Company>>} A Promise that resolves with the search results for companies.
+   */
   async companies(options: SearchOptions): Promise<Search<Company>> {
     return await this.api.get<Search<Company>>(`${BASE_SEARCH}/company`, options);
   }
 
+  /**
+   * Searches for collections asynchronously.
+   * @param {SearchOptions} options - The search options.
+   * @returns {Promise<Search<Collection>>} A Promise that resolves with the search results for collections.
+   */
   async collections(options: SearchOptions): Promise<Search<Collection>> {
     return await this.api.get<Search<Collection>>(`${BASE_SEARCH}/collection`, options);
   }
 
+  /**
+   * Searches for keywords asynchronously.
+   * @param {SearchOptions} options - The search options.
+   * @returns {Promise<Search<{ id: string; name: string }>>} A Promise that resolves with the search results for keywords.
+   */
   async keywords(options: SearchOptions): Promise<Search<{ id: string; name: string }>> {
     return await this.api.get<Search<{ id: string; name: string }>>(`${BASE_SEARCH}/keyword`, options);
   }
 
+  /**
+   * Searches for movies asynchronously.
+   * @param {MovieSearchOptions} options - The search options.
+   * @returns {Promise<Search<Movie>>} A Promise that resolves with the search results for movies.
+   */
   async movies(options: MovieSearchOptions): Promise<Search<Movie>> {
     return await this.api.get<Search<Movie>>(`${BASE_SEARCH}/movie`, options);
   }
 
+  /**
+   * Searches for people asynchronously.
+   * @param {PeopleSearchOptions} options - The search options.
+   * @returns {Promise<Search<Person>>} A Promise that resolves with the search results for people.
+   */
   async people(options: PeopleSearchOptions): Promise<Search<Person>> {
     return await this.api.get<Search<Person>>(`${BASE_SEARCH}/person`, options);
   }
 
+  /**
+   * Searches for TV shows asynchronously.
+   * @param {TvSearchOptions} options - The search options.
+   * @returns {Promise<Search<TV>>} A Promise that resolves with the search results for TV shows.
+   */
   async tv(options: TvSearchOptions): Promise<Search<TV>> {
     return await this.api.get<Search<TV>>(`${BASE_SEARCH}/tv`, options);
   }
 
+  /**
+   * Performs a multi-search asynchronously.
+   * @param {MultiSearchOptions} options - The search options.
+   * @returns {Promise<Search<MultiSearchResult>>} A Promise that resolves with the multi-search results.
+   */
   async multi(options: MultiSearchOptions): Promise<Search<MultiSearchResult>> {
     return await this.api.get<Search<MultiSearchResult>>(`${BASE_SEARCH}/multi`, options);
   }

package/src/endpoints/trending.ts

@@ -1,14 +1,29 @@
-import { BaseEndpoint, LanguageOption, TimeWindow, TrendingMediaType, TrendingResults } from '@/@types';
+import { BaseEndpoint, LanguageOption, PageOption, TimeWindow, TrendingMediaType, TrendingResults } from '@/@types';
 
+/**
+ * Represents an endpoint for retrieving trending content.
+ */
 export class TrendingEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new TrendingEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves trending content asynchronously based on media type and time window.
+   * @param {TrendingMediaType} mediaType - The type of media (e.g., 'all', 'movie', 'tv').
+   * @param {TimeWindow} timeWindow - The time window for trending content (e.g., 'day', 'week').
+   * @param {LanguageOption & PageOption} [options] - Optional parameters for specifying the language and pagination.
+   * @returns {Promise<TrendingResults<T>>} A Promise that resolves with the trending results.
+   * @template T - The type of media being searched for (e.g., 'movie', 'tv').
+   */
   async trending<T extends TrendingMediaType>(
     mediaType: T,
     timeWindow: TimeWindow,
-    options?: LanguageOption,
+    options?: LanguageOption & PageOption,
   ): Promise<TrendingResults<T>> {
     return await this.api.get<TrendingResults<T>>(`/trending/${mediaType}/${timeWindow}`, options);
   }