@tdanks2000/tmdb-wrapper 1.0.0

package/src/endpoints/people.ts

@@ -0,0 +1,79 @@
+import {
+  AppendToResponse,
+  AppendToResponsePersonKey,
+  BaseEndpoint,
+  ChangeOption,
+  Changes,
+  ExternalIds,
+  LanguageOption,
+  PageOption,
+  PeopleImages,
+  PersonChangeValue,
+  PersonCombinedCredits,
+  PersonDetails,
+  PersonMovieCredit,
+  PersonTranslations,
+  PersonTvShowCredit,
+  PopularPersons,
+  TaggedImages,
+} from '@/@types';
+
+const BASE_PERSON = '/person';
+
+export class PeopleEndpoint extends BaseEndpoint {
+  constructor(access_token: string) {
+    super(access_token);
+  }
+
+  async details<T extends AppendToResponsePersonKey[] | undefined>(
+    id: number,
+    appendToResponse?: T,
+    language?: string,
+  ) {
+    const options = {
+      append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
+      language: language,
+    };
+    return await this.api.get<AppendToResponse<PersonDetails, T, 'person'>>(`${BASE_PERSON}/${id}`, options);
+  }
+
+  async changes(id: number, options?: ChangeOption): Promise<Changes<PersonChangeValue>> {
+    return await this.api.get<Changes<PersonChangeValue>>(`${BASE_PERSON}/${id}/changes`, options);
+  }
+
+  async movieCredits(id: number, options?: LanguageOption): Promise<PersonMovieCredit> {
+    return await this.api.get<PersonMovieCredit>(`${BASE_PERSON}/${id}/movie_credits`, options);
+  }
+
+  async tvShowCredits(id: number, options?: LanguageOption): Promise<PersonTvShowCredit> {
+    return await this.api.get<PersonTvShowCredit>(`${BASE_PERSON}/${id}/tv_credits`, options);
+  }
+
+  async combinedCredits(id: number, options?: LanguageOption): Promise<PersonCombinedCredits> {
+    return await this.api.get<PersonCombinedCredits>(`${BASE_PERSON}/${id}/combined_credits`, options);
+  }
+
+  async externalId(id: number): Promise<ExternalIds> {
+    return await this.api.get<ExternalIds>(`${BASE_PERSON}/${id}/external_ids`);
+  }
+
+  async images(id: number): Promise<PeopleImages> {
+    return await this.api.get<PeopleImages>(`${BASE_PERSON}/${id}/images`);
+  }
+
+  async taggedImages(id: number, options?: PageOption): Promise<TaggedImages> {
+    return await this.api.get<TaggedImages>(`${BASE_PERSON}/${id}/tagged_images`, options);
+  }
+
+  async translation(id: number): Promise<PersonTranslations> {
+    return await this.api.get<PersonTranslations>(`${BASE_PERSON}/${id}/translations`);
+  }
+
+  async latest(): Promise<PersonDetails> {
+    return await this.api.get<PersonDetails>(`${BASE_PERSON}/latest`);
+  }
+
+  async popular(options?: LanguageOption & PageOption): Promise<PopularPersons> {
+    return await this.api.get<PopularPersons>(`${BASE_PERSON}/popular`, options);
+  }
+}

package/src/endpoints/review.ts

@@ -0,0 +1,11 @@
+import { BaseEndpoint, ReviewDetails } from '@/@types';
+
+export class ReviewEndpoint extends BaseEndpoint {
+  constructor(access_token: string) {
+    super(access_token);
+  }
+
+  async details(id: string): Promise<ReviewDetails> {
+    return await this.api.get<ReviewDetails>(`/review/${id}`);
+  }
+}

package/src/endpoints/search.ts

