@quranjs/api 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +81 -0
- package/dist/index.d.mts +117 -76
- package/dist/index.d.ts +117 -76
- package/dist/index.min.js +2 -2
- package/dist/index.min.js.map +1 -1
- package/dist/index.min.mjs +2 -2
- package/dist/index.min.mjs.map +1 -1
- package/package.json +5 -7
package/README.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# @quranjs/api
|
|
2
|
+
|
|
3
|
+
[![NPM Version][npm-badge]][npm]
|
|
4
|
+
[![MIT License][license-badge]][license]
|
|
5
|
+
[![Build Status][build-badge]][build]
|
|
6
|
+
[![NPM Monthly downloads][downloads-badge]][npm]
|
|
7
|
+
|
|
8
|
+
A JavaScript/TypeScript library for fetching **authentic, scholarly verified Quran data** from the [Quran.com API](https://api-docs.quran.foundation/docs/category/content-apis).
|
|
9
|
+
|
|
10
|
+
Unlike other sources, this SDK connects you directly to the **[Quran Foundation](https://quran.foundation)**—ensuring a **trusted, highly scrutinized source** of reliable content, including properly licensed translations, tafsir, and supplementary materials.
|
|
11
|
+
|
|
12
|
+
Works seamlessly in both Node.js and browser environments.
|
|
13
|
+
|
|
14
|
+
**Built by the [Quran Foundation](https://quran.foundation) — the team behind [Quran.com](https://quran.com)**
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# npm
|
|
20
|
+
npm install @quranjs/api
|
|
21
|
+
|
|
22
|
+
# yarn
|
|
23
|
+
yarn add @quranjs/api
|
|
24
|
+
|
|
25
|
+
# pnpm
|
|
26
|
+
pnpm add @quranjs/api
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import { quran } from '@quranjs/api';
|
|
33
|
+
|
|
34
|
+
// Get all chapters
|
|
35
|
+
const chapters = await quran.v4.chapters.findAll();
|
|
36
|
+
|
|
37
|
+
// Get a specific chapter
|
|
38
|
+
const surah = await quran.v4.chapters.findById(1);
|
|
39
|
+
|
|
40
|
+
// Get verses of a chapter
|
|
41
|
+
const verses = await quran.v4.verses.findByChapter(1);
|
|
42
|
+
|
|
43
|
+
// Search the Quran
|
|
44
|
+
const results = await quran.v4.search.search('mercy');
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Documentation
|
|
48
|
+
|
|
49
|
+
For complete documentation, guides, and API reference, visit:
|
|
50
|
+
|
|
51
|
+
📚 **[SDK Documentation](https://api-docs.quran.foundation/docs/sdk/javascript)**
|
|
52
|
+
|
|
53
|
+
## Features
|
|
54
|
+
|
|
55
|
+
- 🚀 Full TypeScript support
|
|
56
|
+
- 🌐 Works in Node.js and browsers
|
|
57
|
+
- ✅ Scholarly verified data
|
|
58
|
+
- 📖 Access chapters, verses, juzs, and more
|
|
59
|
+
- 🔍 Full-text search
|
|
60
|
+
- 🎧 Audio recitations
|
|
61
|
+
- 🌍 Multiple verified translations and languages
|
|
62
|
+
|
|
63
|
+
## Links
|
|
64
|
+
|
|
65
|
+
- [Quran Foundation](https://quran.foundation) — Our mission to make the Quran accessible to everyone
|
|
66
|
+
- [API Documentation](https://api-docs.quran.foundation) — Full API reference
|
|
67
|
+
- [GitHub Repository](https://github.com/quran/api-js) — Source code and issues
|
|
68
|
+
|
|
69
|
+
## License
|
|
70
|
+
|
|
71
|
+
MIT © [Quran Foundation](https://quran.foundation)
|
|
72
|
+
|
|
73
|
+
<!-- Links -->
|
|
74
|
+
|
|
75
|
+
[npm]: https://www.npmjs.com/package/@quranjs/api
|
|
76
|
+
[npm-badge]: https://img.shields.io/npm/v/@quranjs/api
|
|
77
|
+
[license-badge]: https://img.shields.io/npm/l/@quranjs/api
|
|
78
|
+
[license]: https://github.com/quran/api-js/blob/main/LICENSE
|
|
79
|
+
[build-badge]: https://github.com/quran/api-js/workflows/CI/badge.svg
|
|
80
|
+
[build]: https://github.com/quran/api-js/actions?query=workflow%3ACI
|
|
81
|
+
[downloads-badge]: https://img.shields.io/npm/dm/@quranjs/api
|
package/dist/index.d.mts
CHANGED
|
@@ -161,68 +161,37 @@ type PageNumber = _PageNumber | NumberUnionToString<_PageNumber>;
|
|
|
161
161
|
type _RubNumber = NumberRange<1, 241>;
|
|
162
162
|
type RubNumber = _RubNumber | NumberUnionToString<_RubNumber>;
|
|
163
163
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
verseNumber?: number;
|
|
175
|
-
juzNumber?: number;
|
|
176
|
-
hizbNumber?: number;
|
|
177
|
-
rubNumber?: number;
|
|
178
|
-
pageNumber?: number;
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
interface Transliteration {
|
|
182
|
-
languageName?: string;
|
|
183
|
-
text?: string;
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
declare enum CharType {
|
|
187
|
-
Word = "word",
|
|
188
|
-
End = "end",
|
|
189
|
-
Pause = "pause",
|
|
190
|
-
Sajdah = "sajdah",
|
|
191
|
-
RubElHizb = "rub-el-hizb"
|
|
164
|
+
declare enum SearchNavigationType {
|
|
165
|
+
SURAH = "surah",
|
|
166
|
+
JUZ = "juz",
|
|
167
|
+
HIZB = "hizb",
|
|
168
|
+
AYAH = "ayah",
|
|
169
|
+
RUB_EL_HIZB = "rub_el_hizb",
|
|
170
|
+
SEARCH_PAGE = "search_page",
|
|
171
|
+
PAGE = "page",
|
|
172
|
+
RANGE = "range",
|
|
173
|
+
QURAN_RANGE = "quran_range"
|
|
192
174
|
}
|
|
193
|
-
interface
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
pageNumber?: number;
|
|
201
|
-
lineNumber?: number;
|
|
202
|
-
text?: string;
|
|
203
|
-
textUthmani?: string;
|
|
204
|
-
textIndopak?: string;
|
|
205
|
-
textImlaei?: string;
|
|
206
|
-
translation: Translation;
|
|
207
|
-
transliteration: Transliteration;
|
|
208
|
-
location?: string;
|
|
209
|
-
verseKey?: VerseKey;
|
|
175
|
+
interface SearchResult {
|
|
176
|
+
resultType: SearchNavigationType;
|
|
177
|
+
key: number | string;
|
|
178
|
+
name: string;
|
|
179
|
+
arabic?: string;
|
|
180
|
+
isArabic?: boolean;
|
|
181
|
+
isTransliteration?: boolean;
|
|
210
182
|
}
|
|
211
183
|
|
|
212
184
|
interface SearchResponse {
|
|
213
|
-
|
|
214
|
-
query: string;
|
|
215
|
-
totalResults: number;
|
|
185
|
+
pagination: {
|
|
216
186
|
currentPage: number;
|
|
187
|
+
nextPage: number | null;
|
|
188
|
+
perPage: number;
|
|
217
189
|
totalPages: number;
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
words: Word[];
|
|
224
|
-
translations: Translation[];
|
|
225
|
-
}[];
|
|
190
|
+
totalRecords: number;
|
|
191
|
+
};
|
|
192
|
+
result?: {
|
|
193
|
+
navigation: SearchResult[];
|
|
194
|
+
verses: SearchResult[];
|
|
226
195
|
};
|
|
227
196
|
}
|
|
228
197
|
|
|
@@ -329,6 +298,54 @@ interface TafsirInfo {
|
|
|
329
298
|
translatedName: TranslatedName;
|
|
330
299
|
}
|
|
331
300
|
|
|
301
|
+
interface Translation {
|
|
302
|
+
id?: number;
|
|
303
|
+
text: string;
|
|
304
|
+
resourceId: number;
|
|
305
|
+
resourceName?: string;
|
|
306
|
+
verseId?: number;
|
|
307
|
+
languageId?: number;
|
|
308
|
+
languageName?: string;
|
|
309
|
+
verseKey?: VerseKey;
|
|
310
|
+
chapterId?: number;
|
|
311
|
+
verseNumber?: number;
|
|
312
|
+
juzNumber?: number;
|
|
313
|
+
hizbNumber?: number;
|
|
314
|
+
rubNumber?: number;
|
|
315
|
+
pageNumber?: number;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
interface Transliteration {
|
|
319
|
+
languageName?: string;
|
|
320
|
+
text?: string;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
declare enum CharType {
|
|
324
|
+
Word = "word",
|
|
325
|
+
End = "end",
|
|
326
|
+
Pause = "pause",
|
|
327
|
+
Sajdah = "sajdah",
|
|
328
|
+
RubElHizb = "rub-el-hizb"
|
|
329
|
+
}
|
|
330
|
+
interface Word {
|
|
331
|
+
id?: number;
|
|
332
|
+
position: number;
|
|
333
|
+
audioUrl: string;
|
|
334
|
+
charTypeName: CharType;
|
|
335
|
+
codeV1?: string;
|
|
336
|
+
codeV2?: string;
|
|
337
|
+
pageNumber?: number;
|
|
338
|
+
lineNumber?: number;
|
|
339
|
+
text?: string;
|
|
340
|
+
textUthmani?: string;
|
|
341
|
+
textIndopak?: string;
|
|
342
|
+
textImlaei?: string;
|
|
343
|
+
translation: Translation;
|
|
344
|
+
transliteration: Transliteration;
|
|
345
|
+
location?: string;
|
|
346
|
+
verseKey?: VerseKey;
|
|
347
|
+
}
|
|
348
|
+
|
|
332
349
|
interface Verse {
|
|
333
350
|
id: number;
|
|
334
351
|
verseNumber: number;
|
|
@@ -445,15 +462,6 @@ interface ChapterReciterResource {
|
|
|
445
462
|
filesSize?: number;
|
|
446
463
|
}
|
|
447
464
|
|
|
448
|
-
interface SearchResult {
|
|
449
|
-
verseKey: VerseKey;
|
|
450
|
-
verseId: number;
|
|
451
|
-
text: string;
|
|
452
|
-
highlighted?: string;
|
|
453
|
-
words: Word[];
|
|
454
|
-
translations: Translation[];
|
|
455
|
-
}
|
|
456
|
-
|
|
457
465
|
type ApiParams = Record<string, string | number | boolean | unknown[] | undefined | Record<string, boolean>>;
|
|
458
466
|
/**
|
|
459
467
|
* Base parameters that are common across most API endpoints
|
|
@@ -471,14 +479,47 @@ interface PaginationParams extends ApiParams {
|
|
|
471
479
|
/** Number of items per page */
|
|
472
480
|
perPage?: number;
|
|
473
481
|
}
|
|
482
|
+
type BinaryString = "0" | "1";
|
|
483
|
+
declare enum SearchMode {
|
|
484
|
+
Advanced = "advanced",
|
|
485
|
+
Quick = "quick"
|
|
486
|
+
}
|
|
474
487
|
/**
|
|
475
488
|
* Search parameters
|
|
476
489
|
*/
|
|
477
490
|
interface SearchParams extends BaseApiParams {
|
|
478
|
-
/**
|
|
479
|
-
|
|
491
|
+
/** Search mode */
|
|
492
|
+
mode: SearchMode;
|
|
493
|
+
/** Search query */
|
|
494
|
+
query: string;
|
|
495
|
+
/** Filter translations */
|
|
496
|
+
filterTranslations?: string | string[];
|
|
497
|
+
/** For advanced search, limit to exact matches */
|
|
498
|
+
exactMatchesOnly?: BinaryString;
|
|
499
|
+
/** Include text in the response */
|
|
500
|
+
getText?: BinaryString;
|
|
501
|
+
/** Include highlighted text */
|
|
502
|
+
highlight?: BinaryString;
|
|
503
|
+
/** Quick search navigational results count */
|
|
504
|
+
navigationalResultsNumber?: number;
|
|
505
|
+
/** Quick search verse results count */
|
|
506
|
+
versesResultsNumber?: number;
|
|
507
|
+
/** Comma-separated list of indexes */
|
|
508
|
+
indexes?: string | string[];
|
|
480
509
|
/** Page number for pagination */
|
|
481
510
|
page?: number;
|
|
511
|
+
/** Number of results to return */
|
|
512
|
+
size?: number;
|
|
513
|
+
/** Translation IDs to use for language detection */
|
|
514
|
+
translationIds?: string | number | Array<string | number>;
|
|
515
|
+
/** Quran fields to include in verse filters */
|
|
516
|
+
fields?: Partial<Record<VerseField, boolean>>;
|
|
517
|
+
/** Translation fields to include in verse filters */
|
|
518
|
+
translationFields?: Partial<Record<TranslationField, boolean>>;
|
|
519
|
+
/** Word fields to include in verse filters */
|
|
520
|
+
wordFields?: Partial<Record<WordField, boolean>>;
|
|
521
|
+
/** Include word data in verse filters */
|
|
522
|
+
words?: boolean;
|
|
482
523
|
}
|
|
483
524
|
|
|
484
525
|
/**
|
|
@@ -812,7 +853,7 @@ declare class QuranResources {
|
|
|
812
853
|
findVerseMedia(options?: GetResourceOptions): Promise<VerseMediaResource>;
|
|
813
854
|
}
|
|
814
855
|
|
|
815
|
-
type SearchOptions = SearchParams
|
|
856
|
+
type SearchOptions = Omit<SearchParams, "query">;
|
|
816
857
|
/**
|
|
817
858
|
* Search API methods
|
|
818
859
|
*/
|
|
@@ -821,16 +862,16 @@ declare class QuranSearch {
|
|
|
821
862
|
constructor(fetcher: QuranFetcher);
|
|
822
863
|
/**
|
|
823
864
|
* Search
|
|
824
|
-
* @description
|
|
825
|
-
* @param {string}
|
|
865
|
+
* @description /v1/search
|
|
866
|
+
* @param {string} query search query
|
|
826
867
|
* @param {SearchOptions} options
|
|
827
868
|
* @example
|
|
828
|
-
* client.search.search('نور')
|
|
829
|
-
* client.search.search('نور', {
|
|
830
|
-
* client.search.search('نور', {
|
|
831
|
-
* client.search.search('نور', {
|
|
869
|
+
* client.search.search('نور', { mode: SearchMode.Quick })
|
|
870
|
+
* client.search.search('نور', { mode: SearchMode.Advanced, exactMatchesOnly: '1' })
|
|
871
|
+
* client.search.search('نور', { mode: SearchMode.Quick, size: 10 })
|
|
872
|
+
* client.search.search('نور', { mode: SearchMode.Quick, page: 2 })
|
|
832
873
|
*/
|
|
833
|
-
search(
|
|
874
|
+
search(query: string, options: SearchOptions): Promise<SearchResponse>;
|
|
834
875
|
}
|
|
835
876
|
|
|
836
877
|
type GetVerseOptions = BaseApiParams & PaginationParams & {
|
|
@@ -1005,4 +1046,4 @@ declare const isValidQuranPage: (page: string | number) => page is PageNumber;
|
|
|
1005
1046
|
*/
|
|
1006
1047
|
declare const isValidVerseKey: (key: string) => key is VerseKey;
|
|
1007
1048
|
|
|
1008
|
-
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 };
|
|
1049
|
+
export { type ApiParams, type AudioResponse, type BaseApiParams, type BinaryString, 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, SearchMode, SearchNavigationType, 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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -161,68 +161,37 @@ type PageNumber = _PageNumber | NumberUnionToString<_PageNumber>;
|
|
|
161
161
|
type _RubNumber = NumberRange<1, 241>;
|
|
162
162
|
type RubNumber = _RubNumber | NumberUnionToString<_RubNumber>;
|
|
163
163
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
verseNumber?: number;
|
|
175
|
-
juzNumber?: number;
|
|
176
|
-
hizbNumber?: number;
|
|
177
|
-
rubNumber?: number;
|
|
178
|
-
pageNumber?: number;
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
interface Transliteration {
|
|
182
|
-
languageName?: string;
|
|
183
|
-
text?: string;
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
declare enum CharType {
|
|
187
|
-
Word = "word",
|
|
188
|
-
End = "end",
|
|
189
|
-
Pause = "pause",
|
|
190
|
-
Sajdah = "sajdah",
|
|
191
|
-
RubElHizb = "rub-el-hizb"
|
|
164
|
+
declare enum SearchNavigationType {
|
|
165
|
+
SURAH = "surah",
|
|
166
|
+
JUZ = "juz",
|
|
167
|
+
HIZB = "hizb",
|
|
168
|
+
AYAH = "ayah",
|
|
169
|
+
RUB_EL_HIZB = "rub_el_hizb",
|
|
170
|
+
SEARCH_PAGE = "search_page",
|
|
171
|
+
PAGE = "page",
|
|
172
|
+
RANGE = "range",
|
|
173
|
+
QURAN_RANGE = "quran_range"
|
|
192
174
|
}
|
|
193
|
-
interface
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
pageNumber?: number;
|
|
201
|
-
lineNumber?: number;
|
|
202
|
-
text?: string;
|
|
203
|
-
textUthmani?: string;
|
|
204
|
-
textIndopak?: string;
|
|
205
|
-
textImlaei?: string;
|
|
206
|
-
translation: Translation;
|
|
207
|
-
transliteration: Transliteration;
|
|
208
|
-
location?: string;
|
|
209
|
-
verseKey?: VerseKey;
|
|
175
|
+
interface SearchResult {
|
|
176
|
+
resultType: SearchNavigationType;
|
|
177
|
+
key: number | string;
|
|
178
|
+
name: string;
|
|
179
|
+
arabic?: string;
|
|
180
|
+
isArabic?: boolean;
|
|
181
|
+
isTransliteration?: boolean;
|
|
210
182
|
}
|
|
211
183
|
|
|
212
184
|
interface SearchResponse {
|
|
213
|
-
|
|
214
|
-
query: string;
|
|
215
|
-
totalResults: number;
|
|
185
|
+
pagination: {
|
|
216
186
|
currentPage: number;
|
|
187
|
+
nextPage: number | null;
|
|
188
|
+
perPage: number;
|
|
217
189
|
totalPages: number;
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
words: Word[];
|
|
224
|
-
translations: Translation[];
|
|
225
|
-
}[];
|
|
190
|
+
totalRecords: number;
|
|
191
|
+
};
|
|
192
|
+
result?: {
|
|
193
|
+
navigation: SearchResult[];
|
|
194
|
+
verses: SearchResult[];
|
|
226
195
|
};
|
|
227
196
|
}
|
|
228
197
|
|
|
@@ -329,6 +298,54 @@ interface TafsirInfo {
|
|
|
329
298
|
translatedName: TranslatedName;
|
|
330
299
|
}
|
|
331
300
|
|
|
301
|
+
interface Translation {
|
|
302
|
+
id?: number;
|
|
303
|
+
text: string;
|
|
304
|
+
resourceId: number;
|
|
305
|
+
resourceName?: string;
|
|
306
|
+
verseId?: number;
|
|
307
|
+
languageId?: number;
|
|
308
|
+
languageName?: string;
|
|
309
|
+
verseKey?: VerseKey;
|
|
310
|
+
chapterId?: number;
|
|
311
|
+
verseNumber?: number;
|
|
312
|
+
juzNumber?: number;
|
|
313
|
+
hizbNumber?: number;
|
|
314
|
+
rubNumber?: number;
|
|
315
|
+
pageNumber?: number;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
interface Transliteration {
|
|
319
|
+
languageName?: string;
|
|
320
|
+
text?: string;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
declare enum CharType {
|
|
324
|
+
Word = "word",
|
|
325
|
+
End = "end",
|
|
326
|
+
Pause = "pause",
|
|
327
|
+
Sajdah = "sajdah",
|
|
328
|
+
RubElHizb = "rub-el-hizb"
|
|
329
|
+
}
|
|
330
|
+
interface Word {
|
|
331
|
+
id?: number;
|
|
332
|
+
position: number;
|
|
333
|
+
audioUrl: string;
|
|
334
|
+
charTypeName: CharType;
|
|
335
|
+
codeV1?: string;
|
|
336
|
+
codeV2?: string;
|
|
337
|
+
pageNumber?: number;
|
|
338
|
+
lineNumber?: number;
|
|
339
|
+
text?: string;
|
|
340
|
+
textUthmani?: string;
|
|
341
|
+
textIndopak?: string;
|
|
342
|
+
textImlaei?: string;
|
|
343
|
+
translation: Translation;
|
|
344
|
+
transliteration: Transliteration;
|
|
345
|
+
location?: string;
|
|
346
|
+
verseKey?: VerseKey;
|
|
347
|
+
}
|
|
348
|
+
|
|
332
349
|
interface Verse {
|
|
333
350
|
id: number;
|
|
334
351
|
verseNumber: number;
|
|
@@ -445,15 +462,6 @@ interface ChapterReciterResource {
|
|
|
445
462
|
filesSize?: number;
|
|
446
463
|
}
|
|
447
464
|
|
|
448
|
-
interface SearchResult {
|
|
449
|
-
verseKey: VerseKey;
|
|
450
|
-
verseId: number;
|
|
451
|
-
text: string;
|
|
452
|
-
highlighted?: string;
|
|
453
|
-
words: Word[];
|
|
454
|
-
translations: Translation[];
|
|
455
|
-
}
|
|
456
|
-
|
|
457
465
|
type ApiParams = Record<string, string | number | boolean | unknown[] | undefined | Record<string, boolean>>;
|
|
458
466
|
/**
|
|
459
467
|
* Base parameters that are common across most API endpoints
|
|
@@ -471,14 +479,47 @@ interface PaginationParams extends ApiParams {
|
|
|
471
479
|
/** Number of items per page */
|
|
472
480
|
perPage?: number;
|
|
473
481
|
}
|
|
482
|
+
type BinaryString = "0" | "1";
|
|
483
|
+
declare enum SearchMode {
|
|
484
|
+
Advanced = "advanced",
|
|
485
|
+
Quick = "quick"
|
|
486
|
+
}
|
|
474
487
|
/**
|
|
475
488
|
* Search parameters
|
|
476
489
|
*/
|
|
477
490
|
interface SearchParams extends BaseApiParams {
|
|
478
|
-
/**
|
|
479
|
-
|
|
491
|
+
/** Search mode */
|
|
492
|
+
mode: SearchMode;
|
|
493
|
+
/** Search query */
|
|
494
|
+
query: string;
|
|
495
|
+
/** Filter translations */
|
|
496
|
+
filterTranslations?: string | string[];
|
|
497
|
+
/** For advanced search, limit to exact matches */
|
|
498
|
+
exactMatchesOnly?: BinaryString;
|
|
499
|
+
/** Include text in the response */
|
|
500
|
+
getText?: BinaryString;
|
|
501
|
+
/** Include highlighted text */
|
|
502
|
+
highlight?: BinaryString;
|
|
503
|
+
/** Quick search navigational results count */
|
|
504
|
+
navigationalResultsNumber?: number;
|
|
505
|
+
/** Quick search verse results count */
|
|
506
|
+
versesResultsNumber?: number;
|
|
507
|
+
/** Comma-separated list of indexes */
|
|
508
|
+
indexes?: string | string[];
|
|
480
509
|
/** Page number for pagination */
|
|
481
510
|
page?: number;
|
|
511
|
+
/** Number of results to return */
|
|
512
|
+
size?: number;
|
|
513
|
+
/** Translation IDs to use for language detection */
|
|
514
|
+
translationIds?: string | number | Array<string | number>;
|
|
515
|
+
/** Quran fields to include in verse filters */
|
|
516
|
+
fields?: Partial<Record<VerseField, boolean>>;
|
|
517
|
+
/** Translation fields to include in verse filters */
|
|
518
|
+
translationFields?: Partial<Record<TranslationField, boolean>>;
|
|
519
|
+
/** Word fields to include in verse filters */
|
|
520
|
+
wordFields?: Partial<Record<WordField, boolean>>;
|
|
521
|
+
/** Include word data in verse filters */
|
|
522
|
+
words?: boolean;
|
|
482
523
|
}
|
|
483
524
|
|
|
484
525
|
/**
|
|
@@ -812,7 +853,7 @@ declare class QuranResources {
|
|
|
812
853
|
findVerseMedia(options?: GetResourceOptions): Promise<VerseMediaResource>;
|
|
813
854
|
}
|
|
814
855
|
|
|
815
|
-
type SearchOptions = SearchParams
|
|
856
|
+
type SearchOptions = Omit<SearchParams, "query">;
|
|
816
857
|
/**
|
|
817
858
|
* Search API methods
|
|
818
859
|
*/
|
|
@@ -821,16 +862,16 @@ declare class QuranSearch {
|
|
|
821
862
|
constructor(fetcher: QuranFetcher);
|
|
822
863
|
/**
|
|
823
864
|
* Search
|
|
824
|
-
* @description
|
|
825
|
-
* @param {string}
|
|
865
|
+
* @description /v1/search
|
|
866
|
+
* @param {string} query search query
|
|
826
867
|
* @param {SearchOptions} options
|
|
827
868
|
* @example
|
|
828
|
-
* client.search.search('نور')
|
|
829
|
-
* client.search.search('نور', {
|
|
830
|
-
* client.search.search('نور', {
|
|
831
|
-
* client.search.search('نور', {
|
|
869
|
+
* client.search.search('نور', { mode: SearchMode.Quick })
|
|
870
|
+
* client.search.search('نور', { mode: SearchMode.Advanced, exactMatchesOnly: '1' })
|
|
871
|
+
* client.search.search('نور', { mode: SearchMode.Quick, size: 10 })
|
|
872
|
+
* client.search.search('نور', { mode: SearchMode.Quick, page: 2 })
|
|
832
873
|
*/
|
|
833
|
-
search(
|
|
874
|
+
search(query: string, options: SearchOptions): Promise<SearchResponse>;
|
|
834
875
|
}
|
|
835
876
|
|
|
836
877
|
type GetVerseOptions = BaseApiParams & PaginationParams & {
|
|
@@ -1005,4 +1046,4 @@ declare const isValidQuranPage: (page: string | number) => page is PageNumber;
|
|
|
1005
1046
|
*/
|
|
1006
1047
|
declare const isValidVerseKey: (key: string) => key is VerseKey;
|
|
1007
1048
|
|
|
1008
|
-
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 };
|
|
1049
|
+
export { type ApiParams, type AudioResponse, type BaseApiParams, type BinaryString, 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, SearchMode, SearchNavigationType, 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 };
|
package/dist/index.min.js
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
'use strict';var
|
|
2
|
-
exports.CharType=
|
|
1
|
+
'use strict';var z=require('humps');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var z__default=/*#__PURE__*/_interopDefault(z);var B=(n=>(n.Word="word",n.End="end",n.Pause="pause",n.Sajdah="sajdah",n.RubElHizb="rub-el-hizb",n))(B||{});var G=(p=>(p.SURAH="surah",p.JUZ="juz",p.HIZB="hizb",p.AYAH="ayah",p.RUB_EL_HIZB="rub_el_hizb",p.SEARCH_PAGE="search_page",p.PAGE="page",p.RANGE="range",p.QURAN_RANGE="quran_range",p))(G||{});var U=(t=>(t.Advanced="advanced",t.Quick="quick",t))(U||{});var V=(r=>(r.ARABIC="ar",r.ENGLISH="en",r.URDU="ur",r.BENGALI="bn",r.TURKISH="tr",r.SPANISH="es",r.GERMAN="de",r.BOSNIAN="bs",r.RUSSIAN="ru",r.ALBANIAN_AL="al",r.FRENCH="fr",r.DUTCH="nl",r.TAMIL="ta",r.TAJIK="tg",r.INDONESIAN="id",r.UZBEK="uz",r.VIETNAMESE="vi",r.CHINESE="zh",r.ITALIAN="it",r.JAPANESE="ja",r.MALAYALAM="ml",r.AMHARIC="am",r.KAZAKH="kk",r.PORTUGUESE="pt",r.TAGALOG="tl",r.THAI="th",r.KOREAN="ko",r.HINDI="hi",r.KURDISH="ku",r.HAUSA="ha",r.AZERI="az",r.SWAHILI="sw",r.PERSIAN="fa",r.SERBIAN="sr",r.MARANAO="mrn",r.AMAZIGH="zgh",r.ASSAMESE="as",r.BULGARIAN="bg",r.CHECHEN="ce",r.CZECH="cs",r.DIVEHI="dv",r.FINNISH="fi",r.GUJAARATI="gu",r.HEBREW="he",r.GEORGIAN="ka",r.CENTRAL_KHMER="km",r.GANDA="lg",r.MARATHI="mr",r.YORUBA="yo",r.MALAY="ms",r.NEPALI="ne",r.SWEDISH="sv",r.TELUGU="te",r.TATAR="tt",r.UYGHUR="ug",r.UKRAINIAN="uk",r.NORWEGIAN="no",r.OROMO="om",r.POLISH="pl",r.PASHTO="ps",r.ROMANIAN="ro",r.SINDHI="sd",r.NORTHERN_SAMI="se",r.SINHALA="si",r.SOMALI="so",r.ALBANIAN_SQ="sq",r))(V||{}),k=(s=>(s.MadaniV1="code_v1",s.MadaniV2="code_v2",s.Uthmani="text_uthmani",s))(k||{});var a=i=>{let e=typeof i=="number"?i:Number(i);return !(!e||e<=0||e>114)};var A=i=>{let e=typeof i=="number"?i:Number(i);return !(!e||e<=0||e>30)};var v=i=>{let e=typeof i=="number"?i:Number(i);return !(!e||e<=0||e>240)};var P=i=>{let e=typeof i=="number"?i:Number(i);return !(!e||e<=0||e>60)};var x=i=>{let e=typeof i=="number"?i:Number(i);return !(!e||e<=0||e>604)};var N={1:7,2:286,3:200,4:176,5:120,6:165,7:206,8:75,9:129,10:109,11:123,12:111,13:43,14:52,15:99,16:128,17:111,18:110,19:98,20:135,21:112,22:78,23:118,24:64,25:77,26:227,27:93,28:88,29:69,30:60,31:34,32:30,33:73,34:54,35:45,36:83,37:182,38:88,39:75,40:85,41:54,42:53,43:89,44:59,45:37,46:35,47:38,48:29,49:18,50:45,51:60,52:49,53:62,54:55,55:78,56:96,57:29,58:22,59:24,60:13,61:14,62:11,63:11,64:18,65:12,66:12,67:30,68:52,69:52,70:44,71:28,72:28,73:20,74:56,75:40,76:31,77:50,78:40,79:46,80:42,81:29,82:19,83:36,84:25,85:22,86:17,87:19,88:26,89:30,90:20,91:15,92:21,93:11,94:8,95:8,96:19,97:5,98:8,99:8,100:11,101:11,102:8,103:3,104:9,105:5,106:4,107:7,108:3,109:6,110:3,111:5,112:4,113:5,114:6};var h=i=>{let[e,t]=i.trim().split(":");if(!e||!t||!a(e))return false;let s=Number(t),o=N[e];return !(!s||s<=0||s>o)};var l=class{constructor(e){this.fetcher=e;}async findAllChapterRecitations(e,t){let{audioFiles:s}=await this.fetcher.fetch(`/content/api/v4/recitations/${e}`,t);return s}async findChapterRecitationById(e,t,s){if(!a(t))throw new Error("Invalid chapter id");let{audioFile:o}=await this.fetcher.fetch(`/content/api/v4/recitations/${e}/${t}`,s);return o}async findVerseRecitationsByChapter(e,t,s){if(!a(e))throw new Error("Invalid chapter id");return await this.fetcher.fetch(`/content/api/v4/recitations/${t}/by_chapter/${e}`,s)}async findVerseRecitationsByKey(e,t,s){if(!h(e))throw new Error("Invalid verse key");return await this.fetcher.fetch(`/content/api/v4/recitations/${t}/by_ayah/${e}`,s)}};var m=class{constructor(e){this.fetcher=e;}async findAll(e){let{chapters:t}=await this.fetcher.fetch("/content/api/v4/chapters",e);return t}async findById(e,t){if(!a(e))throw new Error("Invalid chapter id");let{chapter:s}=await this.fetcher.fetch(`/content/api/v4/chapters/${e}`,t);return s}async findInfoById(e,t){if(!a(e))throw new Error("Invalid chapter id");let{chapterInfo:s}=await this.fetcher.fetch(`/content/api/v4/chapters/${e}/info`,t);return s}};var T=async(i,e={retries:3})=>{let t;for(let s=0;s<=e.retries;s++)try{return await i()}catch(o){if(t=o,s===e.retries)throw t;await new Promise(n=>setTimeout(n,Math.pow(2,s)*1e3));}throw t};var{decamelize:w}=z__default.default,F=i=>i.startsWith("/")?i.slice(1):i,S=["wordFields","translationFields","fields"],E=new Set([...S,...S.map(i=>w(i))]),H=new Set(["navigationalResultsNumber","versesResultsNumber"]),O=i=>{if(!i)return "";let e=new URLSearchParams;for(let[t,s]of Object.entries(i)){if(s===void 0)continue;let o=H.has(t)?t:w(t);if(E.has(t)||E.has(o)){let n=Object.entries(s).filter(([,c])=>c).map(([c])=>w(c));n.length>0&&e.set(o,n.join(","));continue}typeof s=="string"?e.set(o,s):typeof s=="number"||typeof s=="boolean"?e.set(o,s.toString()):Array.isArray(s)&&e.set(o,s.join(","));}return e.size===0?"":`?${e.toString()}`};var{camelizeKeys:_}=z__default.default,u=class{constructor(e){this.config=e;}cachedToken=null;updateConfig(e){this.config=e;}getFetch(){let{fetch:e}=this.config,t=e??globalThis.fetch;if(typeof t!="function")throw new Error("No fetch function available. Please provide a fetch implementation or ensure global fetch is available.");return t}doFetch(...e){return this.getFetch()(...e)}async getAccessToken(){if(this.cachedToken&&this.cachedToken.expiresAt>Date.now()+3e4)return this.cachedToken.value;let{clientId:e,clientSecret:t,authBaseUrl:s}=this.config,o=btoa(`${e}:${t}`),n=new URLSearchParams({grant_type:"client_credentials",scope:"content"}).toString(),c=await T(()=>this.doFetch(`${s}/oauth2/token`,{method:"POST",headers:{Authorization:`Basic ${o}`,"Content-Type":"application/x-www-form-urlencoded",Accept:"application/json"},body:n}),{retries:3});if(!c.ok)throw new Error(`Token request failed: ${c.statusText}`);let f=await c.json(),I=Date.now()+f.expires_in*1e3;return this.cachedToken={value:f.access_token,expiresAt:I},this.cachedToken.value}clearCachedToken(){this.cachedToken=null;}makeUrl(e,t){let{contentBaseUrl:s}=this.config;return `${s}/${F(e)}${O(t)}`}async fetch(e,t){let{clientId:s,defaults:o}=this.config,n=await this.getAccessToken(),c=this.makeUrl(e,{...o,...t}),f=await this.doFetch(c,{headers:{"x-auth-token":n,"x-client-id":s,"Content-Type":"application/json"}});if(!f.ok||f.status>=400)throw new Error(`${f.status} ${f.statusText}`);let I=await f.json();return _(I)}};var d=class{constructor(e){this.fetcher=e;}async findAll(){let{juzs:e}=await this.fetcher.fetch("/content/api/v4/juzs");return e}};var y=class{constructor(e){this.fetcher=e;}async findAllRecitations(e){let{recitations:t}=await this.fetcher.fetch("/content/api/v4/resources/recitations",e);return t}async findAllTranslations(e){let{translations:t}=await this.fetcher.fetch("/content/api/v4/resources/translations",e);return t}async findAllTafsirs(e){let{tafsirs:t}=await this.fetcher.fetch("/content/api/v4/resources/tafsirs",e);return t}async findAllLanguages(e){let{languages:t}=await this.fetcher.fetch("/content/api/v4/resources/languages",e);return t}async findRecitationInfo(e,t){let{recitationInfo:s}=await this.fetcher.fetch(`/content/api/v4/resources/recitations/${e}/info`,t);return s}async findTranslationInfo(e,t){let{translationInfo:s}=await this.fetcher.fetch(`/content/api/v4/resources/translations/${e}/info`,t);return s}async findTafsirInfo(e,t){let{tafsirInfo:s}=await this.fetcher.fetch(`/content/api/v4/resources/tafsirs/${e}/info`,t);return s}async findAllChapterInfos(e){let{chapterInfos:t}=await this.fetcher.fetch("/content/api/v4/resources/chapter_infos",e);return t}async findAllChapterReciters(e){let{reciters:t}=await this.fetcher.fetch("/content/api/v4/resources/chapter_reciters",e);return t}async findAllRecitationStyles(e){let{recitationStyles:t}=await this.fetcher.fetch("/content/api/v4/resources/recitation_styles",e);return t}async findVerseMedia(e){let{verseMedia:t}=await this.fetcher.fetch("/content/api/v4/resources/verse_media",e);return t}};var R=class{constructor(e){this.fetcher=e;}async search(e,t){return this.fetcher.fetch("/v1/search",{query:e,size:30,...t})}};var b=class{constructor(e){this.fetcher=e;}async findByKey(e,t){if(!h(e))throw new Error("Invalid verse key");let{verse:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_key/${e}`,{words:false,...t});return s}async findByChapter(e,t){if(!a(e))throw new Error("Invalid chapter id");let{verses:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_chapter/${e}`,{words:false,...t});return s}async findByPage(e,t){if(!x(e))throw new Error("Invalid page number");let{verses:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_page/${e}`,{words:false,...t});return s}async findByJuz(e,t){if(!A(e))throw new Error("Invalid juz");let{verses:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_juz/${e}`,{words:false,...t});return s}async findByHizb(e,t){if(!P(e))throw new Error("Invalid hizb");let{verses:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_hizb/${e}`,{words:false,...t});return s}async findByRub(e,t){if(!v(e))throw new Error("Invalid rub");let{verses:s}=await this.fetcher.fetch(`/content/api/v4/verses/by_rub/${e}`,{words:false,...t});return s}async findRandom(e){let{verse:t}=await this.fetcher.fetch("/content/api/v4/verses/random",{words:false,...e});return t}};var C=class{config;fetcher;chapters;verses;juzs;audio;resources;search;constructor(e){this.config={contentBaseUrl:"https://apis.quran.foundation",authBaseUrl:"https://oauth2.quran.foundation",...e,defaults:{language:"ar",...e.defaults}},this.fetcher=new u(this.config),this.fetcher.getFetch(),this.chapters=new m(this.fetcher),this.verses=new b(this.fetcher),this.juzs=new d(this.fetcher),this.audio=new l(this.fetcher),this.resources=new y(this.fetcher),this.search=new R(this.fetcher);}getConfig(){return {...this.config}}updateConfig(e){this.config={...this.config,...e,defaults:{...this.config.defaults,...e.defaults}},this.fetcher.updateConfig(this.config);}clearCachedToken(){this.fetcher.clearCachedToken();}};
|
|
2
|
+
exports.CharType=B;exports.Language=V;exports.QuranClient=C;exports.QuranFont=k;exports.SearchMode=U;exports.SearchNavigationType=G;exports.isValidChapterId=a;exports.isValidHizb=P;exports.isValidJuz=A;exports.isValidQuranPage=x;exports.isValidRub=v;exports.isValidVerseKey=h;//# sourceMappingURL=index.min.js.map
|
|
3
3
|
//# sourceMappingURL=index.min.js.map
|