From 24492f28efc2aa7682b82171c808cd058db76943 Mon Sep 17 00:00:00 2001 From: Prantadas Date: Sat, 24 Aug 2024 20:36:34 +0600 Subject: [PATCH] feat: docs string provided for the api methods --- package.json | 16 ++++++-- src/apis/audio.ts | 94 +++++++++++++++++++++++++++++++++++++++++++- src/apis/chapter.ts | 26 ++++++++++++ src/apis/juz.ts | 8 ++++ src/apis/quran.ts | 76 +++++++++++++++++++++++++++++++++++ src/apis/resource.ts | 76 ++++++++++++++++++++++++++++++++++- src/apis/verse.ts | 62 +++++++++++++++++++++++++++++ src/req.ts | 9 +++++ src/utils.ts | 14 +++++++ 9 files changed, 376 insertions(+), 5 deletions(-) diff --git a/package.json b/package.json index ee8f18d..468a6fd 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "al-quran-api", + "name": "al-quran-js", "version": "1.0.0", "description": "An API wrapper for Quran on top of quran.com", "main": "./dist/index.js", @@ -20,7 +20,17 @@ "test": "jest", "start": "ts-node src/index.ts" }, - "keywords": [], + "keywords": [ + "al-quran", + "api", + "quran", + "quran.com", + "al-quran-api", + "verse", + "ayah", + "juz", + "quran-js" + ], "files": [ "dist", "README.md", @@ -47,4 +57,4 @@ "agentkeepalive": "^4.5.0", "axios": "^1.7.2" } -} +} \ No newline at end of file diff --git a/src/apis/audio.ts b/src/apis/audio.ts index b72cb1c..5e85801 100644 --- a/src/apis/audio.ts +++ b/src/apis/audio.ts @@ -15,6 +15,14 @@ const api = Api(); export const audio: AudioApi = { + /** + * Retrieves audio recordings of a specific chapter by a particular reciter. + * + * @param id - The ID of the reciter. + * @param chapter_number - The number of the chapter. + * @returns A promise that resolves to the audio recordings or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/chapter-reciter-audio-file} + */ getChaptersAudioOfAReciter(id: number, chapter_number: number): Promise { if (!id || !chapter_number) return Promise.reject(new Error('Reciter\'s ID and Chapter number is required')); @@ -26,6 +34,13 @@ export const audio: AudioApi = { }); }, + /** + * Retrieves all audio recordings for a specific reciter. + * + * @param id - The ID of the reciter. + * @returns A promise that resolves to the list of audio recordings or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/chapter-reciter-audio-files} + */ getAllChaptersAudioOfAReciter(id: number): Promise { if (!id) return Promise.reject(new Error('Reciter\'s ID is required')); @@ -37,7 +52,13 @@ export const audio: AudioApi = { }); }, - + /** + * Retrieves a list of recitations available in the specified language. + * + * @param language - The language code. Defaults to 'en'. + * @returns A promise that resolves to the list of recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/recitations} + */ getRecitations(language: string = 'en'): Promise { const isLanguageSupported = ALLOWED_LANGUAGES.has(language); if (!isLanguageSupported) return Promise.reject(new Error("Provided language is not supported")); @@ -48,6 +69,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves all audio files for a specific recitation, optionally filtered by query parameters. + * + * @param recitation_id - The ID of the recitation. + * @param query - Optional query parameters to filter the audio files. + * @returns A promise that resolves to the list of audio files or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/recitation-autio-files} + */ getAllAudioFilesofARecitation(recitation_id: number, query?: AudioQueryParams): Promise { if (!recitation_id) return Promise.reject(new Error('recitation_id is required')); let uri = `/quran/recitations/${recitation_id}`; @@ -61,6 +91,14 @@ export const audio: AudioApi = { }, + + /** + * Retrieves a list of chapter reciters available in the specified language. + * + * @param language - The language code. Defaults to 'en'. + * @returns A promise that resolves to the list of chapter reciters or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/chapter-reciters} + */ getListOfChapterReciters(language: string = 'en'): Promise { const isLanguageSupported = ALLOWED_LANGUAGES.has(language); if (!isLanguageSupported) return Promise.reject(new Error("Provided language is not supported")); @@ -71,6 +109,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific chapter by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param chapter_number - The number of the chapter. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-surah-recitation} + */ getAyahRecitationsForSpecificSurah(recitation_id: number, chapter_number: number): Promise { if (!recitation_id || !chapter_number) return Promise.reject(new Error('recitation_id and Chapter number is required')); @@ -81,6 +128,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific Juz by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param juz_number - The number of the Juz. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-juz-recitaiton} + */ getAyahRecitationsForSpecificJuz(recitation_id: number, juz_number: number): Promise { if (!recitation_id || !juz_number) return Promise.reject(new Error('recitation_id and juz_number is required')); @@ -91,6 +147,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific Madani Mushaf page by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param page_number - The number of the Madani Mushaf page. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-page-recitaiton} + */ getAyahRecitationForSpecificMadaniMushafPage(recitation_id: number, page_number: number): Promise { if (!recitation_id || !page_number) return Promise.reject(new Error('recitation_id and Page number is required')); @@ -101,6 +166,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific Rub El Hizb by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param rub_el_hizb_number - The number of the Rub El Hizb. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-rub-el-hizb-recitaiton} + */ getAyahRecitationForSpecificRubelHizb(recitation_id: number, rub_el_hizb_number: number): Promise { if (!recitation_id || !rub_el_hizb_number) return Promise.reject(new Error('recitation_id and rub_el_hizb_number is required')); @@ -111,6 +185,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific Hizb by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param hizb_number - The number of the Hizb. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-hizb-recitaiton} + */ getAyahRecitationForSpecificHizb(recitation_id: number, hizb_number: number): Promise { if (!recitation_id || !hizb_number) return Promise.reject(new Error('recitation_id and hizb_number is required')); @@ -121,6 +204,15 @@ export const audio: AudioApi = { }); }, + + /** + * Retrieves audio recitations for a specific Ayah by a particular reciter. + * + * @param recitation_id - The ID of the reciter. + * @param ayah_key - The key of the Ayah. + * @returns A promise that resolves to the audio recitations or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-ayah-recitaiton} + */ getAyahRecitationForSpecificAyah(recitation_id: number, ayah_key: string): Promise { if (!recitation_id || !ayah_key) return Promise.reject(new Error('recitation_id and ayah_key is required')); diff --git a/src/apis/chapter.ts b/src/apis/chapter.ts index 28b7164..4988b79 100644 --- a/src/apis/chapter.ts +++ b/src/apis/chapter.ts @@ -7,6 +7,14 @@ const api = Api(); export const chapter: ChapterApi = { + + /** + * Retrieves a list of all chapters in the Quran. + * + * @param language - The language code for the chapter names. Defaults to 'en'. + * @returns A promise that resolves to the list of chapters or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/list-chapters} + */ listChapters(language = 'en'): Promise { const isLanguageSupported = language && ALLOWED_LANGUAGES.has(language); if (!isLanguageSupported) return Promise.reject(new Error("Provided language is not supported")); @@ -16,6 +24,15 @@ export const chapter: ChapterApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves information about a specific chapter. + * + * @param id - The ID of the chapter to retrieve. + * @param language - The language code for the chapter information. Defaults to 'en'. + * @returns A promise that resolves to the chapter details or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/get-chapter} + */ getChapter(id: number, language = 'en'): Promise { if (language && !ALLOWED_LANGUAGES.has(language)) return Promise.reject(new Error("Provided language is not supported")); return new Promise((resolve, reject) => { @@ -24,6 +41,15 @@ export const chapter: ChapterApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves detailed information about a specific chapter. + * + * @param chapter_id - The ID of the chapter to retrieve information for. + * @param language - The language code for the chapter information. Defaults to 'en'. + * @returns A promise that resolves to the chapter information or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/info} + */ getChapterInfo(chapter_id: number, language = 'en'): Promise { if (language && !ALLOWED_LANGUAGES.has(language)) return Promise.reject(new Error("Provided language is not supported")); return new Promise((resolve, reject) => { diff --git a/src/apis/juz.ts b/src/apis/juz.ts index e7baadf..2c65389 100644 --- a/src/apis/juz.ts +++ b/src/apis/juz.ts @@ -6,6 +6,14 @@ import { handleError, handleResponse } from "../utils"; const api = Api(); export const juz: JuzApi = { + + /** + * Retrieves a list of all Juzs (sections) of the Quran. + * + * @returns A promise that resolves to the list of Juzs or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/juzs} + */ + getAllJuzs(): Promise { return new Promise((resolve, reject) => { api.get('/juzs') diff --git a/src/apis/quran.ts b/src/apis/quran.ts index dc0f01d..0179f34 100644 --- a/src/apis/quran.ts +++ b/src/apis/quran.ts @@ -15,6 +15,14 @@ import { handleError, handleResponse } from "../utils"; const api = Api(); export const quran: QuranApi = { + + /** + * Retrieves the Indo-Pak script of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the Indo-Pak script response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-indopak} + */ getIndoPakScriptOfAyah(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/code_v1?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/code_v1'; return new Promise((resolve, reject) => { @@ -23,6 +31,14 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves the Uthmani Tajweed script of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the Uthmani Tajweed script response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-uthmani-tajweed} + */ getUthmaniTajweedScriptOfAyah(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/uthmani_tajweed?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/uthmani_tajweed'; return new Promise((resolve, reject) => { @@ -31,6 +47,15 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + + /** + * Retrieves the Uthmani script of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the Uthmani script response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-uthmani} + */ getUthmaniScriptOfAyah(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/uthmani?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/uthmani'; return new Promise((resolve, reject) => { @@ -39,6 +64,14 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves the Uthmani simple script of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the Uthmani simple script response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-uthmani-simple} + */ getUthmaniSimpleScriptOfAyah(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/uthmani_simple?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/uthmani_simple'; return new Promise((resolve, reject) => { @@ -47,6 +80,14 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves the Imlaei simple text of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the Imlaei simple text response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-imlaei} + */ getImlaeiSimpleTextOfAyah(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/imlaei?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/imlaei'; return new Promise((resolve, reject) => { @@ -55,6 +96,15 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a single translation of a verse. + * + * @param translation_id - The ID of the translation to retrieve. + * @param query - Optional query parameters to filter the translation. + * @returns A promise that resolves to the single translation response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/translation} + */ getASingleTranslation(translation_id: string, query?: TranslationQuery): Promise { const uri = query ? `/quran/translations/${translation_id}?${new URLSearchParams(query as URLSearchParams)}` : `/quran/translations/${translation_id}`; return new Promise((resolve, reject) => { @@ -63,6 +113,15 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a single tafsir of a verse. + * + * @param tafsir_id - The ID of the tafsir to retrieve. + * @param query - Optional query parameters to filter the tafsir. + * @returns A promise that resolves to the single tafsir response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/tafsir} + */ getSingleTafsir(tafsir_id: string, query?: TranslationQuery): Promise { const uri = query ? `/quran/tafsirs/${tafsir_id}?${new URLSearchParams(query as URLSearchParams)}` : `/quran/tafsirs/${tafsir_id}`; return new Promise((resolve, reject) => { @@ -71,6 +130,15 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a single tafsir of a verse. + * + * @param tafsir_id - The ID of the tafsir to retrieve. + * @param query - Optional query parameters to filter the tafsir. + * @returns A promise that resolves to the single tafsir response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-code-v-1} + */ getGlyphCodesOfAyahV1(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/code_v1?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/code_v1'; return new Promise((resolve, reject) => { @@ -79,6 +147,14 @@ export const quran: QuranApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves the glyph codes (version 2) of a verse. + * + * @param query - Optional query parameters to filter the verses. + * @returns A promise that resolves to the glyph codes response (version 2) or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/quran-verses-code-v-2} + */ getGlyphCodesOfAyahV2(query?: QuranQuery): Promise { const uri = query ? `/quran/verses/code_v2?${new URLSearchParams(query as URLSearchParams)}` : '/quran/verses/code_v2'; return new Promise((resolve, reject) => { diff --git a/src/apis/resource.ts b/src/apis/resource.ts index a186832..3b1d55e 100644 --- a/src/apis/resource.ts +++ b/src/apis/resource.ts @@ -1,12 +1,25 @@ import { AxiosError } from "axios"; import Api from "../req"; -import { ResourceApi, RecitaionInfo, TranslationInfo, TranslationResponse, TafsirsResponse, TafsirInfoResponse, RecitationStyleResponse, LanguageResponse, ChapterInfos, VerseMediaResponse, ALLOWED_LANGUAGES } from "../types"; +import { + ResourceApi, RecitaionInfo, + TranslationInfo, TranslationResponse, TafsirsResponse, + TafsirInfoResponse, RecitationStyleResponse, LanguageResponse, + ChapterInfos, VerseMediaResponse, ALLOWED_LANGUAGES +} from "../types"; import { handleError, handleResponse } from "../utils"; const api = Api(); export const resources: ResourceApi = { + + /** + * Retrieves information about a specific recitation. + * + * @param recitation_id - The ID of the recitation to retrieve information for. + * @returns A promise that resolves to the recitation information or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/recitation-info} + */ getRecitationInfo(recitation_id: string): Promise { if (!recitation_id) return Promise.reject(new Error('Recitation ID is required')); return new Promise((resolve, reject) => { @@ -15,6 +28,14 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves information about a specific translation. + * + * @param translation_id - The ID of the translation to retrieve information for. + * @returns A promise that resolves to the translation information or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/translation-info} + */ getTranslationInfo(translation_id: string): Promise { if (!translation_id) return Promise.reject(new Error('Translation ID is required')); return new Promise((resolve, reject) => { @@ -23,6 +44,14 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a list of translations available in a specific language. + * + * @param language - The language code for the translations to retrieve. Defaults to 'en'. + * @returns A promise that resolves to the translation response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/translations} + */ getTranslations(language: string = 'en'): Promise { const isLanguageSupported = ALLOWED_LANGUAGES.has(language); if (!isLanguageSupported) return Promise.reject(new Error("Provided language is not supported")); @@ -32,6 +61,14 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a list of tafsirs available in a specific language. + * + * @param language - The language code for the tafsirs to retrieve. Defaults to 'en'. + * @returns A promise that resolves to the tafsirs response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/tafsirs} + */ getTafsirs(language: string = 'en'): Promise { const isLanguageSupported = ALLOWED_LANGUAGES.has(language); if (!isLanguageSupported) return Promise.reject(new Error("Provided language is not supported")); @@ -41,6 +78,14 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves information about a specific tafsir. + * + * @param tafsir_id - The ID of the tafsir to retrieve information for. + * @returns A promise that resolves to the tafsir information or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/tafsir-info} + */ getTafsirInfo(tafsir_id: string): Promise { if (!tafsir_id) return Promise.reject(new Error('Tafsir ID is required')); return new Promise((resolve, reject) => { @@ -49,6 +94,13 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a list of available recitation styles. + * + * @returns A promise that resolves to the recitation style response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/recitation-styles} + */ getRecitationStyles(): Promise { return new Promise((resolve, reject) => { api.get('/resources/recitation_styles') @@ -56,6 +108,14 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + + /** + * Retrieves a list of supported languages. + * + * @returns A promise that resolves to the language response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/languages} + */ getLanguages(): Promise { return new Promise((resolve, reject) => { api.get('/resources/languages') @@ -63,6 +123,13 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves information about all chapters in the Quran. + * + * @returns A promise that resolves to the chapter information or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/chapter-info} + */ getChapterInfos(): Promise { return new Promise((resolve, reject) => { api.get(`/resources/chapter_infos`) @@ -70,6 +137,13 @@ export const resources: ResourceApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves media related to verses in the Quran. + * + * @returns A promise that resolves to the verse media response or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verse-media} + */ getVerseMedias(): Promise { return new Promise((resolve, reject) => { api.get(`/resources/verse_media`) diff --git a/src/apis/verse.ts b/src/apis/verse.ts index ecb35dc..1b60a07 100644 --- a/src/apis/verse.ts +++ b/src/apis/verse.ts @@ -6,6 +6,15 @@ import { handleError, handleResponse } from "../utils"; const api = Api(); export const verse: VerseApi = { + + /** + * Retrieves verses from a specific chapter of the Quran. + * + * @param chapter_number - The number of the chapter to retrieve verses from. + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verses or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-chapter-number} + */ getVerseByChapter(chapter_number: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_chapter/${chapter_number}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_chapter/${chapter_number}`; @@ -15,6 +24,15 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves verses from a specific page of the Quran. + * + * @param page_number - The number of the page to retrieve verses from. + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verses or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-page-number} + */ getVerseByPage(page_number: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_page/${page_number}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_page/${page_number}`; @@ -24,6 +42,15 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves verses from a specific juz (section) of the Quran. + * + * @param juz_number - The number of the juz to retrieve verses from. + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verses or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-juz-number} + */ getVerseByJuz(juz_number: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_juz/${juz_number}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_juz/${juz_number}`; @@ -33,6 +60,15 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves verses from a specific hizb (half of a juz) of the Quran. + * + * @param hizb_number - The number of the hizb to retrieve verses from. + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verses or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-hizb-number} + */ getVerseByHizbNumber(hizb_number: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_hizb/${hizb_number}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_hizb/${hizb_number}`; @@ -42,6 +78,15 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves verses from a specific rub' el-hizb (quarter of a hizb) of the Quran. + * + * @param rub_el_hizb_number - The number of the rub' el-hizb to retrieve verses from. + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verses or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-rub-el-hizb-number} + */ getVerseByRubElHizbNumber(rub_el_hizb_number: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_rub/${rub_el_hizb_number}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_rub/${rub_el_hizb_number}`; @@ -51,6 +96,15 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a specific verse using a verse key. + * + * @param verse_key - The key of the verse to retrieve (usually in the format "chapter:verse"). + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing the verse or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/verses-by-verse-key} + */ getSpecificVerseByVerseKey(verse_key: string, query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/by_key/${verse_key}?${new URLSearchParams(query as URLSearchParams)}` : `/verses/by_key/${verse_key}`; @@ -60,6 +114,14 @@ export const verse: VerseApi = { .catch(handleError(reject)); }); }, + + /** + * Retrieves a random verse (ayah) from the Quran. + * + * @param query - Optional query parameters for the request, including language. + * @returns A promise that resolves to the response containing a random verse or rejects with an error. + * @see {@link https://api-docs.quran.com/docs/quran.com_versioned/random-verse} + */ getRandomAyah(query?: VerseQuery): Promise { if (query?.language && !ALLOWED_LANGUAGES.has(query.language)) throw new Error('Provided query language is not allowed'); const uri = query ? `/verses/random?${new URLSearchParams(query as URLSearchParams)}` : `/verses/random`; diff --git a/src/req.ts b/src/req.ts index ce76db2..9b13c0a 100644 --- a/src/req.ts +++ b/src/req.ts @@ -4,6 +4,15 @@ import config from "./config"; import { CustomHeaders } from "./types"; + +/** + * Creates an Axios instance with custom configuration for making HTTP requests. + * + * @param baseURL - The base URL for the API requests. Defaults to `config.API_BASE_URL`. + * @param token - An optional authorization token to be included in the headers of each request. + * @param customHeaders - An object representing custom headers to be included in each request. Defaults to an empty object. + * @returns An Axios instance configured with the specified parameters. + */ const Api = ( baseURL: string = config.API_BASE_URL, token?: string, diff --git a/src/utils.ts b/src/utils.ts index fa155c2..a1a9705 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -1,9 +1,23 @@ import { AxiosError, AxiosResponse } from 'axios'; +/** + * Handles the response from an Axios request. + * + * @template T - The type of the response data. + * @param resolve - The function to call to resolve the promise with the response data. + * @returns A function that takes an Axios response and resolves the promise with the response data. + */ export const handleResponse = ( resolve: (value: T) => void) => (response: AxiosResponse) => resolve(response.data); + +/** + * Handles an error from an Axios request. + * + * @param reject - The function to call to reject the promise with the error. + * @returns A function that takes an Axios error and rejects the promise with the error. + */ export const handleError = (reject: (reason: Error | AxiosError) => void) => (error: AxiosError) => reject(error); \ No newline at end of file