@tutkli/jikan-ts 0.5.0

package/src/clients/manga.client.ts

@@ -0,0 +1,142 @@
+import { BaseClient, ClientArgs } from './base.client';
+import { MangaEndpoints } from '../constants';
+import { CacheAxiosResponse } from 'axios-cache-interceptor';
+import { AxiosError } from 'axios';
+import {
+  CommonCharacter,
+  JikanImages,
+  JikanResponse,
+  JikanUniqueResponse,
+  Manga,
+  MangaStatistics,
+  Recommendation,
+} from '../models';
+import { MangaSearchParams } from '../models/Params';
+
+/**
+ * **Manga Client**
+ *
+ * Client used to access the Manga Endpoints:
+ * - [MangaSearch](https://docs.api.jikan.moe/#tag/manga)
+ * - [MangaFullById](https://docs.api.jikan.moe/#tag/manga/operation/getMangaFullById)
+ * - [MangaById](https://docs.api.jikan.moe/#tag/manga/operation/getMangaById)
+ * - [MangaCharacters](https://docs.api.jikan.moe/#tag/manga/operation/getMangaCharacters)
+ * - [MangaPictures](https://docs.api.jikan.moe/#tag/manga/operation/getMangaPictures)
+ * - [MangaStatistics](https://docs.api.jikan.moe/#tag/manga/operation/getMangaStatistics)
+ * - [MangaRecommendations](https://docs.api.jikan.moe/#tag/manga/operation/getMangaRecommendations)
+ *
+ * See also: [JikanAPI Documentation](https://docs.api.jikan.moe/)
+ */
+export class MangaClient extends BaseClient {
+  /**
+   * @argument clientOptions Options for the client.
+   */
+  constructor(clientOptions?: ClientArgs) {
+    super(clientOptions);
+  }
+
+  /**
+   * Get all the filtered Mangas. Returns all the Mangas if no filters are given.
+   * @param searchParams Filter parameters
+   * @returns A JikanResponse with Manga data
+   */
+  public async getMangaSearch(searchParams: MangaSearchParams): Promise<JikanResponse<Manga>> {
+    return new Promise<JikanResponse<Manga>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaSearch}`;
+      this.api
+        .get<JikanResponse<Manga>>(endpoint, { params: searchParams })
+        .then((response: CacheAxiosResponse<JikanResponse<Manga>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get a Manga with full information by its ID
+   * @param mal_id The Manga ID
+   * @returns A JikanUniqueResponse with Manga data
+   */
+  public async getMangaFullById(mal_id: number): Promise<JikanUniqueResponse<Manga>> {
+    return new Promise<JikanUniqueResponse<Manga>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaFullById.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanUniqueResponse<Manga>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanUniqueResponse<Manga>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get a Manga by its ID
+   * @param mal_id The Manga ID
+   * @returns A JikanUniqueResponse with Manga data
+   */
+  public async getMangaById(mal_id: number): Promise<JikanUniqueResponse<Manga>> {
+    return new Promise<JikanUniqueResponse<Manga>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaById.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanUniqueResponse<Manga>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanUniqueResponse<Manga>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get Characters of a specific Manga
+   * @param mal_id The Manga ID
+   * @returns A JikanResponse with CommonCharacter data
+   */
+  public async getMangaCharacters(mal_id: number): Promise<JikanResponse<CommonCharacter>> {
+    return new Promise<JikanResponse<CommonCharacter>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaCharacters.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanResponse<CommonCharacter>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanResponse<CommonCharacter>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get Pictures related to a specific Manga
+   * @param mal_id The Manga ID
+   * @returns A JikanResponse with JikanImages data
+   */
+  public async getMangaPictures(mal_id: number): Promise<JikanResponse<JikanImages>> {
+    return new Promise<JikanResponse<JikanImages>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaPictures.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanResponse<JikanImages>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanResponse<JikanImages>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get Statistics related to a specific Manga
+   * @param mal_id The Manga ID
+   * @returns A JikanUniqueResponse with MangaStatistics data
+   */
+  public async getAnimeStatistics(mal_id: number): Promise<JikanUniqueResponse<MangaStatistics>> {
+    return new Promise<JikanUniqueResponse<MangaStatistics>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaStatistics.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanUniqueResponse<MangaStatistics>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanUniqueResponse<MangaStatistics>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get Recommendations related to a specific Manga
+   * @param mal_id The Manga ID
+   * @returns A JikanResponse with Recommendation data
+   */
+  public async getMangaRecommendation(mal_id: number): Promise<JikanResponse<Recommendation>> {
+    return new Promise<JikanResponse<Recommendation>>((resolve, reject) => {
+      const endpoint = `${MangaEndpoints.MangaRecommendations.replace('{id}', String(mal_id))}`;
+      this.api
+        .get<JikanResponse<Recommendation>>(endpoint)
+        .then((response: CacheAxiosResponse<JikanResponse<Recommendation>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+}

package/src/clients/top.client.ts

@@ -0,0 +1,52 @@
+import { BaseClient, ClientArgs } from './base.client';
+import { Anime, JikanResponse, Manga } from '../models';
+import { TopEndpoints } from '../constants';
+import { CacheAxiosResponse } from 'axios-cache-interceptor';
+import { AxiosError } from 'axios';
+import { AnimeTopParams, MangaTopParams } from '../models/Params';
+
+/**
+ * **Anime Client**
+ *
+ * Client used to access the Top Endpoints:
+ * - [TopAnime](https://docs.api.jikan.moe/#tag/top/operation/getTopAnime)
+ * - [TopManga](https://docs.api.jikan.moe/#tag/top/operation/getTopManga)
+ *
+ * See also: [JikanAPI Documentation](https://docs.api.jikan.moe/)
+ */
+export class TopClient extends BaseClient {
+  /**
+   * @argument clientOptions Options for the client.
+   */
+  constructor(clientOptions?: ClientArgs) {
+    super(clientOptions);
+  }
+
+  /**
+   * Get the top Animes
+   * @returns A JikanResponse with Anime data
+   */
+  public async getTopAnime(searchParams: AnimeTopParams): Promise<JikanResponse<Anime>> {
+    return new Promise<JikanResponse<Anime>>((resolve, reject) => {
+      const endpoint = `${TopEndpoints.TopAnime}`;
+      this.api
+        .get<JikanResponse<Anime>>(endpoint, { params: searchParams })
+        .then((response: CacheAxiosResponse<JikanResponse<Anime>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+
+  /**
+   * Get the top Mangas
+   * @returns A JikanResponse with Manga data
+   */
+  public async getTopManga(searchParams: MangaTopParams): Promise<JikanResponse<Manga>> {
+    return new Promise<JikanResponse<Manga>>((resolve, reject) => {
+      const endpoint = `${TopEndpoints.TopManga}`;
+      this.api
+        .get<JikanResponse<Manga>>(endpoint, { params: searchParams })
+        .then((response: CacheAxiosResponse<JikanResponse<Manga>>) => resolve(response.data))
+        .catch((error: AxiosError<string>) => reject(error));
+    });
+  }
+}

package/src/config/cache.config.ts

@@ -0,0 +1,8 @@
+import { buildMemoryStorage, defaultHeaderInterpreter, defaultKeyGenerator } from 'axios-cache-interceptor';
+
+export const DEFAULT_CACHE_OPTIONS = {
+  storage: buildMemoryStorage(),
+  generateKey: defaultKeyGenerator,
+  headerInterpreter: defaultHeaderInterpreter,
+  debug: undefined,
+};

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './cache.config';
+export * from './logger.config';

package/src/config/logger.config.ts

@@ -0,0 +1,25 @@
+import { DestinationStream, Logger, LoggerOptions, pino } from 'pino';
+import { AxiosError } from 'axios';
+import { CacheAxiosResponse, CacheRequestConfig } from 'axios-cache-interceptor';
+
+export const createLogger = (options: LoggerOptions | DestinationStream): Logger => pino(options);
+
+export const handleRequest = (config: CacheRequestConfig, logger: Logger): CacheRequestConfig => {
+  logger.info(`[ Request Config ] ${config.method?.toUpperCase() || ''} | ${config.url || ''}`);
+  return config;
+};
+
+export const handleRequestError = (error: AxiosError, logger: Logger): Promise<AxiosError> => {
+  logger.error(`[ Request Error] CODE ${error.code || 'UNKNOWN'} | ${error.message}`);
+  throw error;
+};
+
+export const handleResponse = (response: CacheAxiosResponse, logger: Logger): CacheAxiosResponse => {
+  logger.info(response.data);
+  return response;
+};
+
+export const handleResponseError = (error: AxiosError, logger: Logger): Promise<AxiosError> => {
+  logger.error(`[ Response Error ] CODE ${error.code || 'UNKNOWN'} | ${error.message}`);
+  throw error;
+};

package/src/constants/base.constant.ts

@@ -0,0 +1,3 @@
+export enum BaseURL {
+  REST = 'https://api.jikan.moe/v4',
+}

package/src/constants/endpoints.constant.ts

@@ -0,0 +1,29 @@
+export enum AnimeEndpoints {
+  AnimeSearch = '/anime',
+  AnimeFullById = '/anime/{id}/full',
+  AnimeById = '/anime/{id}',
+  AnimeCharacters = '/anime/{id}/characters',
+  AnimeStaff = '/anime/{id}/staff',
+  AnimeEpisodes = '/anime/{id}/episodes',
+  AnimeEpisodeById = '/anime/{id}/episodes/{episode}',
+  AnimeVideos = '/anime/{id}/videos',
+  AnimeVideosEpisodes = '/anime/{id}/videos/episodes',
+  AnimePictures = '/anime/{id}/pictures',
+  AnimeStatistics = '/anime/{id}/statistics',
+  AnimeRecommendations = '/anime/{id}/recommendations',
+}
+
+export enum MangaEndpoints {
+  MangaSearch = '/manga',
+  MangaFullById = '/manga/{id}/full',
+  MangaById = '/manga/{id}',
+  MangaCharacters = '/manga/{id}/characters',
+  MangaPictures = '/manga/{id}/pictures',
+  MangaStatistics = '/manga/{id}/statistics',
+  MangaRecommendations = '/manga/{id}/recommendations',
+}
+
+export enum TopEndpoints {
+  TopAnime = '/top/anime',
+  TopManga = '/top/manga',
+}

package/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './base.constant';
+export * from './endpoints.constant';

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './clients';
+export * from './config';
+export * from './constants';
+export * from './models';

package/src/models/Anime/anime-character.model.ts

@@ -0,0 +1,11 @@
+import { CommonCharacter } from '../Common/character.model';
+import { JikanPerson } from '../Common/person.model';
+
+export interface AnimeCharacter extends CommonCharacter {
+  voice_actors: AnimeCharacterVoiceActor[];
+}
+
+export interface AnimeCharacterVoiceActor {
+  person: JikanPerson;
+  language: string;
+}

package/src/models/Anime/anime-episode.model.ts

@@ -0,0 +1,12 @@
+export interface AnimeEpisode {
+  mal_id: number;
+  url: string;
+  title: string;
+  title_japanese: string;
+  title_romanji: string;
+  duration: number;
+  aired: string;
+  filler: boolean;
+  recap: boolean;
+  forum_url: string;
+}

package/src/models/Anime/anime-picture.model.ts

@@ -0,0 +1,5 @@
+import { JikanImages } from '../Common';
+
+export interface AnimePicture {
+  images: JikanImages;
+}

package/src/models/Anime/anime-staff.model.ts

@@ -0,0 +1,6 @@
+import { JikanPerson } from '../Common';
+
+export interface AnimeStaff {
+  person: JikanPerson;
+  positions: string[];
+}

package/src/models/Anime/anime-statistics.model.ts

@@ -0,0 +1,6 @@
+import { Statistics } from '../Common';
+
+export interface AnimeStatistics extends Statistics {
+  watching: number;
+  plan_to_watch: number;
+}

package/src/models/Anime/anime-video.model.ts

@@ -0,0 +1,38 @@
+import { JikanImages, JikanImagesCollection } from '../Common';
+
+export interface AnimeVideo {
+  promo: AnimeVideoPromo[];
+  episodes: AnimeVideoEpisode[];
+  music_videos: AnimeMusicVideo[];
+}
+
+export interface AnimeVideoPromo {
+  title: string;
+  trailer: AnimeYoutubeVideo;
+}
+
+export interface AnimeYoutubeVideo {
+  youtube_id: string;
+  url: string;
+  embed_url: string;
+  images?: JikanImagesCollection;
+}
+
+export interface AnimeVideoEpisode {
+  mal_id: number;
+  url: string;
+  title: string;
+  episode: string;
+  images: JikanImages;
+}
+
+export interface AnimeMusicVideo {
+  title: string;
+  video: AnimeYoutubeVideo;
+  meta: AnimeVideoMeta;
+}
+
+export interface AnimeVideoMeta {
+  title: string;
+  author: string;
+}

package/src/models/Anime/anime.model.ts

@@ -0,0 +1,95 @@
+import {
+  JikanImages,
+  JikanNamedResource,
+  JikanResourcePeriod,
+  JikanResourceRelation,
+  JikanResourceTitle,
+  JikanUniqueResource,
+} from '../Common';
+import { AnimeYoutubeVideo } from './anime-video.model';
+
+export interface Anime {
+  mal_id: string;
+  url: string;
+  images: JikanImages;
+  trailer: AnimeYoutubeVideo;
+  approved: boolean;
+  titles: JikanResourceTitle[];
+  title: string;
+  title_english: string;
+  title_japanese: string;
+  title_synonyms: string[];
+  type: AnimeType;
+  source: string;
+  episodes: number;
+  status: AnimeStatus;
+  airing: boolean;
+  aired: JikanResourcePeriod;
+  duration: string;
+  rating: AnimeRating;
+  score: number;
+  scored_by: number;
+  rank: number;
+  popularity: number;
+  members: number;
+  favorites: number;
+  synopsis: string;
+  background: string;
+  season?: AnimeSeason;
+  year: number;
+  broadcast: AnimeBroadcast;
+  producers: JikanUniqueResource[];
+  licensors: JikanUniqueResource[];
+  studio: JikanUniqueResource[];
+  genres: JikanUniqueResource[];
+  explicit_genres: JikanUniqueResource[];
+  themes: JikanUniqueResource[];
+  demographic: JikanUniqueResource[];
+  relations?: JikanResourceRelation[];
+  theme?: AnimeTheme;
+  external?: JikanNamedResource[];
+  streaming: JikanNamedResource[];
+}
+
+export interface AnimeBroadcast {
+  day: string;
+  time: string;
+  timezone: string;
+  string: string;
+}
+
+export interface AnimeTheme {
+  openings: string[];
+  endings: string[];
+}
+
+export enum AnimeType {
+  tv = 'TV',
+  movie = 'Movie',
+  ova = 'Ova',
+  special = 'Special',
+  ona = 'Ona',
+  music = 'Music',
+}
+
+export enum AnimeStatus {
+  finished = 'Finished Airing',
+  airing = 'Currently Airing',
+  complete = 'Complete',
+}
+
+export enum AnimeRating {
+  g = 'g',
+  pg = 'pg',
+  pg13 = 'pg13',
+  r17 = 'r17',
+  r = 'r',
+  rx = 'rx',
+}
+
+export enum AnimeSeason {
+  spring = 'spring',
+  summer = 'summer',
+  fall = 'fall',
+  winter = 'winter',
+}

package/src/models/Anime/index.ts

@@ -0,0 +1,7 @@
+export * from './anime.model';
+export * from './anime-character.model';
+export * from './anime-staff.model';
+export * from './anime-episode.model';
+export * from './anime-video.model';
+export * from './anime-picture.model';
+export * from './anime-statistics.model';

package/src/models/Common/character.model.ts

@@ -0,0 +1,18 @@
+import { JikanImages } from './image.model';
+
+export interface CommonCharacter {
+  character: CommonCharacterData;
+  role: CharacterRole;
+}
+
+export interface CommonCharacterData {
+  mal_id: number;
+  url: string;
+  images: JikanImages;
+  name: string;
+}
+
+export enum CharacterRole {
+  main = 'Main',
+  supporting = 'Supporting',
+}

package/src/models/Common/image.model.ts

@@ -0,0 +1,12 @@
+export interface JikanImages {
+  jpg: JikanImagesCollection;
+  webp?: JikanImagesCollection;
+}
+
+export interface JikanImagesCollection {
+  image_url: string;
+  small_image_url?: string;
+  medium_image_url?: string;
+  large_image_url?: string;
+  maximum_image_url?: string;
+}

package/src/models/Common/index.ts

@@ -0,0 +1,6 @@
+export * from './resource.model';
+export * from './image.model';
+export * from './character.model';
+export * from './person.model';
+export * from './recommendation.model';
+export * from './statistics.model';

package/src/models/Common/person.model.ts

@@ -0,0 +1,8 @@
+import { JikanImages } from './image.model';
+
+export interface JikanPerson {
+  mal_id: number;
+  url: string;
+  images: JikanImages;
+  name: string;
+}

package/src/models/Common/recommendation.model.ts

@@ -0,0 +1,12 @@
+import { JikanImages } from './image.model';
+
+export interface Recommendation {
+  entry: RecommendationEntry;
+}
+
+export interface RecommendationEntry {
+  mal_id: number;
+  url: string;
+  images: JikanImages;
+  title: string;
+}

package/src/models/Common/resource.model.ts

@@ -0,0 +1,31 @@
+export interface JikanUniqueResource {
+  mal_id: number;
+  type: string;
+  name: string;
+  url: string;
+}
+
+export interface JikanNamedResource {
+  name: string;
+  url: string;
+}
+
+export interface JikanResourceTitle {
+  type: string;
+  title: string;
+}
+
+export interface JikanResourcePeriod {
+  from: string;
+  to: string;
+  prop: {
+    form: { day: number; month: number; year: number };
+    to: { day: number; month: number; year: number };
+    string: string;
+  };
+}
+
+export interface JikanResourceRelation {
+  relation: string;
+  entry: JikanUniqueResource[];
+}

package/src/models/Common/statistics.model.ts

@@ -0,0 +1,13 @@
+export interface Statistics {
+  completed: number;
+  on_hold: number;
+  dropped: number;
+  total: number;
+  scores: StatisticsScore[];
+}
+
+export interface StatisticsScore {
+  score: number;
+  votes: number;
+  percentage: number;
+}

package/src/models/Manga/index.ts

@@ -0,0 +1,2 @@
+export * from './manga.model';
+export * from './manga-statistics.model';

package/src/models/Manga/manga-statistics.model.ts

@@ -0,0 +1,6 @@
+import { Statistics } from '../Common';
+
+export interface MangaStatistics extends Statistics {
+  reading: number;
+  plan_to_read: number;
+}

package/src/models/Manga/manga.model.ts

@@ -0,0 +1,58 @@
+import {
+  JikanImages,
+  JikanNamedResource,
+  JikanResourcePeriod,
+  JikanResourceRelation,
+  JikanResourceTitle,
+  JikanUniqueResource,
+} from '../Common';
+
+export interface Manga {
+  mal_id: number;
+  url: string;
+  images: JikanImages;
+  approved: boolean;
+  titles: JikanResourceTitle[];
+  title: string;
+  title_japanese: string;
+  title_synonyms?: string[];
+  type: MangaType;
+  chapters: number;
+  volumes: number;
+  status: MangaStatus;
+  publishing: boolean;
+  published: JikanResourcePeriod;
+  score: number;
+  scored_by: number;
+  rank: number;
+  popularity: number;
+  members: number;
+  favorites: number;
+  synopsis: string;
+  background: string;
+  authors: JikanUniqueResource[];
+  serializations: JikanUniqueResource[];
+  explicit_genres: JikanUniqueResource[];
+  themes: JikanUniqueResource[];
+  demographics: JikanUniqueResource[];
+  relations?: JikanResourceRelation[];
+  external?: JikanNamedResource[];
+}
+
+export enum MangaType {
+  manga = 'Manga',
+  novel = 'Novel',
+  lightnovel = 'Lightnovel',
+  oneshot = 'Oneshot',
+  doujin = 'Doujin',
+  manwha = 'Manwha',
+  manhua = 'Manhua',
+}
+
+export enum MangaStatus {
+  publishing = 'Publishing',
+  complete = 'Complete',
+  hiatus = 'Hiatus',
+  discontinued = 'Discontinued',
+  upcoming = 'Upcoming',
+}

package/src/models/Params/index.ts

@@ -0,0 +1,2 @@
+export * from './search-params.model';
+export * from './top-params.model';