@quranjs/api 2.1.0 → 3.0.0

package/README.md

@@ -9,7 +9,10 @@ A JavaScript/TypeScript library for fetching **authentic, scholarly verified Qur
 
 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.
 
-Works seamlessly in both Node.js and browser environments.
+Works in both server and browser environments through separate runtime entrypoints:
+
+- `@quranjs/api/server`
+- `@quranjs/api/public`
 
 **Built by the [Quran Foundation](https://quran.foundation) — the team behind [Quran.com](https://quran.com)**
 
@@ -29,21 +32,38 @@ pnpm add @quranjs/api
 ## Quick Start
 
 ```typescript
-import { quran } from '@quranjs/api';
+import { SearchMode } from "@quranjs/api";
+import { createServerClient } from "@quranjs/api/server";
+
+const client = createServerClient({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+});
+
+const chapters = await client.content.v4.chapters.list();
+const results = await client.search.v1.query({
+  query: "mercy",
+  mode: SearchMode.Quick,
+});
+```
 
-// Get all chapters
-const chapters = await quran.v4.chapters.findAll();
+For browser or mobile apps, use `@quranjs/api/public`. Public usage docs live in the API docs portal.
 
-// Get a specific chapter
-const surah = await quran.v4.chapters.findById(1);
+Existing `QuranClient` imports from `@quranjs/api` remain supported for backwards compatibility:
 
-// Get verses of a chapter
-const verses = await quran.v4.verses.findByChapter(1);
+```typescript
+import { QuranClient } from "@quranjs/api";
 
-// Search the Quran
-const results = await quran.v4.search.search('mercy');
+const client = new QuranClient({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+});
+
+const chapters = await client.chapters.findAll();
 ```
 
+For new apps, prefer the runtime-specific `@quranjs/api/server` and `@quranjs/api/public` entrypoints.
+
 ## Documentation
 
 For complete documentation, guides, and API reference, visit:

package/dist/index-BZgqOfA4.d.mts

@@ -0,0 +1,228 @@
+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;
+}
+type BinaryString = "0" | "1";
+declare enum SearchMode {
+    Advanced = "advanced",
+    Quick = "quick"
+}
+/**
+ * Search parameters
+ */
+interface SearchParams extends BaseApiParams {
+    /** Search mode */
+    mode: SearchMode;
+    /** Search query */
+    query: string;
+    /** Filter translations */
+    filterTranslations?: string | string[];
+    /** For advanced search, limit to exact matches */
+    exactMatchesOnly?: BinaryString;
+    /** Include text in the response */
+    getText?: BinaryString;
+    /** Include highlighted text */
+    highlight?: BinaryString;
+    /** Quick search navigational results count */
+    navigationalResultsNumber?: number;
+    /** Quick search verse results count */
+    versesResultsNumber?: number;
+    /** Comma-separated list of indexes */
+    indexes?: string | string[];
+    /** Page number for pagination */
+    page?: number;
+    /** Number of results to return */
+    size?: number;
+    /** Translation IDs to use for language detection */
+    translationIds?: string | number | Array<string | number>;
+    /** Quran fields to include in verse filters */
+    fields?: Partial<Record<VerseField, boolean>>;
+    /** Translation fields to include in verse filters */
+    translationFields?: Partial<Record<TranslationField, boolean>>;
+    /** Word fields to include in verse filters */
+    wordFields?: Partial<Record<WordField, boolean>>;
+    /** Include word data in verse filters */
+    words?: boolean;
+}
+
+type AuthService = "auth" | "quranReflect";
+
+/**
+ * Custom fetcher function type that matches the native fetch API
+ */
+type CustomFetcher = typeof fetch;
+type RuntimeMode = "server" | "public";
+type HTTPMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+interface QuranFetchClient {
+    fetch<T = unknown>(url: string, params?: ApiParams): Promise<T>;
+}
+type ApiService = "content" | "search" | AuthService | "oauth2";
+interface ServiceEnvironmentConfig {
+    gatewayUrl?: string;
+    tokenHost?: string;
+    oauth2BaseUrl?: string;
+    contentBaseUrl?: string;
+    searchBaseUrl?: string;
+    authBaseUrl?: string;
+    quranReflectBaseUrl?: string;
+}
+interface QuranClientConfig {
+    /** Client ID for authentication */
+    clientId: string;
+    /** Client secret for authentication */
+    clientSecret: string;
+    /** Legacy gateway base URL for content/search APIs */
+    contentBaseUrl?: string;
+    /** Legacy OAuth2 token host URL */
+    authBaseUrl?: string;
+    /** Custom fetch implementation */
+    fetch?: CustomFetcher;
+    /** Default parameters for all API calls */
+    defaults?: Partial<BaseApiParams>;
+}
+interface UserSession {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    scope?: string;
+    tokenType?: string;
+    expiresAt?: number;
+}
+interface TokenStorage {
+    getSession?: () => UserSession | null | undefined | Promise<UserSession | null | undefined>;
+    setSession?: (session: UserSession | null) => void | Promise<void>;
+    clearSession?: () => void | Promise<void>;
+}
+interface BaseRuntimeClientConfig {
+    clientId: string;
+    fetch?: CustomFetcher;
+    defaults?: Partial<BaseApiParams>;
+    services?: ServiceEnvironmentConfig;
+    userSession?: UserSession;
+    storage?: TokenStorage;
+}
+interface ServerClientConfig extends BaseRuntimeClientConfig {
+    clientSecret: string;
+}
+interface PublicClientConfig extends BaseRuntimeClientConfig {
+    clientType: "public" | "confidential-proxy";
+}
+interface CachedToken {
+    value: string;
+    expiresAt: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface OperationRequest {
+    path?: Record<string, string | number>;
+    query?: ApiParams;
+    body?: string | URLSearchParams | Record<string, unknown> | null;
+    headers?: Record<string, string>;
+    method?: HTTPMethod;
+    auth?: "auto" | "none" | "app" | "user";
+    accessToken?: string;
+    basicAuth?: {
+        username: string;
+        password: string;
+    };
+    contentType?: string;
+}
+
+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";
+
+export { type ApiParams as A, type BaseApiParams as B, type CustomFetcher as C, type HTTPMethod as H, Language as L, type OperationRequest as O, type PaginationParams as P, type QuranClientConfig as Q, type RuntimeMode as R, SearchMode as S, type TranslationField as T, type UserSession as U, type VerseField as V, type WordField as W, QuranFont as a, type VerseRecitationField as b, type BinaryString as c, type SearchParams as d, type QuranFetchClient as e, type ApiService as f, type ServiceEnvironmentConfig as g, type TokenStorage as h, type ServerClientConfig as i, type PublicClientConfig as j, type CachedToken as k, type TokenResponse as l };

package/dist/index-BZgqOfA4.d.ts

@@ -0,0 +1,228 @@
+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;
+}
+type BinaryString = "0" | "1";
+declare enum SearchMode {
+    Advanced = "advanced",
+    Quick = "quick"
+}
+/**
+ * Search parameters
+ */
+interface SearchParams extends BaseApiParams {
+    /** Search mode */
+    mode: SearchMode;
+    /** Search query */
+    query: string;
+    /** Filter translations */
+    filterTranslations?: string | string[];
+    /** For advanced search, limit to exact matches */
+    exactMatchesOnly?: BinaryString;
+    /** Include text in the response */
+    getText?: BinaryString;
+    /** Include highlighted text */
+    highlight?: BinaryString;
+    /** Quick search navigational results count */
+    navigationalResultsNumber?: number;
+    /** Quick search verse results count */
+    versesResultsNumber?: number;
+    /** Comma-separated list of indexes */
+    indexes?: string | string[];
+    /** Page number for pagination */
+    page?: number;
+    /** Number of results to return */
+    size?: number;
+    /** Translation IDs to use for language detection */
+    translationIds?: string | number | Array<string | number>;
+    /** Quran fields to include in verse filters */
+    fields?: Partial<Record<VerseField, boolean>>;
+    /** Translation fields to include in verse filters */
+    translationFields?: Partial<Record<TranslationField, boolean>>;
+    /** Word fields to include in verse filters */
+    wordFields?: Partial<Record<WordField, boolean>>;
+    /** Include word data in verse filters */
+    words?: boolean;
+}
+
+type AuthService = "auth" | "quranReflect";
+
+/**
+ * Custom fetcher function type that matches the native fetch API
+ */
+type CustomFetcher = typeof fetch;
+type RuntimeMode = "server" | "public";
+type HTTPMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+interface QuranFetchClient {
+    fetch<T = unknown>(url: string, params?: ApiParams): Promise<T>;
+}
+type ApiService = "content" | "search" | AuthService | "oauth2";
+interface ServiceEnvironmentConfig {
+    gatewayUrl?: string;
+    tokenHost?: string;
+    oauth2BaseUrl?: string;
+    contentBaseUrl?: string;
+    searchBaseUrl?: string;
+    authBaseUrl?: string;
+    quranReflectBaseUrl?: string;
+}
+interface QuranClientConfig {
+    /** Client ID for authentication */
+    clientId: string;
+    /** Client secret for authentication */
+    clientSecret: string;
+    /** Legacy gateway base URL for content/search APIs */
+    contentBaseUrl?: string;
+    /** Legacy OAuth2 token host URL */
+    authBaseUrl?: string;
+    /** Custom fetch implementation */
+    fetch?: CustomFetcher;
+    /** Default parameters for all API calls */
+    defaults?: Partial<BaseApiParams>;
+}
+interface UserSession {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    scope?: string;
+    tokenType?: string;
+    expiresAt?: number;
+}
+interface TokenStorage {
+    getSession?: () => UserSession | null | undefined | Promise<UserSession | null | undefined>;
+    setSession?: (session: UserSession | null) => void | Promise<void>;
+    clearSession?: () => void | Promise<void>;
+}
+interface BaseRuntimeClientConfig {
+    clientId: string;
+    fetch?: CustomFetcher;
+    defaults?: Partial<BaseApiParams>;
+    services?: ServiceEnvironmentConfig;
+    userSession?: UserSession;
+    storage?: TokenStorage;
+}
+interface ServerClientConfig extends BaseRuntimeClientConfig {
+    clientSecret: string;
+}
+interface PublicClientConfig extends BaseRuntimeClientConfig {
+    clientType: "public" | "confidential-proxy";
+}
+interface CachedToken {
+    value: string;
+    expiresAt: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface OperationRequest {
+    path?: Record<string, string | number>;
+    query?: ApiParams;
+    body?: string | URLSearchParams | Record<string, unknown> | null;
+    headers?: Record<string, string>;
+    method?: HTTPMethod;
+    auth?: "auto" | "none" | "app" | "user";
+    accessToken?: string;
+    basicAuth?: {
+        username: string;
+        password: string;
+    };
+    contentType?: string;
+}
+
+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";
+
+export { type ApiParams as A, type BaseApiParams as B, type CustomFetcher as C, type HTTPMethod as H, Language as L, type OperationRequest as O, type PaginationParams as P, type QuranClientConfig as Q, type RuntimeMode as R, SearchMode as S, type TranslationField as T, type UserSession as U, type VerseField as V, type WordField as W, QuranFont as a, type VerseRecitationField as b, type BinaryString as c, type SearchParams as d, type QuranFetchClient as e, type ApiService as f, type ServiceEnvironmentConfig as g, type TokenStorage as h, type ServerClientConfig as i, type PublicClientConfig as j, type CachedToken as k, type TokenResponse as l };