@quranjs/api 1.8.0 → 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,1008 @@
+/**
+ * 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>;
+
+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 SearchResponse {
+    search: {
+        query: string;
+        totalResults: number;
+        currentPage: number;
+        totalPages: number;
+        results?: {
+            verseKey: string;
+            verse_id: number;
+            text: string;
+            highlighted: string;
+            words: Word[];
+            translations: Translation[];
+        }[];
+    };
+}
+
+/**
+ * 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;
+    url: string;
+    id?: number;
+    chapterId?: number;
+    segments?: Segment[];
+    format?: 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 Footnote {
+    id: number | string;
+    text: string;
+    languageName?: string;
+    languageId?: number;
+}
+
+interface Reciter {
+    id: number;
+    name: string;
+    recitationStyle: string;
+    relativePath: string;
+    profilePicture?: string;
+    coverImage?: string;
+    bio?: string;
+    qirat?: {
+        languageName: string;
+        name: string;
+    };
+    style?: {
+        languageName: string;
+        name: string;
+    };
+    translatedName?: {
+        languageName: string;
+        name: string;
+    };
+}
+
+interface Tafsir {
+    id?: number;
+    resourceId?: number;
+    text?: string;
+    resourceName?: string;
+    languageName?: string;
+}
+
+interface TafsirInfo {
+    id?: number;
+    name?: string;
+    authorName?: string;
+    slug?: string;
+    languageName?: string;
+    translatedName: TranslatedName;
+}
+
+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;
+}
+
+interface SearchResult {
+    verseKey: VerseKey;
+    verseId: number;
+    text: string;
+    highlighted?: string;
+    words: Word[];
+    translations: Translation[];
+}
+
+type ApiParams = Record<string, string | number | boolean | unknown[] | undefined | Record<string, boolean>>;
+/**
+ * Base parameters that are common across most API endpoints
+ */
+interface BaseApiParams extends ApiParams {
+    /** Language for the response */
+    language?: Language;
+}
+/**
+ * Pagination parameters
+ */
+interface PaginationParams extends ApiParams {
+    /** Page number for pagination */
+    page?: number;
+    /** Number of items per page */
+    perPage?: number;
+}
+/**
+ * Search parameters
+ */
+interface SearchParams extends BaseApiParams {
+    /** Number of results to return */
+    size?: number;
+    /** Page number for pagination */
+    page?: number;
+}
+
+/**
+ * Custom fetcher function type that matches the native fetch API
+ */
+type CustomFetcher = typeof fetch;
+interface QuranClientConfig {
+    /** Client ID for authentication */
+    clientId: string;
+    /** Client secret for authentication */
+    clientSecret: string;
+    /** Base URL for content APIs */
+    contentBaseUrl?: string;
+    /** Base URL for authentication */
+    authBaseUrl?: string;
+    /** Custom fetch implementation */
+    fetch?: CustomFetcher;
+    /** Default parameters for all API calls */
+    defaults?: Partial<BaseApiParams>;
+}
+interface CachedToken {
+    value: string;
+    expiresAt: number;
+}
+interface TokenResponse {
+    access_token: string;
+    expires_in: number;
+}
+
+declare enum Language {
+    ARABIC = "ar",
+    ENGLISH = "en",
+    URDU = "ur",
+    BENGALI = "bn",
+    TURKISH = "tr",
+    SPANISH = "es",
+    GERMAN = "de",
+    BOSNIAN = "bs",
+    RUSSIAN = "ru",
+    ALBANIAN_AL = "al",
+    FRENCH = "fr",
+    DUTCH = "nl",
+    TAMIL = "ta",
+    TAJIK = "tg",
+    INDONESIAN = "id",
+    UZBEK = "uz",
+    VIETNAMESE = "vi",
+    CHINESE = "zh",
+    ITALIAN = "it",
+    JAPANESE = "ja",
+    MALAYALAM = "ml",
+    AMHARIC = "am",
+    KAZAKH = "kk",
+    PORTUGUESE = "pt",
+    TAGALOG = "tl",
+    THAI = "th",
+    KOREAN = "ko",
+    HINDI = "hi",
+    KURDISH = "ku",
+    HAUSA = "ha",
+    AZERI = "az",
+    SWAHILI = "sw",
+    PERSIAN = "fa",
+    SERBIAN = "sr",
+    MARANAO = "mrn",
+    AMAZIGH = "zgh",
+    ASSAMESE = "as",
+    BULGARIAN = "bg",
+    CHECHEN = "ce",
+    CZECH = "cs",
+    DIVEHI = "dv",
+    FINNISH = "fi",
+    GUJAARATI = "gu",
+    HEBREW = "he",
+    GEORGIAN = "ka",
+    CENTRAL_KHMER = "km",
+    GANDA = "lg",
+    MARATHI = "mr",
+    YORUBA = "yo",
+    MALAY = "ms",
+    NEPALI = "ne",
+    SWEDISH = "sv",
+    TELUGU = "te",
+    TATAR = "tt",
+    UYGHUR = "ug",
+    UKRAINIAN = "uk",
+    NORWEGIAN = "no",
+    OROMO = "om",
+    POLISH = "pl",
+    PASHTO = "ps",
+    ROMANIAN = "ro",
+    SINDHI = "sd",
+    NORTHERN_SAMI = "se",
+    SINHALA = "si",
+    SOMALI = "so",
+    ALBANIAN_SQ = "sq"
+}
+declare enum QuranFont {
+    MadaniV1 = "code_v1",
+    MadaniV2 = "code_v2",
+    Uthmani = "text_uthmani"
+}
+type VerseField = "chapterId" | "textUthmani" | "textUthmaniSimple" | "textImlaei" | "textImlaeiSimple" | "textIndopak" | "textIndopakNastaleeq" | "textUthmaniTajweed" | "imageUrl" | "imageWidth" | "codeV1" | "codeV2" | "v1Page" | "v2Page";
+type WordField = "v1Page" | "v2Page" | "textUthmani" | "textImlaei" | "textIndopak" | "verseKey" | "location" | "codeV1" | "codeV2";
+type TranslationField = "resourceName" | "verseId" | "languageId" | "languageName" | "verseKey" | "chapterId" | "verseNumber" | "juzNumber" | "hizbNumber" | "rubNumber" | "pageNumber";
+type VerseRecitationField = "id" | "chapterId" | "segments" | "format";
+
+type Config = Required<Pick<QuranClientConfig, "contentBaseUrl" | "authBaseUrl">> & Omit<QuranClientConfig, "contentBaseUrl" | "authBaseUrl">;
+/**
+ * Handles HTTP requests with authentication for the Quran API
+ */
+declare class QuranFetcher {
+    private config;
+    private cachedToken;
+    constructor(config: Config);
+    /**
+     * Update the configuration
+     */
+    updateConfig(config: Config): void;
+    getFetch(): CustomFetcher;
+    private doFetch;
+    /**
+     * Get access token for API authentication
+     */
+    private getAccessToken;
+    /**
+     * Clear cached token (useful for testing or forcing re-authentication)
+     */
+    clearCachedToken(): void;
+    /**
+     * Make URL with base URL and query parameters
+     */
+    private makeUrl;
+    /**
+     * Make authenticated HTTP request
+     */
+    fetch<T extends object>(url: string, params?: ApiParams): Promise<T>;
+}
+
+type GetChapterRecitationOptions = BaseApiParams;
+type GetVerseRecitationOptions = BaseApiParams & {
+    fields?: Partial<Record<VerseRecitationField, boolean>>;
+};
+/**
+ * Audio API methods
+ */
+declare class QuranAudio {
+    private fetcher;
+    constructor(fetcher: QuranFetcher);
+    /**
+     * 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: VerseRecitation[];
+        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: VerseRecitation[];
+        pagination: Pagination;
+    }>;
+}
+
+type GetChapterOptions = BaseApiParams;
+/**
+ * Chapters API methods
+ */
+declare class QuranChapters {
+    private fetcher;
+    constructor(fetcher: QuranFetcher);
+    /**
+     * 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: QuranFetcher);
+    /**
+     * 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: QuranFetcher);
+    /**
+     * 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 = SearchParams;
+/**
+ * Search API methods
+ */
+declare class QuranSearch {
+    private fetcher;
+    constructor(fetcher: QuranFetcher);
+    /**
+     * Search
+     * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/search
+     * @param {string} q search query
+     * @param {SearchOptions} options
+     * @example
+     * client.search.search('نور')
+     * client.search.search('نور', { language: Language.ENGLISH })
+     * client.search.search('نور', { language: Language.ENGLISH, size: 10 })
+     * client.search.search('نور', { language: Language.ENGLISH, page: 2 })
+     */
+    search(q: string, options?: SearchOptions): Promise<SearchResponse["search"]>;
+}
+
+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: QuranFetcher);
+    /**
+     * 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 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>;
+}
+
+/**
+ * Main Quran API client
+ */
+declare class QuranClient {
+    private config;
+    private fetcher;
+    readonly chapters: QuranChapters;
+    readonly verses: QuranVerses;
+    readonly juzs: QuranJuzs;
+    readonly audio: QuranAudio;
+    readonly resources: QuranResources;
+    readonly search: QuranSearch;
+    constructor(config: QuranClientConfig);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): QuranClientConfig;
+    /**
+     * Update the configuration
+     */
+    updateConfig(newConfig: Partial<QuranClientConfig>): void;
+    /**
+     * Clear cached authentication token
+     */
+    clearCachedToken(): void;
+}
+
+/**
+ * Validates chapter id
+ * @param id chapter id
+ * @example
+ * isValidChapterId('1') // true
+ * isValidChapterId('114') // true
+ * isValidChapterId('0') // false
+ * isValidChapterId('-1') // false
+ * isValidChapterId('200') // false
+ */
+declare const isValidChapterId: (id: string | number) => id is ChapterId;
+
+/**
+ * Validates juz number
+ * @param juz juz number
+ * @example
+ * isValidJuz('1') // true
+ * isValidJuz('30') // true
+ * isValidJuz('0') // false
+ * isValidJuz('-1') // false
+ * isValidJuz('200') // false
+ */
+declare const isValidJuz: (juz: string | number) => juz is JuzNumber;
+
+/**
+ * Validates rub number
+ * @param rub rub number
+ * @example
+ * isValidRub('1') // true
+ * isValidRub('240') // true
+ * isValidRub('0') // false
+ * isValidRub('-1') // false
+ * isValidRub('300') // false
+ */
+declare const isValidRub: (rub: string | number) => rub is RubNumber;
+
+/**
+ * Validates hizb number
+ * @param hizb hizb number
+ * @example
+ * isValidHizb('1') // true
+ * isValidHizb('60') // true
+ * isValidHizb('0') // false
+ * isValidHizb('-1') // false
+ * isValidHizb('200') // false
+ */
+declare const isValidHizb: (hizb: string | number) => hizb is HizbNumber;
+
+/**
+ * Validates mushaf page number
+ * @param page mushaf page number
+ * @example
+ * isValidQuranPage('1') // true
+ * isValidQuranPage('604') // true
+ * isValidQuranPage('0') // false
+ * isValidQuranPage('-1') // false
+ * isValidQuranPage('1000') // false
+ */
+declare const isValidQuranPage: (page: string | number) => page is PageNumber;
+
+/**
+ * Validates verse key
+ * @param key colon separated verse key (chapter:verse)
+ * @example
+ * isValidVerseKey('1:1') // true
+ * isValidVerseKey('30:1') // true
+ * isValidVerseKey('0') // false
+ * isValidVerseKey('1:-') // false
+ * isValidVerseKey('1_1') // false
+ */
+declare const isValidVerseKey: (key: string) => key is VerseKey;
+
+export { type ApiParams, type AudioResponse, type BaseApiParams, type CachedToken, type Chapter, type ChapterId, type ChapterInfo, type ChapterInfoResource, type ChapterRecitation, type ChapterReciterResource, CharType, type CustomFetcher, type Footnote, type HizbNumber, type Juz, type JuzNumber, Language, type LanguageResource, type PageNumber, type Pagination, type PaginationParams, QuranClient, type QuranClientConfig, QuranFont, type RecitationInfoResource, type RecitationResource, type RecitationStylesResource, type Reciter, type RubNumber, type SearchParams, type SearchResponse, type SearchResult, type Segment, type Tafsir, type TafsirInfo, type TafsirInfoResource, type TafsirResource, type TokenResponse, type TranslatedName, type Translation, type TranslationField, type TranslationInfoResource, type TranslationResource, type Transliteration, type Verse, type VerseField, type VerseKey, type VerseMediaResource, type VerseRecitation, type VerseRecitationField, type Word, type WordField, isValidChapterId, isValidHizb, isValidJuz, isValidQuranPage, isValidRub, isValidVerseKey };