ROOT /

History

Enable CI/CD by adding .onedev-buildspec.yml

dist	Loading last commit info...
src
tests
.gitignore
README.md
package-lock.json
package.json
tsconfig.json
tsup.config.ts

README.md

Islamic Network SDK (JavaScript/TypeScript)

Typed SDK for the Islamic Network APIs (AlAdhan + AlQuran) designed to work in React, Next.js, and React Native.

Supported APIs:

AlAdhan (prayer times, Islamic calendar, qibla, Asma Al Husna)
AlQuran (surahs, ayahs, sections, editions, search, sajda, meta)

Installation

npm install @islamicnetwork/sdk
# or
pnpm add @islamicnetwork/sdk
# or
yarn add @islamicnetwork/sdk

Usage

AlAdhan

import { AlAdhanClient, AlAdhanRequests } from "@islamic-network/sdk";

const client = AlAdhanClient.create();

const request = new AlAdhanRequests.DailyPrayerTimesByCoordinatesRequest(
  "01-01-2025",
  51.5194682,
  -0.1360365,
  new AlAdhanRequests.PrayerTimesOptions()
);

const response = await client.prayerTimes().dailyByCoordinates(request);

console.log(response.data.timings.Fajr);

import { AlAdhanClient, AlAdhanRequests } from "@islamic-network/sdk";

const client = AlAdhanClient.create();

const qibla = await client.qibla().direction(
  new AlAdhanRequests.QiblaDirectionRequest(19.071017570421, 72.838622286762)
);

console.log(qibla.data.direction);

import { AlAdhanClient, AlAdhanRequests } from "@islamic-network/sdk";

const client = AlAdhanClient.create();

const asma = await client
  .asmaAlHusna()
  .byNumber(new AlAdhanRequests.AsmaAlHusnaByNumberRequest([1, 2, 3]));

console.log(asma.data[0]?.en.meaning);

Qibla Compass (Binary)

import { AlAdhanClient, AlAdhanRequests } from "@islamic-network/sdk";

const client = AlAdhanClient.create();
const image = await client
  .qibla()
  .compass(new AlAdhanRequests.QiblaCompassRequest(19.071017570421, 72.838622286762));

// Browser/React: build a Blob URL
const blob = new Blob([image.body], { type: image.contentType });
const url = URL.createObjectURL(blob);

AlQuran

import { AlQuranClient, AlQuranRequests } from "@islamic-network/sdk";

const client = AlQuranClient.create();

const ayah = await client.ayahByNumber(new AlQuranRequests.AyahByNumberRequest(5));
console.log(ayah.data.text);

const editions = await client.editions(new AlQuranRequests.EditionListRequest(null, "text", "en"));
console.log(editions.data[0]?.identifier);

Configuration

Both clients accept the same options:

import { AlAdhanClient } from "@islamic-network/sdk";

const client = AlAdhanClient.create({
  baseUrl: "https://api.aladhan.com/v1",
  defaultHeaders: { "X-App": "my-app" },
  defaultQuery: { iso8601: true },
  timeoutMs: 10_000,
  userAgent: "my-sdk-client",
  fetch: globalThis.fetch // optional, provide for custom environments
});

Notes

The SDK uses the global fetch implementation by default. Provide a custom fetch for non-standard environments.
Prayer timings preserve API field names (e.g., Fajr, Dhuhr, Firstthird).
Qibla compass requests return binary image data with a content type.
Integration tests call live API endpoints and retry once on 429 or network errors.

Testing

npm test

Integration tests call the live APIs. When a 429 or timeout occurs, the client retries once after 1 second.