@tdanks2000/tmdb-wrapper 1.0.0 → 1.0.2

package/src/endpoints/tvEpisodes.ts

@@ -11,7 +11,9 @@ import {
   LanguageOption,
   TvEpisodeChangeValue,
   TvEpisodeCredit,
+  TvEpisodeImageSearchOptions,
   TvEpisodeTranslations,
+  TvEpisodeVideoSearchOptions,
   Videos,
 } from '@/@types';
 
@@ -19,25 +21,26 @@ const BASE_EPISODE = (episodeSelection: EpisodeSelection): string => {
   return `/tv/${episodeSelection.tvShowID}/season/${episodeSelection.seasonNumber}/episode/${episodeSelection.episodeNumber}`;
 };
 
-export interface TvEpisodeImageSearchOptions extends LanguageOption {
-  /**
-   * a list of ISO-639-1 values to query
-   */
-  include_image_language?: string[];
-}
-
-export interface TvEpisodeVideoSearchOptions extends LanguageOption {
+/**
+ * Represents an endpoint for accessing TV episode-related information.
+ */
+export class TvEpisodesEndpoint extends BaseEndpoint {
   /**
-   * a list of ISO-639-1 values to query
+   * Constructs a new TvEpisodesEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
    */
-  include_video_language?: string[];
-}
-
-export class TvEpisodesEndpoint extends BaseEndpoint {
   constructor(access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @param {AppendToResponseTvEpisodeKey[]} [appendToResponse] - Additional data to append to the response.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<AppendToResponse<Omit<Episode, 'show_id'>, AppendToResponseTvEpisodeKey[], 'tvEpisode'>>}
+   * A Promise that resolves with the details of the TV episode.
+   */
   async details<T extends AppendToResponseTvEpisodeKey[] | undefined>(
     episodeSelection: EpisodeSelection,
     appendToResponse?: T,
@@ -54,18 +57,41 @@ export class TvEpisodesEndpoint extends BaseEndpoint {
     );
   }
 
+  /**
+   * Retrieves changes related to a specific TV episode asynchronously.
+   * @param {number} episodeID - The ID of the TV episode.
+   * @param {ChangeOption} [options] - Optional parameters for specifying changes.
+   * @returns {Promise<Changes<TvEpisodeChangeValue>>} A Promise that resolves with the changes related to the TV episode.
+   */
   async changes(episodeID: number, options?: ChangeOption) {
     return await this.api.get<Changes<TvEpisodeChangeValue>>(`/tv/episode/${episodeID}/changes`, options);
   }
 
+  /**
+   * Retrieves credits for a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<TvEpisodeCredit>} A Promise that resolves with the credits for the TV episode.
+   */
   async credits(episodeSelection: EpisodeSelection, options?: LanguageOption) {
     return await this.api.get<TvEpisodeCredit>(`${BASE_EPISODE(episodeSelection)}/credits`, options);
   }
 
+  /**
+   * Retrieves external IDs for a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @returns {Promise<ExternalIds>} A Promise that resolves with the external IDs for the TV episode.
+   */
   async externalIds(episodeSelection: EpisodeSelection) {
     return await this.api.get<ExternalIds>(`${BASE_EPISODE(episodeSelection)}/external_ids`);
   }
 
+  /**
+   * Retrieves images for a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @param {TvEpisodeImageSearchOptions} [options] - Optional parameters for specifying image search options.
+   * @returns {Promise<Images>} A Promise that resolves with the images for the TV episode.
+   */
   async images(episodeSelection: EpisodeSelection, options?: TvEpisodeImageSearchOptions) {
     const computedOptions = {
       include_image_language: options?.include_image_language?.join(','),
@@ -74,10 +100,21 @@ export class TvEpisodesEndpoint extends BaseEndpoint {
     return await this.api.get<Images>(`${BASE_EPISODE(episodeSelection)}/images`, computedOptions);
   }
 
+  /**
+   * Retrieves translations for a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @returns {Promise<TvEpisodeTranslations>} A Promise that resolves with the translations for the TV episode.
+   */
   async translations(episodeSelection: EpisodeSelection) {
     return await this.api.get<TvEpisodeTranslations>(`${BASE_EPISODE(episodeSelection)}/translations`);
   }
 
+  /**
+   * Retrieves videos for a specific TV episode asynchronously.
+   * @param {EpisodeSelection} episodeSelection - The selection criteria for the TV episode.
+   * @param {TvEpisodeVideoSearchOptions} [options] - Optional parameters for specifying video search options.
+   * @returns {Promise<Videos>} A Promise that resolves with the videos for the TV episode.
+   */
   async videos(episodeSelection: EpisodeSelection, options?: TvEpisodeVideoSearchOptions) {
     const computedOptions = {
       include_video_language: options?.include_video_language?.join(','),

package/src/endpoints/tvSeasons.ts

@@ -13,6 +13,8 @@ import {
   SeasonSelection,
   Translations,
   TvSeasonChangeValue,
+  TvSeasonImageSearchOptions,
+  TvSeasonVideoSearchOptions,
   Videos,
 } from '@/@types';
 
@@ -20,25 +22,26 @@ const BASE_SEASON = (seasonSelection: SeasonSelection): string => {
   return `/tv/${seasonSelection.tvShowID}/season/${seasonSelection.seasonNumber}`;
 };
 
-export interface TvSeasonImageSearchOptions extends LanguageOption {
-  /**
-   * a list of ISO-639-1 values to query
-   */
-  include_image_language?: string[];
-}
-
-export interface TvSeasonVideoSearchOptions extends LanguageOption {
+/**
+ * Represents an endpoint for accessing TV season-related information.
+ */
+export class TvSeasonsEndpoint extends BaseEndpoint {
   /**
-   * a list of ISO-639-1 values to query
+   * Constructs a new TvSeasonsEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
    */
-  include_video_language?: string[];
-}
-
-export class TvSeasonsEndpoint extends BaseEndpoint {
   constructor(access_token: string) {
     super(access_token);
   }
 
+  /**
+   * Retrieves details of a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {AppendToResponseTvSeasonKey[]} [appendToResponse] - Additional data to append to the response.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<AppendToResponse<SeasonDetails, AppendToResponseTvSeasonKey[], 'tvSeason'>>}
+   * A Promise that resolves with the details of the TV season.
+   */
   async details<T extends AppendToResponseTvSeasonKey[] | undefined>(
     seasonSelection: SeasonSelection,
     appendToResponse?: T,
@@ -55,22 +58,52 @@ export class TvSeasonsEndpoint extends BaseEndpoint {
     );
   }
 
+  /**
+   * Retrieves aggregate credits for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<AggregateCredits>} A Promise that resolves with the aggregate credits for the TV season.
+   */
   async aggregateCredits(seasonSelection: SeasonSelection, options?: LanguageOption) {
     return await this.api.get<AggregateCredits>(`${BASE_SEASON(seasonSelection)}/aggregate_credits`, options);
   }
 
+  /**
+   * Retrieves changes related to a specific TV season asynchronously.
+   * @param {number} seasonId - The ID of the TV season.
+   * @param {ChangeOption} [options] - Optional parameters for specifying changes.
+   * @returns {Promise<Changes<TvSeasonChangeValue>>} A Promise that resolves with the changes related to the TV season.
+   */
   async changes(seasonId: number, options?: ChangeOption) {
     return await this.api.get<Changes<TvSeasonChangeValue>>(`/tv/season/${seasonId}/changes`, options);
   }
 
+  /**
+   * Retrieves credits for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<Credits>} A Promise that resolves with the credits for the TV season.
+   */
   async credits(seasonSelection: SeasonSelection, options?: LanguageOption) {
     return await this.api.get<Credits>(`${BASE_SEASON(seasonSelection)}/credits`, options);
   }
 
+  /**
+   * Retrieves external IDs for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<ExternalIds>} A Promise that resolves with the external IDs for the TV season.
+   */
   async externalIds(seasonSelection: SeasonSelection, options?: LanguageOption) {
     return await this.api.get<ExternalIds>(`${BASE_SEASON(seasonSelection)}/external_ids`, options);
   }
 
+  /**
+   * Retrieves images for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {TvSeasonImageSearchOptions} [options] - Optional parameters for specifying image search options.
+   * @returns {Promise<Images>} A Promise that resolves with the images for the TV season.
+   */
   async images(seasonSelection: SeasonSelection, options?: TvSeasonImageSearchOptions) {
     const computedOptions = {
       include_image_language: options?.include_image_language?.join(','),
@@ -79,6 +112,12 @@ export class TvSeasonsEndpoint extends BaseEndpoint {
     return await this.api.get<Images>(`${BASE_SEASON(seasonSelection)}/images`, computedOptions);
   }
 
+  /**
+   * Retrieves videos for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {TvSeasonVideoSearchOptions} [options] - Optional parameters for specifying video search options.
+   * @returns {Promise<Videos>} A Promise that resolves with the videos for the TV season.
+   */
   async videos(seasonSelection: SeasonSelection, options?: TvSeasonVideoSearchOptions) {
     const computedOptions = {
       include_video_language: options?.include_video_language?.join(','),
@@ -87,6 +126,12 @@ export class TvSeasonsEndpoint extends BaseEndpoint {
     return await this.api.get<Videos>(`${BASE_SEASON(seasonSelection)}/videos`, computedOptions);
   }
 
+  /**
+   * Retrieves translations for a specific TV season asynchronously.
+   * @param {SeasonSelection} seasonSelection - The selection criteria for the TV season.
+   * @param {LanguageOption} [options] - Optional parameters for specifying the language.
+   * @returns {Promise<Translations>} A Promise that resolves with the translations for the TV season.
+   */
   async translations(seasonSelection: SeasonSelection, options?: LanguageOption) {
     return await this.api.get<Translations>(`${BASE_SEASON(seasonSelection)}/translations`, options);
   }

package/src/endpoints/tvShows.ts

@@ -36,12 +36,31 @@ import {
 
 const BASE_TV = '/tv';
 
+/**
+ * Represents an endpoint for accessing TV show-related information.
+ */
 export class TvShowsEndpoint extends BaseEndpoint {
+  /**
+   * Constructs a new TvShowsEndpoint instance.
+   * @param {string} access_token - The access token used for authentication.
+   */
   constructor(protected readonly access_token: string) {
     super(access_token);
   }
 
-  async details<T extends AppendToResponseTvKey[] | undefined>(id: number, appendToResponse?: T, language?: string) {
+  /**
+   * Retrieves details of a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {AppendToResponseTvKey[]} [appendToResponse] - Additional data to append to the response.
+   * @param {string} [language] - The language for the response.
+   * @returns {Promise<AppendToResponse<TvShowDetails, AppendToResponseTvKey[], 'tvShow'>>}
+   * A Promise that resolves with the details of the TV show.
+   */
+  async details<T extends AppendToResponseTvKey[] | undefined>(
+    id: number,
+    appendToResponse?: T,
+    language?: string,
+  ): Promise<AppendToResponse<TvShowDetails, T, 'tvShow'>> {
     const options = {
       append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
       language: language,
@@ -49,38 +68,89 @@ export class TvShowsEndpoint extends BaseEndpoint {
     return await this.api.get<AppendToResponse<TvShowDetails, T, 'tvShow'>>(`${BASE_TV}/${id}`, options);
   }
 
+  /**
+   * Retrieves alternative titles of a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<AlternativeTitles>} A Promise that resolves with the alternative titles of the TV show.
+   */
   async alternativeTitles(id: number): Promise<AlternativeTitles> {
     return await this.api.get<AlternativeTitles>(`${BASE_TV}/${id}/alternative_titles`);
   }
 
+  /**
+   * Retrieves changes for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {ChangeOption} [options] - Additional options for the request.
+   * @returns {Promise<Changes<TvShowChangeValue>>}
+   * A Promise that resolves with the changes for the TV show.
+   */
   async changes(id: number, options?: ChangeOption): Promise<Changes<TvShowChangeValue>> {
     return await this.api.get<Changes<TvShowChangeValue>>(`${BASE_TV}/${id}/changes`, options);
   }
 
+  /**
+   * Retrieves content ratings for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<ContentRatings>} A Promise that resolves with the content ratings of the TV show.
+   */
   async contentRatings(id: number): Promise<ContentRatings> {
     return await this.api.get<ContentRatings>(`${BASE_TV}/${id}/content_ratings`);
   }
 
+  /**
+   * Retrieves aggregate credits for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {LanguageOption} [options] - Additional options for the request.
+   * @returns {Promise<AggregateCredits>} A Promise that resolves with the aggregate credits of the TV show.
+   */
   async aggregateCredits(id: number, options?: LanguageOption): Promise<AggregateCredits> {
     return await this.api.get<AggregateCredits>(`${BASE_TV}/${id}/aggregate_credits`, options);
   }
 
+  /**
+   * Retrieves credits for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {LanguageOption} [options] - Additional options for the request.
+   * @returns {Promise<Credits>} A Promise that resolves with the credits of the TV show.
+   */
   async credits(id: number, options?: LanguageOption): Promise<Credits> {
     return await this.api.get<Credits>(`${BASE_TV}/${id}/credits`, options);
   }
 
+  /**
+   * Retrieves details of a specific season of a TV show asynchronously.
+   * @param {number} tvId - The ID of the TV show.
+   * @param {number} seasonNumber - The season number.
+   * @returns {Promise<SeasonDetails>} A Promise that resolves with the details of the season.
+   */
   async season(tvId: number, seasonNumber: number): Promise<SeasonDetails> {
     return await this.api.get<SeasonDetails>(`${BASE_TV}/${tvId}/season/${seasonNumber}`);
   }
 
+  /**
+   * Retrieves episode groups for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<EpisodeGroups>} A Promise that resolves with the episode groups of the TV show.
+   */
   async episodeGroups(id: number): Promise<EpisodeGroups> {
     return await this.api.get<EpisodeGroups>(`${BASE_TV}/${id}/episode_groups`);
   }
 
+  /**
+   * Retrieves external IDs for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<ExternalIds>} A Promise that resolves with the external IDs of the TV show.
+   */
   async externalIds(id: number): Promise<ExternalIds> {
     return await this.api.get<ExternalIds>(`${BASE_TV}/${id}/external_ids`);
   }
 
+  /**
+   * Retrieves images for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {TvShowImageOptions} [options] - Additional options for the request.
+   * @returns {Promise<Images>} A Promise that resolves with the images of the TV show.
+   */
   async images(id: number, options?: TvShowImageOptions): Promise<Images> {
     const computedOptions = {
       include_image_language: options?.include_image_language?.join(','),
@@ -89,30 +159,69 @@ export class TvShowsEndpoint extends BaseEndpoint {
     return await this.api.get<Images>(`${BASE_TV}/${id}/images`, computedOptions);
   }
 
+  /**
+   * Retrieves keywords for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<Keywords>} A Promise that resolves with the keywords of the TV show.
+   */
   async keywords(id: number): Promise<Keywords> {
     return await this.api.get<Keywords>(`${BASE_TV}/${id}/keywords`);
   }
 
+  /**
+   * Retrieves recommendations for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {LanguageOption & PageOption} [options] - Additional options for the request.
+   * @returns {Promise<Recommendations>} A Promise that resolves with the recommendations for the TV show.
+   */
   async recommendations(id: number, options?: LanguageOption & PageOption): Promise<Recommendations> {
     return await this.api.get<Recommendations>(`${BASE_TV}/${id}/recommendations`, options);
   }
 
+  /**
+   * Retrieves reviews for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {LanguageOption & PageOption} [options] - Additional options for the request.
+   * @returns {Promise<Reviews>} A Promise that resolves with the reviews of the TV show.
+   */
   async reviews(id: number, options?: LanguageOption & PageOption): Promise<Reviews> {
     return await this.api.get<Reviews>(`${BASE_TV}/${id}/reviews`, options);
   }
 
+  /**
+   * Retrieves information about whether the TV show was screened theatrically asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<ScreenedTheatrically>} A Promise that resolves with information about theatrical screenings.
+   */
   async screenedTheatrically(id: number): Promise<ScreenedTheatrically> {
     return await this.api.get<ScreenedTheatrically>(`${BASE_TV}/${id}/screened_theatrically`);
   }
 
+  /**
+   * Retrieves similar TV shows for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {LanguageOption & PageOption} [options] - Additional options for the request.
+   * @returns {Promise<Similartv>} A Promise that resolves with the similar TV shows.
+   */
   async similar(id: number, options?: LanguageOption & PageOption): Promise<Similartv> {
     return await this.api.get<Similartv>(`${BASE_TV}/${id}/similar`, options);
   }
 
+  /**
+   * Retrieves translations for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<Translations>} A Promise that resolves with the translations of the TV show.
+   */
   async translations(id: number): Promise<Translations> {
     return await this.api.get<Translations>(`${BASE_TV}/${id}/translations`);
   }
 
+  /**
+   * Retrieves videos for a specific TV show asynchronously.
+   * @param {number} id - The ID of the TV show.
+   * @param {TvShowVideoOptions} [options] - Additional options for the request.
+   * @returns {Promise<Videos>} A Promise that resolves with the videos of the TV show.
+   */
   async videos(id: number, options?: TvShowVideoOptions): Promise<Videos> {
     const computedOptions = {
       include_video_language: options?.include_video_language?.join(','),
@@ -122,29 +231,55 @@ export class TvShowsEndpoint extends BaseEndpoint {
   }
 
   /**
-   * Powered by JustWatch
-   * @param id
+   * Retrieves watch providers for a specific TV show asynchronously.
+   * Powered by JustWatch.
+   * @param {number} id - The ID of the TV show.
+   * @returns {Promise<WatchProviders>} A Promise that resolves with the watch providers of the TV show.
    */
   async watchProviders(id: number): Promise<WatchProviders> {
     return await this.api.get<WatchProviders>(`${BASE_TV}/${id}/watch/providers`);
   }
 
+  /**
+   * Retrieves the latest TV show asynchronously.
+   * @returns {Promise<Latesttv>} A Promise that resolves with the latest TV show.
+   */
   async latest(): Promise<Latesttv> {
     return await this.api.get<Latesttv>(`${BASE_TV}/latest`);
   }
 
+  /**
+   * Retrieves TV shows that are currently on the air asynchronously.
+   * @param {PageOption & LanguageOption & TimezoneOption} [options] - Additional options for the request.
+   * @returns {Promise<OnTheAir>} A Promise that resolves with TV shows currently on the air.
+   */
   async onTheAir(options?: PageOption & LanguageOption & TimezoneOption): Promise<OnTheAir> {
     return await this.api.get<OnTheAir>(`${BASE_TV}/on_the_air`, options);
   }
 
+  /**
+   * Retrieves TV shows that are airing today asynchronously.
+   * @param {PageOption & LanguageOption & TimezoneOption} [options] - Additional options for the request.
+   * @returns {Promise<tvAiringToday>} A Promise that resolves with TV shows airing today.
+   */
   async airingToday(options?: PageOption & LanguageOption & TimezoneOption): Promise<tvAiringToday> {
     return await this.api.get<tvAiringToday>(`${BASE_TV}/airing_today`, options);
   }
 
+  /**
+   * Retrieves popular TV shows asynchronously.
+   * @param {PageOption & LanguageOption} [options] - Additional options for the request.
+   * @returns {Promise<Populartv>} A Promise that resolves with popular TV shows.
+   */
   async popular(options?: PageOption & LanguageOption): Promise<Populartv> {
     return await this.api.get<Populartv>(`${BASE_TV}/popular`, options);
   }
 
+  /**
+   * Retrieves top-rated TV shows asynchronously.
+   * @param {PageOption & LanguageOption} [options] - Additional options for the request.
+   * @returns {Promise<TopRatedtv>} A Promise that resolves with top-rated TV shows.
+   */
   async topRated(options?: PageOption & LanguageOption): Promise<TopRatedtv> {
     return await this.api.get<TopRatedtv>(`${BASE_TV}/top_rated`, options);
   }