@quranjs/api 1.0.1

package/src/sdk/v4/audio.ts

@@ -0,0 +1,266 @@
+import {
+  ChapterRecitation,
+  VerseRecitation,
+  ChapterId,
+  HizbNumber,
+  JuzNumber,
+  Language,
+  PageNumber,
+  Pagination,
+  RubNumber,
+  VerseKey,
+  VerseRecitationField,
+} from '@/types';
+import { decamelize } from 'humps';
+import Utils from '../utils';
+import { fetcher } from './_fetcher';
+
+type GetChapterRecitationsOptions = Partial<{
+  language: Language;
+}>;
+
+const defaultChapterRecitationsOptions: GetChapterRecitationsOptions = {
+  language: Language.ARABIC,
+};
+
+const getChapterRecitationsOptions = (
+  options: GetChapterRecitationsOptions = {}
+) => {
+  const final: any = { ...defaultChapterRecitationsOptions, ...options };
+
+  return final;
+};
+
+type GetVerseRecitationsOptions = Partial<{
+  language: Language;
+  fields: Partial<Record<VerseRecitationField, boolean>>;
+}>;
+
+const defaultVerseRecitationsOptions: GetVerseRecitationsOptions = {
+  language: Language.ARABIC,
+};
+
+const getVerseRecitationsOptions = (
+  options: GetVerseRecitationsOptions = {}
+) => {
+  const initial = { ...defaultVerseRecitationsOptions, ...options };
+  const final: any = { language: initial.language };
+
+  if (initial.fields) {
+    const fields: string[] = [];
+    for (const [key, value] of Object.entries(initial.fields)) {
+      if (value) fields.push(decamelize(key));
+    }
+    final.fields = fields.join(',');
+  }
+
+  return final;
+};
+
+/**
+ * Get all chapter recitations for specific reciter
+ * @description https://quran.api-docs.io/v4/audio-recitations/list-of-all-surah-audio-files-for-specific-reciter
+ * @param {string} reciterId
+ * @param {GetChapterRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findAllChapterRecitations('2')
+ */
+const findAllChapterRecitations = async (
+  reciterId: string,
+  options?: GetChapterRecitationsOptions
+) => {
+  const params = getChapterRecitationsOptions(options);
+  const { audioFiles } = await fetcher<{ audioFiles: ChapterRecitation[] }>(
+    `/chapter_recitations/${reciterId}`,
+    params
+  );
+  return audioFiles;
+};
+
+/**
+ * Get chapter recitation for specific reciter and a specific chapter
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-single-surah-audio-for-specific-reciter
+ * @param {ChapterId} chapterId
+ * @param {string} reciterId
+ * @param {GetChapterRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findChapterRecitationById('1', '2') // first chapter recitation for reciter 2
+ */
+const findChapterRecitationById = async (
+  chapterId: ChapterId,
+  reciterId: string,
+  options?: GetChapterRecitationsOptions
+) => {
+  if (!Utils.isValidChapterId(chapterId)) throw new Error('Invalid chapter id');
+
+  const params = getChapterRecitationsOptions(options);
+  const { audioFile } = await fetcher<{ audioFile: ChapterRecitation }>(
+    `/chapter_recitations/${reciterId}/${chapterId}`,
+    params
+  );
+
+  return audioFile;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific chapter
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-surah
+ * @param {ChapterId} chapterId
+ * @param {string} recitationId
+ * @param {GetVerseRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByChapter('1', '2')
+ */
+const findVerseRecitationsByChapter = async (
+  chapterId: ChapterId,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidChapterId(chapterId)) throw new Error('Invalid chapter id');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_chapter/${chapterId}`, params);
+
+  return data;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific juz
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-juz
+ * @param {JuzNumber} juz
+ * @param {string} recitationId
+ * @param {GetRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByJuz('1', '2')
+ */
+const findVerseRecitationsByJuz = async (
+  juz: JuzNumber,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidJuz(juz)) throw new Error('Invalid juz');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_juz/${juz}`, params);
+
+  return data;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific mushaf page
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-madani-mushaf-page
+ * @param {PageNumber} page
+ * @param {string} recitationId
+ * @param {GetVerseRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByPage('1', '2')
+ */
+const findVerseRecitationsByPage = async (
+  page: PageNumber,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidQuranPage(page)) throw new Error('Invalid page');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_page/${page}`, params);
+
+  return data;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific rub
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-rub
+ * @param {RubNumber} rub
+ * @param {string} recitationId
+ * @param {GetVerseRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByRub('1', '2')
+ */
+const findVerseRecitationsByRub = async (
+  rub: RubNumber,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidRub(rub)) throw new Error('Invalid rub');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_rub/${rub}`, params);
+
+  return data;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific hizb
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-hizb
+ * @param {HizbNumber} hizb
+ * @param {string} recitationId
+ * @param {GetVerseRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByHizb('1', '2')
+ */
+const findVerseRecitationsByHizb = async (
+  hizb: HizbNumber,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidHizb(hizb)) throw new Error('Invalid hizb');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_hizb/${hizb}`, params);
+
+  return data;
+};
+
+/**
+ * Get all verse audio files for a specific reciter and a specific hizb
+ * @description https://quran.api-docs.io/v4/audio-recitations/get-ayah-recitations-for-specific-ayah
+ * @param {VerseKey} key
+ * @param {string} recitationId
+ * @param {GetVerseRecitationsOptions} options
+ * @example
+ * quran.v4.audio.findVerseRecitationsByKey('1:1', '2')
+ */
+const findVerseRecitationsByKey = async (
+  key: VerseKey,
+  recitationId: string,
+  options?: GetVerseRecitationsOptions
+) => {
+  if (!Utils.isValidVerseKey(key)) throw new Error('Invalid verse key');
+
+  const params = getVerseRecitationsOptions(options);
+  const data = await fetcher<{
+    audioFiles: VerseRecitation[];
+    pagination: Pagination;
+  }>(`/recitations/${recitationId}/by_ayah/${key}`, params);
+
+  return data;
+};
+
+const audio = {
+  findAllChapterRecitations,
+  findChapterRecitationById,
+  findVerseRecitationsByChapter,
+  findVerseRecitationsByJuz,
+  findVerseRecitationsByPage,
+  findVerseRecitationsByRub,
+  findVerseRecitationsByHizb,
+  findVerseRecitationsByKey,
+};
+
+export default audio;

package/src/sdk/v4/chapters.ts

@@ -0,0 +1,83 @@
+import { Chapter, ChapterId, ChapterInfo, Language } from '@/types';
+import { fetcher } from './_fetcher';
+import Utils from '../utils';
+
+type Options = Partial<{
+  language: Language;
+}>;
+
+const defaultOptions: Options = {
+  language: Language.ARABIC,
+};
+
+const getChapterOptions = (options: Options = {}) => {
+  const final: any = { ...defaultOptions, ...options };
+  return final;
+};
+
+/**
+ * Get all chapters.
+ * @description https://quran.api-docs.io/v4/chapters/list-chapters
+ * @param {Options} options
+ * @example
+ * quran.v4.chapters.findAll()
+ */
+const findAll = async (options?: Options) => {
+  const params = getChapterOptions(options);
+  const { chapters } = await fetcher<{ chapters: Chapter[] }>(
+    '/chapters',
+    params
+  );
+
+  return chapters;
+};
+
+/**
+ * Get chapter by id.
+ * @description https://quran.api-docs.io/v4/chapters/get-chapter
+ * @param {ChapterId} id chapter id, minimum 1, maximum 114
+ * @param {Options} options
+ * @example
+ * quran.v4.chapters.findById('1')
+ * quran.v4.chapters.findById('114')
+ */
+const findById = async (id: ChapterId, options?: Options) => {
+  if (!Utils.isValidChapterId(id)) throw new Error('Invalid chapter id');
+
+  const params = getChapterOptions(options);
+  const { chapter } = await fetcher<{ chapter: Chapter }>(
+    `/chapters/${id}`,
+    params
+  );
+
+  return chapter;
+};
+
+/**
+ * Get chapter info by id.
+ * @description https://quran.api-docs.io/v4/chapters/chapter_info
+ * @param {ChapterId} id chapter id, minimum 1, maximum 114
+ * @param {Options} options
+ * @example
+ * quran.v4.chapters.findInfoById('1')
+ * quran.v4.chapters.findInfoById('114')
+ */
+const findInfoById = async (id: ChapterId, options?: Options) => {
+  if (!Utils.isValidChapterId(id)) throw new Error('Invalid chapter id');
+
+  const params = getChapterOptions(options);
+  const { chapterInfo } = await fetcher<{ chapterInfo: ChapterInfo }>(
+    `/chapters/${id}/info`,
+    params
+  );
+
+  return chapterInfo;
+};
+
+const chapters = {
+  findAll,
+  findById,
+  findInfoById,
+};
+
+export default chapters;

package/src/sdk/v4/index.ts

@@ -0,0 +1,17 @@
+import chapters from './chapters';
+import verses from './verses';
+import juzs from './juzs';
+import audio from './audio';
+import resources from './resources';
+import search from './search';
+
+const v4 = {
+  chapters,
+  verses,
+  juzs,
+  audio,
+  resources,
+  search,
+};
+
+export default v4;

package/src/sdk/v4/juzs.ts

@@ -0,0 +1,17 @@
+import { Juz } from '@/types';
+import { fetcher } from './_fetcher';
+
+/**
+ * Get All Juzs
+ * @description https://quran.api-docs.io/v4/juz/get-all-juzs
+ * @example
+ * quran.v4.juzs.findAll()
+ */
+const findAll = async () => {
+  const { juzs } = await fetcher<{ juzs: Juz[] }>('/juzs');
+  return juzs;
+};
+
+const juzs = { findAll };
+
+export default juzs;

package/src/sdk/v4/resources.ts

@@ -0,0 +1,224 @@
+import {
+  ChapterInfoResource,
+  ChapterReciterResource,
+  Language,
+  LanguageResource,
+  // RecitationInfoResource,
+  RecitationResource,
+  RecitationStylesResource,
+  // TafsirInfoResource,
+  TafsirResource,
+  // TranslationInfoResource,
+  TranslationResource,
+  VerseMediaResource,
+} from '@/types';
+import { fetcher } from './_fetcher';
+
+type GetResourcesOptions = Partial<{
+  language: Language;
+}>;
+
+const defaultOptions: GetResourcesOptions = {
+  language: Language.ARABIC,
+};
+
+const getResourcesOptions = (options: GetResourcesOptions = {}) => {
+  const final: any = { ...defaultOptions, ...options };
+  return final;
+};
+
+/**
+ * Get all recitations.
+ * @description https://quran.api-docs.io/v4/resources/recitations
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllRecitations()
+ */
+const findAllRecitations = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { recitations } = await fetcher<{
+    recitations: RecitationResource[];
+  }>('/resources/recitations', params);
+
+  return recitations;
+};
+
+// TODO: uncomment when API is ready
+/**
+ * Get all recitation info.
+ * @description https://quran.api-docs.io/v4/resources/recitation-info
+ * @param {string} id recitation id
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findRecitationInfo('1')
+ */
+// const findRecitationInfo = async (id: string, options?: GetResourcesOptions) => {
+//   const params = getResourcesOptions(options);
+//   const { info } = await fetcher<{
+//     info: RecitationInfoResource;
+//   }>(`/resources/recitations/${id}/info`, params);
+
+//   return info;
+// };
+
+/**
+ * Get all translations.
+ * @description https://quran.api-docs.io/v4/resources/translations
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllTranslations()
+ */
+const findAllTranslations = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { translations } = await fetcher<{
+    translations: TranslationResource[];
+  }>('/resources/translations', params);
+
+  return translations;
+};
+
+// TODO: uncomment when API is ready
+/**
+ * Get translation info.
+ * @description https://quran.api-docs.io/v4/resources/translation-info
+ * @param {string} id translation id
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findTranslationInfo('169')
+ */
+// const findTranslationInfo = async (id: string, options?: GetResourcesOptions) => {
+//   const params = getResourcesOptions(options);
+//   const { info } = await fetcher<{
+//     info: TranslationInfoResource;
+//   }>(`/resources/translations/${id}/info`, params);
+
+//   return info;
+// };
+
+/**
+ * Get all tafsirs.
+ * @description https://quran.api-docs.io/v4/resources/tafsirs
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllTafsirs()
+ */
+const findAllTafsirs = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { tafsirs } = await fetcher<{
+    tafsirs: TafsirResource[];
+  }>('/resources/tafsirs', params);
+
+  return tafsirs;
+};
+
+// TODO: uncomment when API is ready
+/**
+ * Get tafsir info.
+ * @description https://quran.api-docs.io/v4/resources/tafsirs-info
+ * @param {string} id tafsir id
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findTranslationInfo('1')
+ */
+// const findTafsirInfo = async (id: string, options?: GetResourcesOptions) => {
+//   const params = getResourcesOptions(options);
+//   const { info } = await fetcher<{
+//     info: TafsirInfoResource;
+//   }>(`/resources/tafsirs/${id}/info`, params);
+
+//   return info;
+// };
+
+/**
+ * Get all recitation styles.
+ * @description https://quran.api-docs.io/v4/resources/recitation-styles
+ * @example
+ * quran.v4.resources.findAllRecitationStyles()
+ */
+const findAllRecitationStyles = async () => {
+  const { recitationStyles } = await fetcher<{
+    recitationStyles: RecitationStylesResource;
+  }>('/resources/recitation_styles');
+
+  return recitationStyles;
+};
+
+/**
+ * Get all languages.
+ * @description https://quran.api-docs.io/v4/resources/languages
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllLanguages()
+ */
+const findAllLanguages = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { languages } = await fetcher<{
+    languages: LanguageResource[];
+  }>('/resources/languages', params);
+
+  return languages;
+};
+
+/**
+ * Get all chapter infos.
+ * @description https://quran.api-docs.io/v4/resources/chapter-info
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllChapterInfos()
+ */
+const findAllChapterInfos = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { chapterInfos } = await fetcher<{
+    chapterInfos: ChapterInfoResource[];
+  }>('/resources/chapter_infos', params);
+
+  return chapterInfos;
+};
+
+/**
+ * Get verse media.
+ * @description https://quran.api-docs.io/v4/resources/verse_media
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findVerseMedia()
+ */
+const findVerseMedia = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { verseMedia } = await fetcher<{
+    verseMedia: VerseMediaResource;
+  }>(`/resources/verse_media`, params);
+
+  return verseMedia;
+};
+
+/**
+ * Get all chapter reciters.
+ * @description https://quran.api-docs.io/v4/resources/list-of-chapter-reciters
+ * @param {GetResourcesOptions} options
+ * @example
+ * quran.v4.resources.findAllChapterReciters()
+ */
+const findAllChapterReciters = async (options?: GetResourcesOptions) => {
+  const params = getResourcesOptions(options);
+  const { reciters } = await fetcher<{
+    reciters: ChapterReciterResource[];
+  }>(`/resources/chapter_reciters`, params);
+
+  return reciters;
+};
+
+const resources = {
+  findAllRecitations,
+  findAllTranslations,
+  findAllTafsirs,
+  findAllRecitationStyles,
+  findAllLanguages,
+  findVerseMedia,
+  findAllChapterReciters,
+  findAllChapterInfos,
+  // findRecitationInfo
+  // findTranslationInfo
+  // findTafsirInfo
+};
+
+export default resources;

package/src/sdk/v4/search.ts

@@ -0,0 +1,40 @@
+import { Language, SearchResponse } from '@/types';
+import { fetcher } from './_fetcher';
+
+type SearchOptions = Partial<{
+  language: Language;
+  size: number;
+  page: number;
+}>;
+
+const defaultSearchOptions: SearchOptions = {
+  language: Language.ARABIC,
+  size: 30,
+};
+
+const getSearchOptions = (q: string, options: SearchOptions = {}) => {
+  const all = { ...defaultSearchOptions, ...options, q };
+  return all;
+};
+
+/**
+ * Search
+ * @description https://quran.api-docs.io/v4/search/KfCmk4KQYbtyK9adj
+ * @param q search query
+ * @param options search options
+ * @example
+ * quran.v4.search.search('الله')
+ * quran.v4.search.search('الله', { language: Language.ENGLISH })
+ * quran.v4.search.search('الله', { language: Language.ENGLISH, size: 10 })
+ * quran.v4.search.search('الله', { language: Language.ENGLISH, page: 2 })
+ */
+const search = async (q: string, options?: SearchOptions) => {
+  const params = getSearchOptions(q, options);
+  const { search } = await fetcher<SearchResponse>('/search', params);
+
+  return search;
+};
+
+const searchApi = { search };
+
+export default searchApi;