Hosted API access is disabled on `al-quran-database.vercel.app` for now. Use the repository locally or self-host this project to run the API endpoints documented here.

SDK Guide

Verified JS/TS client for versioned REST and GraphQL. Package is ESM-only, targets Node 18+, and uses native fetch.

Install

npm install @faha1999/al-quran-database

Use inside browser apps, Next.js servers, edge runtimes, or Node services with native fetch against your own local or self-hosted API instance.

Defaults

`baseUrl` defaults to empty string. This makes same-origin calls, useful when app and API deploy together.

`apiVersion` defaults to `v1`.

REST helpers throw on non-2xx responses or unsuccessful API envelopes.

GraphQL helper throws when HTTP fails or response contains `errors`.

Configuration

Local Development

import { QuranDevSDK } from '@faha1999/al-quran-database';

const quran = new QuranDevSDK({
  baseUrl: 'http://localhost:3000',
  apiVersion: 'v1',
});

Self-Hosted API

import { QuranDevSDK } from '@faha1999/al-quran-database';

const quran = new QuranDevSDK({
  baseUrl: 'https://your-domain.example',
});

const surah = await quran.getSurah(1);

Usage

Surah + translation

const surah = await quran.getSurah(1, 'en.sahih');

console.log(surah.name_ar);
console.log(surah.ayahs[0]?.translation);

Ranked search

const { data: results, meta } = await quran.search('mercy', {
  language: 'en',
  limit: 5,
});

console.log(meta.total);
console.log(results[0]?.matched_identifiers);

Ayah with words and knowledge

const ayah = await quran.getAyah(1, 'en.sahih', true);
const knowledge = await quran.getKnowledge(1);

console.log(ayah.words?.[0]?.text);
console.log(knowledge.themes);

GraphQL

const data = await quran.graphql<{
  ayah: { text: string; knowledge: { themes: string[] } | null } | null;
}>({
  query: `
    query GetAyah($id: Int!) {
      ayah(id: $id, includeWords: true) {
        text
        knowledge {
          themes
        }
      }
    }
  `,
  variables: { id: 1 },
});

Method Coverage

getSurahs(page?, limit?)getSurah(id, edition?)getAyah(id, edition?, includeWords?)search(query, { edition?, language?, page?, limit? })getJuz(id, edition?)getHizb(id, edition?)getRub(id, edition?)getPage(id, edition?)getWords(ayahId)getDuas(page?, limit?)getReciters()getFaqs()getKnowledge(ayahId)getMeta()getResearchReferences()graphql({ query, variables? })

Public Exports

`QuranDevSDK` class

`quran` singleton instance

`QuranApiOptions`

`GraphqlRequest`

`MetaPayload`

public entity and response types from `quran-types`

Error Handling

try {
  await quran.getSurah(999999);
} catch (error) {
  console.error(error);
  // REST: "Quran API error: 404 Not Found" or envelope error text
}

try {
  await quran.graphql({ query: 'query { nope }' });
} catch (error) {
  console.error(error);
  // GraphQL: first error message from response
}