@@ -0,0 +1,78 @@
+import {
+  BaseEndpoint,
+  Collection,
+  Company,
+  LanguageOption,
+  Movie,
+  MultiSearchResult,
+  PageOption,
+  Person,
+  RegionOption,
+  Search,
+  TV,
+} 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;
+}
+
+export class SearchEndpoint extends BaseEndpoint {
+  constructor(protected readonly access_token: string) {
+    super(access_token);
+  }
+
+  async companies(options: SearchOptions): Promise<Search<Company>> {
+    return await this.api.get<Search<Company>>(`${BASE_SEARCH}/company`, options);
+  }
+
+  async collections(options: SearchOptions): Promise<Search<Collection>> {
+    return await this.api.get<Search<Collection>>(`${BASE_SEARCH}/collection`, options);
+  }
+
+  async keywords(options: SearchOptions): Promise<Search<{ id: string; name: string }>> {
+    return await this.api.get<Search<{ id: string; name: string }>>(`${BASE_SEARCH}/keyword`, options);
+  }
+
+  async movies(options: MovieSearchOptions): Promise<Search<Movie>> {
+    return await this.api.get<Search<Movie>>(`${BASE_SEARCH}/movie`, options);
+  }
+
+  async people(options: PeopleSearchOptions): Promise<Search<Person>> {
+    return await this.api.get<Search<Person>>(`${BASE_SEARCH}/person`, options);
+  }
+
+  async tv(options: TvSearchOptions): Promise<Search<TV>> {
+    return await this.api.get<Search<TV>>(`${BASE_SEARCH}/tv`, options);
+  }
+
+  async multi(options: MultiSearchOptions): Promise<Search<MultiSearchResult>> {
+    return await this.api.get<Search<MultiSearchResult>>(`${BASE_SEARCH}/multi`, options);
+  }
+}

package/src/endpoints/trending.ts

@@ -0,0 +1,15 @@
+import { BaseEndpoint, LanguageOption, TimeWindow, TrendingMediaType, TrendingResults } from '@/@types';
+
+export class TrendingEndpoint extends BaseEndpoint {
+  constructor(access_token: string) {
+    super(access_token);
+  }
+
+  async trending<T extends TrendingMediaType>(
+    mediaType: T,
+    timeWindow: TimeWindow,
+    options?: LanguageOption,
+  ): Promise<TrendingResults<T>> {
+    return await this.api.get<TrendingResults<T>>(`/trending/${mediaType}/${timeWindow}`, options);
+  }
+}

package/src/endpoints/tvEpisodes.ts

