@quranjs/api 3.1.0 → 3.2.0

package/dist/{verses-DnPcyHIi.d.ts → verses-B5K9Egsa.d.ts}

@@ -251,6 +251,76 @@ interface Chapter {
     translatedName: TranslatedName;
 }
 
+interface RecitationResource {
+    id?: number;
+    reciterName?: string;
+    style?: string;
+    translatedName?: TranslatedName;
+}
+interface RecitationInfoResource {
+    id?: number;
+    info?: string;
+}
+interface TranslationResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface TranslationInfoResource {
+    id?: number;
+    info?: string;
+}
+interface TafsirResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface TafsirInfoResource {
+    id?: number;
+    info?: string;
+}
+interface RecitationStylesResource {
+    mujawwad: string;
+    murattal: string;
+    muallim: string;
+}
+interface LanguageResource {
+    id?: number;
+    name?: string;
+    nativeName?: string;
+    isoCode?: string;
+    direction?: string;
+    translatedNames?: TranslatedName[];
+}
+interface ChapterInfoResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface VerseMediaResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    languageName?: string;
+}
+interface ChapterReciterResource {
+    id: number;
+    name: string;
+    arabicName?: string;
+    relativePath?: string;
+    format?: string;
+    filesSize?: number;
+}
+
 interface ChapterInfo {
     id: number;
     chapterId: number;
@@ -258,8 +328,63 @@ interface ChapterInfo {
     shortText: string;
     source: string;
     languageName?: string;
+    resourceId?: number;
+}
+interface ChapterInfoResponse {
+    chapterInfo: ChapterInfo | null;
+    resources?: ChapterInfoResource[];
 }
 
+interface HadithReference {
+    id: number;
+    collection: string;
+    hadithNumber: string;
+    ourHadithNumber: number;
+    arabicUrn: number;
+    englishUrn: number;
+    surahNumber: number;
+    ayahStartNumber: number;
+    ayahEndNumber: number;
+}
+interface HadithReferencesByAyahResponse {
+    verseKey: VerseKey;
+    verseNumber: number;
+    chapterNumber: number;
+    language: string;
+    direction: string;
+    hadithReferences: HadithReference[];
+}
+interface HadithGrade {
+    gradedBy?: string;
+    grade?: string;
+}
+interface HadithContent {
+    lang: string;
+    chapterNumber: string;
+    chapterTitle: string;
+    body: string;
+    urn: number;
+    grades: HadithGrade[];
+}
+interface Hadith {
+    urn: number;
+    collection: string;
+    bookNumber: string;
+    chapterId: string;
+    hadithNumber: string;
+    name: string;
+    hadith: HadithContent[];
+}
+interface HadithsByAyahResponse {
+    hadiths: Hadith[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+    language: string;
+    direction: string;
+}
+type HadithCountWithinRangeResponse = Record<string, number>;
+
 interface Tafsir {
     id?: number;
     resourceId?: number;
@@ -369,76 +494,6 @@ interface Pagination {
     totalRecords: number;
 }
 
-interface RecitationResource {
-    id?: number;
-    reciterName?: string;
-    style?: string;
-    translatedName?: TranslatedName;
-}
-interface RecitationInfoResource {
-    id?: number;
-    info?: string;
-}
-interface TranslationResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface TranslationInfoResource {
-    id?: number;
-    info?: string;
-}
-interface TafsirResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface TafsirInfoResource {
-    id?: number;
-    info?: string;
-}
-interface RecitationStylesResource {
-    mujawwad: string;
-    murattal: string;
-    muallim: string;
-}
-interface LanguageResource {
-    id?: number;
-    name?: string;
-    nativeName?: string;
-    isoCode?: string;
-    direction?: string;
-    translatedNames?: TranslatedName[];
-}
-interface ChapterInfoResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface VerseMediaResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    languageName?: string;
-}
-interface ChapterReciterResource {
-    id: number;
-    name: string;
-    arabicName?: string;
-    relativePath?: string;
-    format?: string;
-    filesSize?: number;
-}
-
 type GetChapterRecitationOptions = BaseApiParams;
 type GetVerseRecitationOptions = BaseApiParams & {
     fields?: Partial<Record<VerseRecitationField, boolean>>;
@@ -493,6 +548,10 @@ declare class QuranAudio {
 }
 
 type GetChapterOptions = BaseApiParams;
+type GetChapterInfoOptions = BaseApiParams & {
+    resourceId?: string | number;
+    includeResources?: boolean;
+};
 /**
  * Chapters API methods
  */
@@ -521,12 +580,61 @@ declare class QuranChapters {
      * Get chapter info by id.
      * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
      * @param {ChapterId} id chapter id, minimum 1, maximum 114
-     * @param {GetChapterOptions} options
+     * @param {GetChapterInfoOptions} options
      * @example
      * client.chapters.findInfoById('1')
      * client.chapters.findInfoById('114')
      */
-    findInfoById(id: ChapterId, options?: GetChapterOptions): Promise<ChapterInfo>;
+    findInfoById(id: ChapterId, options?: GetChapterInfoOptions): Promise<ChapterInfo | null>;
+    /**
+     * Get the full chapter info response, including available resources when requested.
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
+     * @param {ChapterId} id chapter id, minimum 1, maximum 114
+     * @param {GetChapterInfoOptions} options
+     * @example
+     * client.chapters.findInfoResponseById('1', { includeResources: true })
+     * client.chapters.findInfoResponseById('1', { resourceId: 'en-tafsir-ibn-ashur' })
+     */
+    findInfoResponseById(id: ChapterId, options?: GetChapterInfoOptions): Promise<ChapterInfoResponse>;
+}
+
+type GetHadithReferenceOptions = BaseApiParams;
+type GetHadithsByAyahOptions = BaseApiParams & {
+    page?: number;
+    limit?: number;
+};
+type CountHadithsWithinRangeOptions = BaseApiParams;
+/**
+ * Hadith reference API methods.
+ */
+declare class QuranHadithReferences {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get ordered hadith reference records linked to a specific ayah.
+     * @param {VerseKey} key verse key in format "chapter:verse" (e.g., "12:12")
+     * @param {GetHadithReferenceOptions} options
+     * @example
+     * client.hadithReferences.findByAyah("12:12")
+     */
+    findByAyah(key: VerseKey, options?: GetHadithReferenceOptions): Promise<HadithReferencesByAyahResponse>;
+    /**
+     * Get paginated hadith payloads linked to a specific ayah.
+     * @param {VerseKey} key verse key in format "chapter:verse" (e.g., "12:12")
+     * @param {GetHadithsByAyahOptions} options
+     * @example
+     * client.hadithReferences.findHadithsByAyah("12:12", { limit: 4 })
+     */
+    findHadithsByAyah(key: VerseKey, options?: GetHadithsByAyahOptions): Promise<HadithsByAyahResponse>;
+    /**
+     * Get a verse-key to hadith-count map within an inclusive ayah range.
+     * @param {VerseKey} from start verse key in format "chapter:verse"
+     * @param {VerseKey} to end verse key in format "chapter:verse"
+     * @param {CountHadithsWithinRangeOptions} options
+     * @example
+     * client.hadithReferences.countWithinRange("12:12", "12:13")
+     */
+    countWithinRange(from: VerseKey, to: VerseKey, options?: CountHadithsWithinRangeOptions): Promise<HadithCountWithinRangeResponse>;
 }
 
 /**
@@ -736,4 +844,4 @@ declare class QuranVerses {
     findRandom(options?: GetVerseOptions): Promise<Verse>;
 }
 
-export { type AudioResponse as A, type ChapterReciterResource as B, type ChapterId as C, SearchNavigationType as D, type SearchResult as E, type HizbNumber as H, type JuzNumber as J, type LanguageResource as L, type NormalizedVerseRecitation as N, type PageNumber as P, QuranChapters as Q, type RubNumber as R, type SearchResponse as S, type TranslatedName as T, type VerseKey as V, type Word as W, QuranVerses as a, QuranJuzs as b, QuranAudio as c, QuranResources as d, QuranSearch as e, type ChapterRecitation as f, type VerseRecitation as g, type Chapter as h, type ChapterInfo as i, type Segment as j, type Tafsir as k, type Translation as l, type Transliteration as m, type Verse as n, CharType as o, type Juz as p, type Pagination as q, type RecitationResource as r, type RecitationInfoResource as s, type TranslationResource as t, type TranslationInfoResource as u, type TafsirResource as v, type TafsirInfoResource as w, type RecitationStylesResource as x, type ChapterInfoResource as y, type VerseMediaResource as z };
+export { type AudioResponse as A, type RecitationResource as B, type ChapterId as C, type RecitationInfoResource as D, type TranslationResource as E, type TranslationInfoResource as F, type TafsirResource as G, type HizbNumber as H, type TafsirInfoResource as I, type JuzNumber as J, type RecitationStylesResource as K, type LanguageResource as L, type ChapterInfoResource as M, type NormalizedVerseRecitation as N, type VerseMediaResource as O, type PageNumber as P, QuranChapters as Q, type RubNumber as R, type SearchResponse as S, type TranslatedName as T, type ChapterReciterResource as U, type VerseKey as V, type Word as W, SearchNavigationType as X, type SearchResult as Y, QuranVerses as a, QuranJuzs as b, QuranAudio as c, QuranHadithReferences as d, QuranResources as e, QuranSearch as f, type ChapterRecitation as g, type VerseRecitation as h, type Chapter as i, type ChapterInfo as j, type ChapterInfoResponse as k, type HadithReference as l, type HadithReferencesByAyahResponse as m, type HadithGrade as n, type HadithContent as o, type Hadith as p, type HadithsByAyahResponse as q, type HadithCountWithinRangeResponse as r, type Segment as s, type Tafsir as t, type Translation as u, type Transliteration as v, type Verse as w, CharType as x, type Juz as y, type Pagination as z };

package/dist/{verses-qzAdux2V.d.mts → verses-CFFeqPDX.d.mts}

@@ -251,6 +251,76 @@ interface Chapter {
     translatedName: TranslatedName;
 }
 
+interface RecitationResource {
+    id?: number;
+    reciterName?: string;
+    style?: string;
+    translatedName?: TranslatedName;
+}
+interface RecitationInfoResource {
+    id?: number;
+    info?: string;
+}
+interface TranslationResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface TranslationInfoResource {
+    id?: number;
+    info?: string;
+}
+interface TafsirResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface TafsirInfoResource {
+    id?: number;
+    info?: string;
+}
+interface RecitationStylesResource {
+    mujawwad: string;
+    murattal: string;
+    muallim: string;
+}
+interface LanguageResource {
+    id?: number;
+    name?: string;
+    nativeName?: string;
+    isoCode?: string;
+    direction?: string;
+    translatedNames?: TranslatedName[];
+}
+interface ChapterInfoResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName?: TranslatedName;
+}
+interface VerseMediaResource {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    languageName?: string;
+}
+interface ChapterReciterResource {
+    id: number;
+    name: string;
+    arabicName?: string;
+    relativePath?: string;
+    format?: string;
+    filesSize?: number;
+}
+
 interface ChapterInfo {
     id: number;
     chapterId: number;
@@ -258,8 +328,63 @@ interface ChapterInfo {
     shortText: string;
     source: string;
     languageName?: string;
+    resourceId?: number;
+}
+interface ChapterInfoResponse {
+    chapterInfo: ChapterInfo | null;
+    resources?: ChapterInfoResource[];
 }
 
+interface HadithReference {
+    id: number;
+    collection: string;
+    hadithNumber: string;
+    ourHadithNumber: number;
+    arabicUrn: number;
+    englishUrn: number;
+    surahNumber: number;
+    ayahStartNumber: number;
+    ayahEndNumber: number;
+}
+interface HadithReferencesByAyahResponse {
+    verseKey: VerseKey;
+    verseNumber: number;
+    chapterNumber: number;
+    language: string;
+    direction: string;
+    hadithReferences: HadithReference[];
+}
+interface HadithGrade {
+    gradedBy?: string;
+    grade?: string;
+}
+interface HadithContent {
+    lang: string;
+    chapterNumber: string;
+    chapterTitle: string;
+    body: string;
+    urn: number;
+    grades: HadithGrade[];
+}
+interface Hadith {
+    urn: number;
+    collection: string;
+    bookNumber: string;
+    chapterId: string;
+    hadithNumber: string;
+    name: string;
+    hadith: HadithContent[];
+}
+interface HadithsByAyahResponse {
+    hadiths: Hadith[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+    language: string;
+    direction: string;
+}
+type HadithCountWithinRangeResponse = Record<string, number>;
+
 interface Tafsir {
     id?: number;
     resourceId?: number;
@@ -369,76 +494,6 @@ interface Pagination {
     totalRecords: number;
 }
 
-interface RecitationResource {
-    id?: number;
-    reciterName?: string;
-    style?: string;
-    translatedName?: TranslatedName;
-}
-interface RecitationInfoResource {
-    id?: number;
-    info?: string;
-}
-interface TranslationResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface TranslationInfoResource {
-    id?: number;
-    info?: string;
-}
-interface TafsirResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface TafsirInfoResource {
-    id?: number;
-    info?: string;
-}
-interface RecitationStylesResource {
-    mujawwad: string;
-    murattal: string;
-    muallim: string;
-}
-interface LanguageResource {
-    id?: number;
-    name?: string;
-    nativeName?: string;
-    isoCode?: string;
-    direction?: string;
-    translatedNames?: TranslatedName[];
-}
-interface ChapterInfoResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    slug?: string;
-    languageName?: string;
-    translatedName?: TranslatedName;
-}
-interface VerseMediaResource {
-    id?: number;
-    name?: string;
-    authorName?: string;
-    languageName?: string;
-}
-interface ChapterReciterResource {
-    id: number;
-    name: string;
-    arabicName?: string;
-    relativePath?: string;
-    format?: string;
-    filesSize?: number;
-}
-
 type GetChapterRecitationOptions = BaseApiParams;
 type GetVerseRecitationOptions = BaseApiParams & {
     fields?: Partial<Record<VerseRecitationField, boolean>>;
@@ -493,6 +548,10 @@ declare class QuranAudio {
 }
 
 type GetChapterOptions = BaseApiParams;
+type GetChapterInfoOptions = BaseApiParams & {
+    resourceId?: string | number;
+    includeResources?: boolean;
+};
 /**
  * Chapters API methods
  */
@@ -521,12 +580,61 @@ declare class QuranChapters {
      * Get chapter info by id.
      * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
      * @param {ChapterId} id chapter id, minimum 1, maximum 114
-     * @param {GetChapterOptions} options
+     * @param {GetChapterInfoOptions} options
      * @example
      * client.chapters.findInfoById('1')
      * client.chapters.findInfoById('114')
      */
-    findInfoById(id: ChapterId, options?: GetChapterOptions): Promise<ChapterInfo>;
+    findInfoById(id: ChapterId, options?: GetChapterInfoOptions): Promise<ChapterInfo | null>;
+    /**
+     * Get the full chapter info response, including available resources when requested.
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
+     * @param {ChapterId} id chapter id, minimum 1, maximum 114
+     * @param {GetChapterInfoOptions} options
+     * @example
+     * client.chapters.findInfoResponseById('1', { includeResources: true })
+     * client.chapters.findInfoResponseById('1', { resourceId: 'en-tafsir-ibn-ashur' })
+     */
+    findInfoResponseById(id: ChapterId, options?: GetChapterInfoOptions): Promise<ChapterInfoResponse>;
+}
+
+type GetHadithReferenceOptions = BaseApiParams;
+type GetHadithsByAyahOptions = BaseApiParams & {
+    page?: number;
+    limit?: number;
+};
+type CountHadithsWithinRangeOptions = BaseApiParams;
+/**
+ * Hadith reference API methods.
+ */
+declare class QuranHadithReferences {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get ordered hadith reference records linked to a specific ayah.
+     * @param {VerseKey} key verse key in format "chapter:verse" (e.g., "12:12")
+     * @param {GetHadithReferenceOptions} options
+     * @example
+     * client.hadithReferences.findByAyah("12:12")
+     */
+    findByAyah(key: VerseKey, options?: GetHadithReferenceOptions): Promise<HadithReferencesByAyahResponse>;
+    /**
+     * Get paginated hadith payloads linked to a specific ayah.
+     * @param {VerseKey} key verse key in format "chapter:verse" (e.g., "12:12")
+     * @param {GetHadithsByAyahOptions} options
+     * @example
+     * client.hadithReferences.findHadithsByAyah("12:12", { limit: 4 })
+     */
+    findHadithsByAyah(key: VerseKey, options?: GetHadithsByAyahOptions): Promise<HadithsByAyahResponse>;
+    /**
+     * Get a verse-key to hadith-count map within an inclusive ayah range.
+     * @param {VerseKey} from start verse key in format "chapter:verse"
+     * @param {VerseKey} to end verse key in format "chapter:verse"
+     * @param {CountHadithsWithinRangeOptions} options
+     * @example
+     * client.hadithReferences.countWithinRange("12:12", "12:13")
+     */
+    countWithinRange(from: VerseKey, to: VerseKey, options?: CountHadithsWithinRangeOptions): Promise<HadithCountWithinRangeResponse>;
 }
 
 /**
@@ -736,4 +844,4 @@ declare class QuranVerses {
     findRandom(options?: GetVerseOptions): Promise<Verse>;
 }
 
-export { type AudioResponse as A, type ChapterReciterResource as B, type ChapterId as C, SearchNavigationType as D, type SearchResult as E, type HizbNumber as H, type JuzNumber as J, type LanguageResource as L, type NormalizedVerseRecitation as N, type PageNumber as P, QuranChapters as Q, type RubNumber as R, type SearchResponse as S, type TranslatedName as T, type VerseKey as V, type Word as W, QuranVerses as a, QuranJuzs as b, QuranAudio as c, QuranResources as d, QuranSearch as e, type ChapterRecitation as f, type VerseRecitation as g, type Chapter as h, type ChapterInfo as i, type Segment as j, type Tafsir as k, type Translation as l, type Transliteration as m, type Verse as n, CharType as o, type Juz as p, type Pagination as q, type RecitationResource as r, type RecitationInfoResource as s, type TranslationResource as t, type TranslationInfoResource as u, type TafsirResource as v, type TafsirInfoResource as w, type RecitationStylesResource as x, type ChapterInfoResource as y, type VerseMediaResource as z };
+export { type AudioResponse as A, type RecitationResource as B, type ChapterId as C, type RecitationInfoResource as D, type TranslationResource as E, type TranslationInfoResource as F, type TafsirResource as G, type HizbNumber as H, type TafsirInfoResource as I, type JuzNumber as J, type RecitationStylesResource as K, type LanguageResource as L, type ChapterInfoResource as M, type NormalizedVerseRecitation as N, type VerseMediaResource as O, type PageNumber as P, QuranChapters as Q, type RubNumber as R, type SearchResponse as S, type TranslatedName as T, type ChapterReciterResource as U, type VerseKey as V, type Word as W, SearchNavigationType as X, type SearchResult as Y, QuranVerses as a, QuranJuzs as b, QuranAudio as c, QuranHadithReferences as d, QuranResources as e, QuranSearch as f, type ChapterRecitation as g, type VerseRecitation as h, type Chapter as i, type ChapterInfo as j, type ChapterInfoResponse as k, type HadithReference as l, type HadithReferencesByAyahResponse as m, type HadithGrade as n, type HadithContent as o, type Hadith as p, type HadithsByAyahResponse as q, type HadithCountWithinRangeResponse as r, type Segment as s, type Tafsir as t, type Translation as u, type Transliteration as v, type Verse as w, CharType as x, type Juz as y, type Pagination as z };

package/package.json

@@ -11,7 +11,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "3.1.0",
+  "version": "3.2.0",
   "main": "dist/index.min.js",
   "module": "dist/index.min.mjs",
   "types": "dist/index.d.ts",