@quranjs/api 2.2.0 → 3.1.0

package/dist/verses-DnPcyHIi.d.ts

@@ -0,0 +1,739 @@
+import { e as QuranFetchClient, B as BaseApiParams, b as VerseRecitationField, d as SearchParams, P as PaginationParams, W as WordField, T as TranslationField, V as VerseField } from './index-BZgqOfA4.js';
+
+/**
+ * Maps chapter number to verse count
+ */
+declare const versesMapping: {
+    readonly 1: 7;
+    readonly 2: 286;
+    readonly 3: 200;
+    readonly 4: 176;
+    readonly 5: 120;
+    readonly 6: 165;
+    readonly 7: 206;
+    readonly 8: 75;
+    readonly 9: 129;
+    readonly 10: 109;
+    readonly 11: 123;
+    readonly 12: 111;
+    readonly 13: 43;
+    readonly 14: 52;
+    readonly 15: 99;
+    readonly 16: 128;
+    readonly 17: 111;
+    readonly 18: 110;
+    readonly 19: 98;
+    readonly 20: 135;
+    readonly 21: 112;
+    readonly 22: 78;
+    readonly 23: 118;
+    readonly 24: 64;
+    readonly 25: 77;
+    readonly 26: 227;
+    readonly 27: 93;
+    readonly 28: 88;
+    readonly 29: 69;
+    readonly 30: 60;
+    readonly 31: 34;
+    readonly 32: 30;
+    readonly 33: 73;
+    readonly 34: 54;
+    readonly 35: 45;
+    readonly 36: 83;
+    readonly 37: 182;
+    readonly 38: 88;
+    readonly 39: 75;
+    readonly 40: 85;
+    readonly 41: 54;
+    readonly 42: 53;
+    readonly 43: 89;
+    readonly 44: 59;
+    readonly 45: 37;
+    readonly 46: 35;
+    readonly 47: 38;
+    readonly 48: 29;
+    readonly 49: 18;
+    readonly 50: 45;
+    readonly 51: 60;
+    readonly 52: 49;
+    readonly 53: 62;
+    readonly 54: 55;
+    readonly 55: 78;
+    readonly 56: 96;
+    readonly 57: 29;
+    readonly 58: 22;
+    readonly 59: 24;
+    readonly 60: 13;
+    readonly 61: 14;
+    readonly 62: 11;
+    readonly 63: 11;
+    readonly 64: 18;
+    readonly 65: 12;
+    readonly 66: 12;
+    readonly 67: 30;
+    readonly 68: 52;
+    readonly 69: 52;
+    readonly 70: 44;
+    readonly 71: 28;
+    readonly 72: 28;
+    readonly 73: 20;
+    readonly 74: 56;
+    readonly 75: 40;
+    readonly 76: 31;
+    readonly 77: 50;
+    readonly 78: 40;
+    readonly 79: 46;
+    readonly 80: 42;
+    readonly 81: 29;
+    readonly 82: 19;
+    readonly 83: 36;
+    readonly 84: 25;
+    readonly 85: 22;
+    readonly 86: 17;
+    readonly 87: 19;
+    readonly 88: 26;
+    readonly 89: 30;
+    readonly 90: 20;
+    readonly 91: 15;
+    readonly 92: 21;
+    readonly 93: 11;
+    readonly 94: 8;
+    readonly 95: 8;
+    readonly 96: 19;
+    readonly 97: 5;
+    readonly 98: 8;
+    readonly 99: 8;
+    readonly 100: 11;
+    readonly 101: 11;
+    readonly 102: 8;
+    readonly 103: 3;
+    readonly 104: 9;
+    readonly 105: 5;
+    readonly 106: 4;
+    readonly 107: 7;
+    readonly 108: 3;
+    readonly 109: 6;
+    readonly 110: 3;
+    readonly 111: 5;
+    readonly 112: 4;
+    readonly 113: 5;
+    readonly 114: 6;
+};
+
+type _NumbersFrom0ToN<Nr extends number> = Nr extends Nr ? number extends Nr ? number : Nr extends 0 ? never : _NumbersFrom0ToNRec<Nr, [], 0> : never;
+type _NumbersFrom0ToNRec<Nr extends number, Counter extends unknown[], Accumulator extends number> = Counter["length"] extends Nr ? Accumulator : _NumbersFrom0ToNRec<Nr, [
+    unknown,
+    ...Counter
+], Accumulator | Counter["length"]>;
+type NumberRange<Start extends number, End extends number> = Exclude<_NumbersFrom0ToN<End>, _NumbersFrom0ToN<Start>>;
+type NumberUnionToString<TType> = TType extends number ? `${TType}` : TType;
+/**
+ * Builds a tuple with a length equal to the provided number literal.
+ * Used for type-level arithmetic.
+ */
+type BuildTuple<TLength extends number, TAccumulator extends unknown[] = []> = TAccumulator["length"] extends TLength ? TAccumulator : BuildTuple<TLength, [...TAccumulator, unknown]>;
+/**
+ * Increments a numeric literal type by 1.
+ */
+type Increment<TNumber extends number> = [
+    ...BuildTuple<TNumber>,
+    unknown
+]["length"];
+
+/**
+ * A `VerseKey` is a string literal in the form `${chapter}:${verse}` where:
+ * - `chapter` is a valid chapter id from `versesMapping`
+ * - `verse` is within the range 1..(verseCount for that chapter)
+ */
+type VerseKey = {
+    [TChapter in keyof typeof versesMapping]: `${TChapter}:${NumberRange<1, Increment<(typeof versesMapping)[TChapter]>>}`;
+}[keyof typeof versesMapping];
+
+type ChapterId = keyof typeof versesMapping | NumberUnionToString<keyof typeof versesMapping>;
+
+type _HizbNumber = NumberRange<1, 61>;
+type HizbNumber = _HizbNumber | NumberUnionToString<_HizbNumber>;
+
+type _JuzNumber = NumberRange<1, 31>;
+type JuzNumber = _JuzNumber | NumberUnionToString<_JuzNumber>;
+
+type _PageNumber = NumberRange<1, 605>;
+type PageNumber = _PageNumber | NumberUnionToString<_PageNumber>;
+
+type _RubNumber = NumberRange<1, 241>;
+type RubNumber = _RubNumber | NumberUnionToString<_RubNumber>;
+
+declare enum SearchNavigationType {
+    SURAH = "surah",
+    JUZ = "juz",
+    HIZB = "hizb",
+    AYAH = "ayah",
+    RUB_EL_HIZB = "rub_el_hizb",
+    SEARCH_PAGE = "search_page",
+    PAGE = "page",
+    RANGE = "range",
+    QURAN_RANGE = "quran_range"
+}
+interface SearchResult {
+    resultType: SearchNavigationType;
+    key: number | string;
+    name: string;
+    arabic?: string;
+    isArabic?: boolean;
+    isTransliteration?: boolean;
+}
+
+interface SearchResponse {
+    pagination: {
+        currentPage: number;
+        nextPage: number | null;
+        perPage: number;
+        totalPages: number;
+        totalRecords: number;
+    };
+    result?: {
+        navigation: SearchResult[];
+        verses: SearchResult[];
+    };
+}
+
+/**
+ * Segment structure is [wordFrom, wordTo, timeFrom, timeTo] time is in ms
+ */
+type Segment = [number, number, number, number];
+
+interface ChapterRecitation {
+    id: number;
+    chapterId: number;
+    fileSize: number;
+    format: string;
+    audioUrl: string;
+}
+interface VerseRecitation {
+    verseKey: VerseKey;
+    /** Relative URL path (e.g., "AbdulBaset/Murattal/mp3/002255.mp3") */
+    url: string;
+    /** Absolute URL when returned by SDK helpers (e.g., "https://verses.quran.com/AbdulBaset/Murattal/mp3/002255.mp3") */
+    audioUrl?: string;
+    id?: number;
+    chapterId?: number;
+    segments?: Segment[];
+    format?: string;
+}
+type NormalizedVerseRecitation = VerseRecitation & {
+    audioUrl: string;
+};
+
+interface AudioResponse {
+    url?: string;
+    duration?: number;
+    format?: string;
+    verseKey: string;
+    segments?: Segment[];
+}
+
+interface TranslatedName {
+    name: string;
+    languageName: string;
+}
+
+interface Chapter {
+    id: number;
+    versesCount: number;
+    bismillahPre: boolean;
+    revelationOrder: number;
+    revelationPlace: string;
+    pages: Array<number>;
+    nameComplex: string;
+    nameSimple: string;
+    transliteratedName: string;
+    nameArabic: string;
+    translatedName: TranslatedName;
+}
+
+interface ChapterInfo {
+    id: number;
+    chapterId: number;
+    text: string;
+    shortText: string;
+    source: string;
+    languageName?: string;
+}
+
+interface Tafsir {
+    id?: number;
+    resourceId?: number;
+    text?: string;
+    resourceName?: string;
+    languageName?: string;
+    slug?: string;
+    languageId?: number;
+    groupVerseKeyFrom?: string;
+    groupVerseKeyTo?: string;
+    groupTafsirId?: number;
+    startVerseId?: number;
+    endVerseId?: number;
+}
+
+interface Translation {
+    id?: number;
+    text: string;
+    resourceId: number;
+    resourceName?: string;
+    verseId?: number;
+    languageId?: number;
+    languageName?: string;
+    verseKey?: VerseKey;
+    chapterId?: number;
+    verseNumber?: number;
+    juzNumber?: number;
+    hizbNumber?: number;
+    rubNumber?: number;
+    pageNumber?: number;
+}
+
+interface Transliteration {
+    languageName?: string;
+    text?: string;
+}
+
+declare enum CharType {
+    Word = "word",
+    End = "end",
+    Pause = "pause",
+    Sajdah = "sajdah",
+    RubElHizb = "rub-el-hizb"
+}
+interface Word {
+    id?: number;
+    position: number;
+    audioUrl: string;
+    charTypeName: CharType;
+    codeV1?: string;
+    codeV2?: string;
+    pageNumber?: number;
+    lineNumber?: number;
+    text?: string;
+    textUthmani?: string;
+    textIndopak?: string;
+    textImlaei?: string;
+    translation: Translation;
+    transliteration: Transliteration;
+    location?: string;
+    verseKey?: VerseKey;
+}
+
+interface Verse {
+    id: number;
+    verseNumber: number;
+    verseKey: VerseKey;
+    chapterId?: number | string;
+    pageNumber: number;
+    juzNumber: number;
+    hizbNumber: number;
+    rubElHizbNumber: number;
+    words?: Word[];
+    textUthmani?: string;
+    textUthmaniSimple?: string;
+    textUthmaniTajweed?: string;
+    textImlaei?: string;
+    textImlaeiSimple?: string;
+    textIndopak?: string;
+    textIndopakNastaleeq?: string;
+    sajdahNumber: null;
+    imageUrl?: string;
+    imageWidth?: number;
+    v1Page?: number;
+    v2Page?: number;
+    codeV1?: string;
+    codeV2?: string;
+    translations?: Translation[];
+    tafsirs?: Tafsir[];
+    audio?: AudioResponse;
+}
+
+interface Juz {
+    id: number;
+    juzNumber: number;
+    verseMapping: Record<number, string>;
+    firstVerseId: number;
+    lastVerseId: number;
+    versesCount: number;
+}
+
+interface Pagination {
+    perPage: number;
+    currentPage: number;
+    nextPage: number;
+    totalPages: number;
+    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>>;
+};
+/**
+ * Audio API methods
+ */
+declare class QuranAudio {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get all chapter recitations for specific reciter
+     * @param {string} reciterId
+     * @param {GetChapterRecitationOptions} options
+     * @example
+     * client.audio.findAllChapterRecitations('2')
+     */
+    findAllChapterRecitations(reciterId: string, options?: GetChapterRecitationOptions): Promise<ChapterRecitation[]>;
+    /**
+     * Get a specific chapter recitation by reciter and chapter
+     * @param {string} reciterId
+     * @param {ChapterId} chapterId
+     * @param {GetChapterRecitationOptions} options
+     * @example
+     * client.audio.findChapterRecitationById('2', '1')
+     */
+    findChapterRecitationById(reciterId: string, chapterId: ChapterId, options?: GetChapterRecitationOptions): Promise<ChapterRecitation>;
+    /**
+     * Get verse recitations by chapter
+     * @param {ChapterId} chapterId
+     * @param {string} recitationId
+     * @param {GetVerseRecitationOptions} options
+     * @example
+     * client.audio.findVerseRecitationsByChapter('1', '2')
+     */
+    findVerseRecitationsByChapter(chapterId: ChapterId, recitationId: string, options?: GetVerseRecitationOptions): Promise<{
+        audioFiles: NormalizedVerseRecitation[];
+        pagination: Pagination;
+    }>;
+    /**
+     * Get verse recitations by verse key
+     * @param {VerseKey} key
+     * @param {string} recitationId
+     * @param {GetVerseRecitationOptions} options
+     * @example
+     * client.audio.findVerseRecitationsByKey('1:1', '2')
+     */
+    findVerseRecitationsByKey(key: VerseKey, recitationId: string, options?: GetVerseRecitationOptions): Promise<{
+        audioFiles: NormalizedVerseRecitation[];
+        pagination: Pagination;
+    }>;
+}
+
+type GetChapterOptions = BaseApiParams;
+/**
+ * Chapters API methods
+ */
+declare class QuranChapters {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get all chapters.
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/list-chapters
+     * @param {GetChapterOptions} options
+     * @example
+     * client.chapters.findAll()
+     */
+    findAll(options?: GetChapterOptions): Promise<Chapter[]>;
+    /**
+     * Get chapter by id.
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter
+     * @param {ChapterId} id chapter id, minimum 1, maximum 114
+     * @param {GetChapterOptions} options
+     * @example
+     * client.chapters.findById('1')
+     * client.chapters.findById('114')
+     */
+    findById(id: ChapterId, options?: GetChapterOptions): Promise<Chapter>;
+    /**
+     * 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
+     * @example
+     * client.chapters.findInfoById('1')
+     * client.chapters.findInfoById('114')
+     */
+    findInfoById(id: ChapterId, options?: GetChapterOptions): Promise<ChapterInfo>;
+}
+
+/**
+ * Juzs API methods
+ */
+declare class QuranJuzs {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get All Juzs
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/juzs
+     * @example
+     * client.juzs.findAll()
+     */
+    findAll(): Promise<Juz[]>;
+}
+
+type GetResourceOptions = BaseApiParams;
+/**
+ * Resources API methods
+ */
+declare class QuranResources {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get all recitations.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllRecitations()
+     */
+    findAllRecitations(options?: GetResourceOptions): Promise<RecitationResource[]>;
+    /**
+     * Get all translations.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllTranslations()
+     */
+    findAllTranslations(options?: GetResourceOptions): Promise<TranslationResource[]>;
+    /**
+     * Get all tafsirs.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllTafsirs()
+     */
+    findAllTafsirs(options?: GetResourceOptions): Promise<TafsirResource[]>;
+    /**
+     * Get all languages.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllLanguages()
+     */
+    findAllLanguages(options?: GetResourceOptions): Promise<LanguageResource[]>;
+    /**
+     * Get recitation info by id.
+     * @param {string} id recitation id
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findRecitationInfo('1')
+     */
+    findRecitationInfo(id: string, options?: GetResourceOptions): Promise<RecitationInfoResource>;
+    /**
+     * Get translation info by id.
+     * @param {string} id translation id
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findTranslationInfo('131')
+     */
+    findTranslationInfo(id: string, options?: GetResourceOptions): Promise<TranslationInfoResource>;
+    /**
+     * Get tafsir info by id.
+     * @param {string} id tafsir id
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findTafsirInfo('171')
+     */
+    findTafsirInfo(id: string, options?: GetResourceOptions): Promise<TafsirInfoResource>;
+    /**
+     * Get all chapter infos.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllChapterInfos()
+     */
+    findAllChapterInfos(options?: GetResourceOptions): Promise<ChapterInfoResource[]>;
+    /**
+     * Get all chapter reciters.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllChapterReciters()
+     */
+    findAllChapterReciters(options?: GetResourceOptions): Promise<ChapterReciterResource[]>;
+    /**
+     * Get all recitation styles.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findAllRecitationStyles()
+     */
+    findAllRecitationStyles(options?: GetResourceOptions): Promise<RecitationStylesResource>;
+    /**
+     * Get verse media.
+     * @param {GetResourceOptions} options
+     * @example
+     * client.resources.findVerseMedia()
+     */
+    findVerseMedia(options?: GetResourceOptions): Promise<VerseMediaResource>;
+}
+
+type SearchOptions = Omit<SearchParams, "query">;
+/**
+ * Search API methods
+ */
+declare class QuranSearch {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Search
+     * @description /v1/search
+     * @param {string} query search query
+     * @param {SearchOptions} options
+     * @example
+     * client.search.search('نور', { mode: SearchMode.Quick })
+     * client.search.search('نور', { mode: SearchMode.Advanced, exactMatchesOnly: '1' })
+     * client.search.search('نور', { mode: SearchMode.Quick, size: 10 })
+     * client.search.search('نور', { mode: SearchMode.Quick, page: 2 })
+     */
+    search(query: string, options: SearchOptions): Promise<SearchResponse>;
+}
+
+type GetVerseOptions = BaseApiParams & PaginationParams & {
+    reciter?: string | number;
+    words?: boolean;
+    translations?: string[] | number[];
+    tafsirs?: string[] | number[];
+    wordFields?: Partial<Record<WordField, boolean>>;
+    translationFields?: Partial<Record<TranslationField, boolean>>;
+    fields?: Partial<Record<VerseField, boolean>>;
+};
+/**
+ * Verses API methods
+ */
+declare class QuranVerses {
+    private fetcher;
+    constructor(fetcher: QuranFetchClient);
+    /**
+     * Get a specific verse by its key.
+     * @param {VerseKey} key verse key in format "chapter:verse" (e.g., "1:1")
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByKey('1:1')
+     * client.verses.findByKey('2:255')
+     */
+    findByKey(key: VerseKey, options?: GetVerseOptions): Promise<Verse>;
+    /**
+     * Get verses by range.
+     * @param {VerseKey} from start verse key (e.g., "1:1")
+     * @param {VerseKey} to end verse key (e.g., "1:7")
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByRange('1:1', '1:7')
+     */
+    findByRange(from: VerseKey, to: VerseKey, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get verses by chapter.
+     * @param {ChapterId} id chapter id, minimum 1, maximum 114
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByChapter('1')
+     */
+    findByChapter(id: ChapterId, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get verses by page number.
+     * @param {PageNumber} page page number
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByPage('1')
+     */
+    findByPage(page: PageNumber, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get verses by juz number.
+     * @param {JuzNumber} juz juz number
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByJuz('1')
+     */
+    findByJuz(juz: JuzNumber, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get verses by hizb number.
+     * @param {HizbNumber} hizb hizb number
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByHizb('1')
+     */
+    findByHizb(hizb: HizbNumber, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get verses by rub number.
+     * @param {RubNumber} rub rub number
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findByRub('1')
+     */
+    findByRub(rub: RubNumber, options?: GetVerseOptions): Promise<Verse[]>;
+    /**
+     * Get a random verse.
+     * @param {GetVerseOptions} options
+     * @example
+     * client.verses.findRandom()
+     */
+    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 };