@@ -0,0 +1,88 @@
+import {
+  AppendToResponse,
+  AppendToResponseTvEpisodeKey,
+  BaseEndpoint,
+  ChangeOption,
+  Changes,
+  Episode,
+  EpisodeSelection,
+  ExternalIds,
+  Images,
+  LanguageOption,
+  TvEpisodeChangeValue,
+  TvEpisodeCredit,
+  TvEpisodeTranslations,
+  Videos,
+} from '@/@types';
+
+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 {
+  /**
+   * a list of ISO-639-1 values to query
+   */
+  include_video_language?: string[];
+}
+
+export class TvEpisodesEndpoint extends BaseEndpoint {
+  constructor(access_token: string) {
+    super(access_token);
+  }
+
+  async details<T extends AppendToResponseTvEpisodeKey[] | undefined>(
+    episodeSelection: EpisodeSelection,
+    appendToResponse?: T,
+    options?: LanguageOption,
+  ) {
+    const combinedOptions = {
+      append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
+      ...options,
+    };
+
+    return await this.api.get<AppendToResponse<Omit<Episode, 'show_id'>, T, 'tvEpisode'>>(
+      `${BASE_EPISODE(episodeSelection)}`,
+      combinedOptions,
+    );
+  }
+
+  async changes(episodeID: number, options?: ChangeOption) {
+    return await this.api.get<Changes<TvEpisodeChangeValue>>(`/tv/episode/${episodeID}/changes`, options);
+  }
+
+  async credits(episodeSelection: EpisodeSelection, options?: LanguageOption) {
+    return await this.api.get<TvEpisodeCredit>(`${BASE_EPISODE(episodeSelection)}/credits`, options);
+  }
+
+  async externalIds(episodeSelection: EpisodeSelection) {
+    return await this.api.get<ExternalIds>(`${BASE_EPISODE(episodeSelection)}/external_ids`);
+  }
+
+  async images(episodeSelection: EpisodeSelection, options?: TvEpisodeImageSearchOptions) {
+    const computedOptions = {
+      include_image_language: options?.include_image_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Images>(`${BASE_EPISODE(episodeSelection)}/images`, computedOptions);
+  }
+
+  async translations(episodeSelection: EpisodeSelection) {
+    return await this.api.get<TvEpisodeTranslations>(`${BASE_EPISODE(episodeSelection)}/translations`);
+  }
+
+  async videos(episodeSelection: EpisodeSelection, options?: TvEpisodeVideoSearchOptions) {
+    const computedOptions = {
+      include_video_language: options?.include_video_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Videos>(`${BASE_EPISODE(episodeSelection)}/videos`, computedOptions);
+  }
+}

package/src/endpoints/tvSeasons.ts

@@ -0,0 +1,93 @@
+import {
+  AggregateCredits,
+  AppendToResponse,
+  AppendToResponseTvSeasonKey,
+  BaseEndpoint,
+  ChangeOption,
+  Changes,
+  Credits,
+  ExternalIds,
+  Images,
+  LanguageOption,
+  SeasonDetails,
+  SeasonSelection,
+  Translations,
+  TvSeasonChangeValue,
+  Videos,
+} from '@/@types';
+
+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 {
+  /**
+   * a list of ISO-639-1 values to query
+   */
+  include_video_language?: string[];
+}
+
+export class TvSeasonsEndpoint extends BaseEndpoint {
+  constructor(access_token: string) {
+    super(access_token);
+  }
+
+  async details<T extends AppendToResponseTvSeasonKey[] | undefined>(
+    seasonSelection: SeasonSelection,
+    appendToResponse?: T,
+    options?: LanguageOption,
+  ) {
+    const combinedOptions = {
+      append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
+      ...options,
+    };
+
+    return await this.api.get<AppendToResponse<SeasonDetails, T, 'tvSeason'>>(
+      `${BASE_SEASON(seasonSelection)}`,
+      combinedOptions,
+    );
+  }
+
+  async aggregateCredits(seasonSelection: SeasonSelection, options?: LanguageOption) {
+    return await this.api.get<AggregateCredits>(`${BASE_SEASON(seasonSelection)}/aggregate_credits`, options);
+  }
+
+  async changes(seasonId: number, options?: ChangeOption) {
+    return await this.api.get<Changes<TvSeasonChangeValue>>(`/tv/season/${seasonId}/changes`, options);
+  }
+
+  async credits(seasonSelection: SeasonSelection, options?: LanguageOption) {
+    return await this.api.get<Credits>(`${BASE_SEASON(seasonSelection)}/credits`, options);
+  }
+
+  async externalIds(seasonSelection: SeasonSelection, options?: LanguageOption) {
+    return await this.api.get<ExternalIds>(`${BASE_SEASON(seasonSelection)}/external_ids`, options);
+  }
+
+  async images(seasonSelection: SeasonSelection, options?: TvSeasonImageSearchOptions) {
+    const computedOptions = {
+      include_image_language: options?.include_image_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Images>(`${BASE_SEASON(seasonSelection)}/images`, computedOptions);
+  }
+
+  async videos(seasonSelection: SeasonSelection, options?: TvSeasonVideoSearchOptions) {
+    const computedOptions = {
+      include_video_language: options?.include_video_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Videos>(`${BASE_SEASON(seasonSelection)}/videos`, computedOptions);
+  }
+
+  async translations(seasonSelection: SeasonSelection, options?: LanguageOption) {
+    return await this.api.get<Translations>(`${BASE_SEASON(seasonSelection)}/translations`, options);
+  }
+}

package/src/endpoints/tvShows.ts

@@ -0,0 +1,151 @@
+import {
+  AggregateCredits,
+  AlternativeTitles,
+  AppendToResponse,
+  AppendToResponseTvKey,
+  BaseEndpoint,
+  ChangeOption,
+  Changes,
+  ContentRatings,
+  Credits,
+  EpisodeGroups,
+  ExternalIds,
+  Images,
+  Keywords,
+  LanguageOption,
+  Latesttv,
+  OnTheAir,
+  PageOption,
+  Populartv,
+  Recommendations,
+  Reviews,
+  ScreenedTheatrically,
+  SeasonDetails,
+  Similartv,
+  TimezoneOption,
+  TopRatedtv,
+  Translations,
+  TvShowChangeValue,
+  TvShowDetails,
+  TvShowImageOptions,
+  TvShowVideoOptions,
+  Videos,
+  WatchProviders,
+  tvAiringToday,
+} from '@/@types';
+
+const BASE_TV = '/tv';
+
+export class TvShowsEndpoint extends BaseEndpoint {
+  constructor(protected readonly access_token: string) {
+    super(access_token);
+  }
+
+  async details<T extends AppendToResponseTvKey[] | undefined>(id: number, appendToResponse?: T, language?: string) {
+    const options = {
+      append_to_response: appendToResponse ? appendToResponse.join(',') : undefined,
+      language: language,
+    };
+    return await this.api.get<AppendToResponse<TvShowDetails, T, 'tvShow'>>(`${BASE_TV}/${id}`, options);
+  }
+
+  async alternativeTitles(id: number): Promise<AlternativeTitles> {
+    return await this.api.get<AlternativeTitles>(`${BASE_TV}/${id}/alternative_titles`);
+  }
+
+  async changes(id: number, options?: ChangeOption): Promise<Changes<TvShowChangeValue>> {
+    return await this.api.get<Changes<TvShowChangeValue>>(`${BASE_TV}/${id}/changes`, options);
+  }
+
+  async contentRatings(id: number): Promise<ContentRatings> {
+    return await this.api.get<ContentRatings>(`${BASE_TV}/${id}/content_ratings`);
+  }
+
+  async aggregateCredits(id: number, options?: LanguageOption): Promise<AggregateCredits> {
+    return await this.api.get<AggregateCredits>(`${BASE_TV}/${id}/aggregate_credits`, options);
+  }
+
+  async credits(id: number, options?: LanguageOption): Promise<Credits> {
+    return await this.api.get<Credits>(`${BASE_TV}/${id}/credits`, options);
+  }
+
+  async season(tvId: number, seasonNumber: number): Promise<SeasonDetails> {
+    return await this.api.get<SeasonDetails>(`${BASE_TV}/${tvId}/season/${seasonNumber}`);
+  }
+
+  async episodeGroups(id: number): Promise<EpisodeGroups> {
+    return await this.api.get<EpisodeGroups>(`${BASE_TV}/${id}/episode_groups`);
+  }
+
+  async externalIds(id: number): Promise<ExternalIds> {
+    return await this.api.get<ExternalIds>(`${BASE_TV}/${id}/external_ids`);
+  }
+
+  async images(id: number, options?: TvShowImageOptions): Promise<Images> {
+    const computedOptions = {
+      include_image_language: options?.include_image_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Images>(`${BASE_TV}/${id}/images`, computedOptions);
+  }
+
+  async keywords(id: number): Promise<Keywords> {
+    return await this.api.get<Keywords>(`${BASE_TV}/${id}/keywords`);
+  }
+
+  async recommendations(id: number, options?: LanguageOption & PageOption): Promise<Recommendations> {
+    return await this.api.get<Recommendations>(`${BASE_TV}/${id}/recommendations`, options);
+  }
+
+  async reviews(id: number, options?: LanguageOption & PageOption): Promise<Reviews> {
+    return await this.api.get<Reviews>(`${BASE_TV}/${id}/reviews`, options);
+  }
+
+  async screenedTheatrically(id: number): Promise<ScreenedTheatrically> {
+    return await this.api.get<ScreenedTheatrically>(`${BASE_TV}/${id}/screened_theatrically`);
+  }
+
+  async similar(id: number, options?: LanguageOption & PageOption): Promise<Similartv> {
+    return await this.api.get<Similartv>(`${BASE_TV}/${id}/similar`, options);
+  }
+
+  async translations(id: number): Promise<Translations> {
+    return await this.api.get<Translations>(`${BASE_TV}/${id}/translations`);
+  }
+
+  async videos(id: number, options?: TvShowVideoOptions): Promise<Videos> {
+    const computedOptions = {
+      include_video_language: options?.include_video_language?.join(','),
+      language: options?.language,
+    };
+    return await this.api.get<Videos>(`${BASE_TV}/${id}/videos`, computedOptions);
+  }
+
+  /**
+   * Powered by JustWatch
+   * @param id
+   */
+  async watchProviders(id: number): Promise<WatchProviders> {
+    return await this.api.get<WatchProviders>(`${BASE_TV}/${id}/watch/providers`);
+  }
+
+  async latest(): Promise<Latesttv> {
+    return await this.api.get<Latesttv>(`${BASE_TV}/latest`);
+  }
+
+  async onTheAir(options?: PageOption & LanguageOption & TimezoneOption): Promise<OnTheAir> {
+    return await this.api.get<OnTheAir>(`${BASE_TV}/on_the_air`, options);
+  }
+
+  async airingToday(options?: PageOption & LanguageOption & TimezoneOption): Promise<tvAiringToday> {
+    return await this.api.get<tvAiringToday>(`${BASE_TV}/airing_today`, options);
+  }
+
+  async popular(options?: PageOption & LanguageOption): Promise<Populartv> {
+    return await this.api.get<Populartv>(`${BASE_TV}/popular`, options);
+  }
+
+  async topRated(options?: PageOption & LanguageOption): Promise<TopRatedtv> {
+    return await this.api.get<TopRatedtv>(`${BASE_TV}/top_rated`, options);
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+import {
+  AccountEndpoint,
+  CertificationEndpoint,
+  ChangeEndpoint,
+  CollectionsEndpoint,
+  ConfigurationEndpoint,
+  CreditsEndpoint,
+  DiscoverEndpoint,
+  FindEndpoint,
+  GenreEndpoint,
+  KeywordsEndpoint,
+  MoviesEndpoint,
+  PeopleEndpoint,
+  ReviewEndpoint,
+  SearchEndpoint,
+  TrendingEndpoint,
+  TvEpisodesEndpoint,
+  TvSeasonsEndpoint,
+  TvShowsEndpoint,
+} from '@/endpoints';
+
+class TMDB {
+  constructor(access_token: string) {
+    this.account = new AccountEndpoint(access_token);
+    this.certification = new CertificationEndpoint(access_token);
+    this.changes = new ChangeEndpoint(access_token);
+    this.collections = new CollectionsEndpoint(access_token);
+    this.configuration = new ConfigurationEndpoint(access_token);
+    this.credits = new CreditsEndpoint(access_token);
+    this.discover = new DiscoverEndpoint(access_token);
+    this.find = new FindEndpoint(access_token);
+    this.genre = new GenreEndpoint(access_token);
+    this.keywords = new KeywordsEndpoint(access_token);
+    this.movies = new MoviesEndpoint(access_token);
+    this.people = new PeopleEndpoint(access_token);
+    this.review = new ReviewEndpoint(access_token);
+    this.search = new SearchEndpoint(access_token);
+    this.trending = new TrendingEndpoint(access_token);
+    this.tvEpisodes = new TvEpisodesEndpoint(access_token);
+    this.tvSeasons = new TvSeasonsEndpoint(access_token);
+    this.tvShows = new TvShowsEndpoint(access_token);
+  }
+
+  account: AccountEndpoint;
+  certification: CertificationEndpoint;
+  changes: ChangeEndpoint;
+  collections: CollectionsEndpoint;
+  configuration: ConfigurationEndpoint;
+  credits: CreditsEndpoint;
+  discover: DiscoverEndpoint;
+  find: FindEndpoint;
+  genre: GenreEndpoint;
+  keywords: KeywordsEndpoint;
+  movies: MoviesEndpoint;
+  people: PeopleEndpoint;
+  review: ReviewEndpoint;
+  search: SearchEndpoint;
+  trending: TrendingEndpoint;
+  tvEpisodes: TvEpisodesEndpoint;
+  tvSeasons: TvSeasonsEndpoint;
+  tvShows: TvShowsEndpoint;
+}
+
+export * from './@types';
+export * from './utils';
+export { TMDB };

package/src/utils/api.ts

@@ -0,0 +1,31 @@
+import { ErrorResponse } from '@/@types';
+
+const BASE_URL_V3 = 'https://api.themoviedb.org/3';
+
+export class API {
+  private access_token: string;
+  constructor(access_token: string) {
+    this.access_token = access_token;
+  }
+
+  async get<T>(path: string, options?: Record<string, any>): Promise<T> {
+    const params = parseOptions(options);
+    const response = await fetch(`${BASE_URL_V3}${path}?${params}`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${this.access_token}`,
+        'Content-Type': 'application/json;charset=utf-8',
+      },
+    });
+
+    if (!response.ok) {
+      return Promise.reject((await response.json()) as ErrorResponse);
+    }
+
+    return (await response.json()) as T;
+  }
+}
+
+export const parseOptions = (options?: Record<string, any>): string => {
+  return options ? new URLSearchParams(Object.entries(options)).toString() : '';
+};

package/src/utils/getimagePath.ts

@@ -0,0 +1,16 @@
+/**
+ * Utility method to construct full url for image
+ * based on configuration
+ *
+ * https://developers.themoviedb.org/3/getting-started/images
+ * @param {string} baseUrl base image url
+ * @param {string} fileSize file size
+ * @param {string} imagePath raw image path
+ * @param {boolean} svg get svg version if true
+ */
+export const getFullImagePath = (baseUrl: string, fileSize: string, imagePath: string, svg = false): string => {
+  const imagePathArr = imagePath.split('.');
+  const imageFormat = svg ? 'svg' : imagePathArr[1];
+
+  return `${baseUrl}${fileSize}${imagePathArr[0]}.${imageFormat}`;
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './api';
+export * from './getimagePath';