Migrate and Modernize SDK Documentation for Quran Foundation API

docs/sdk/authentication.md

@@ -0,0 +1,28 @@
+---
+id: authentication
+title: "🔑 Authentication"
+sidebar_label: Authentication
+---
+
+The SDK uses the OAuth2 **Client Credentials** flow behind the scenes. Once you call `configure` with your `clientId` and `clientSecret`, every request automatically obtains and refreshes an access token.
+
+## How it works
+
+1. The SDK requests a token using the [OAuth2 Token Exchange endpoint](https://api-docs.quran.foundation/docs/oauth2_apis_versioned/oauth-2-token-exchange).
+2. Tokens are cached until 30 seconds before expiry.
+3. All API calls include the `x-auth-token` and `x-client-id` headers for you.
+
+You generally do not need to handle tokens manually. If you wish to override the fetch implementation (for example in React Native), pass a custom `fetchFn` during configuration:
+
+```javascript
+import { configure } from '@quranjs/api';
+import fetch from 'cross-fetch';
+
+configure({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  fetchFn: fetch,
+});
+```
+
+For details on the OAuth2 endpoints themselves, see the [Token Exchange documentation](https://api-docs.quran.foundation/docs/oauth2_apis_versioned/oauth-2-token-exchange).

docs/sdk/endpoints.md

@@ -0,0 +1,17 @@
+---
+id: endpoints
+title: "🗂️ Endpoint Reference"
+sidebar_label: Endpoint Reference
+---
+
+Below is an overview of the main API groups exposed via the SDK. Each link points to the full API documentation on api-docs.quran.foundation.
+
+- **Chapters** – [List Chapters](https://api-docs.quran.foundation/docs/content_apis_versioned/list-chapters), [Get Chapter](https://api-docs.quran.foundation/docs/content_apis_versioned/get-chapter), [Chapter Info](https://api-docs.quran.foundation/docs/content_apis_versioned/info)
+- **Verses** – [Verses by Chapter](https://api-docs.quran.foundation/docs/content_apis_versioned/verses-by-chapter-number), [Verses by Key](https://api-docs.quran.foundation/docs/content_apis_versioned/verses-by-verse-key), [Random Verse](https://api-docs.quran.foundation/docs/content_apis_versioned/random-verse) and others
+- **Juzs** – [List Juzs](https://api-docs.quran.foundation/docs/content_apis_versioned/juzs)
+- **Audio** – [Chapter Recitation Files](https://api-docs.quran.foundation/docs/content_apis_versioned/chapter-reciter-audio-files), [Verse Recitations](https://api-docs.quran.foundation/docs/content_apis_versioned/list-surah-recitation)
+- **Resources** – [Translations](https://api-docs.quran.foundation/docs/content_apis_versioned/translations), [Tafsirs](https://api-docs.quran.foundation/docs/content_apis_versioned/tafsirs), [Languages](https://api-docs.quran.foundation/docs/content_apis_versioned/languages) and more
+- **Search** – [Search Endpoint](https://api-docs.quran.foundation/docs/content_apis_versioned/search)
+- **OAuth2** – [Token Endpoint](https://api-docs.quran.foundation/docs/oauth2_apis_versioned/token)
+
+For advanced query parameters and response schemas, consult the linked documentation.

docs/sdk/index.md

@@ -0,0 +1,49 @@
+---
+id: index
+title: "📦 SDK Overview"
+sidebar_label: SDK Overview
+---
+
+The Quran Foundation JavaScript SDK simplifies interaction with the [Quran Foundation API](https://api-docs.quran.foundation). It works in Node.js and modern browsers and handles authentication for you.
+
+## Installation
+
+```bash
+npm install @quranjs/api
+```
+
+or with Yarn:
+
+```bash
+yarn add @quranjs/api
+```
+
+or with pnpm:
+
+```bash
+pnpm add @quranjs/api
+```
+
+## Basic Setup
+
+Before using the SDK, configure it with your client credentials. You can obtain a **Client ID** and **Client Secret** from the [Request Access](https://api-docs.quran.foundation/request-access) page:
+
+```javascript
+import { configure, quran } from '@quranjs/api';
+
+configure({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+});
+```
+
+After configuration you can call the SDK methods directly. Tokens are fetched and refreshed automatically.
+
+### Example: list chapters
+
+```javascript
+const chapters = await quran.qf.chapters.findAll();
+console.log(chapters);
+```
+
+Continue to the [Authentication](authentication.md) guide for details on how tokens are managed.

docs/sdk/migration.md

@@ -0,0 +1,14 @@
+---
+id: migration
+title: "🛠️ Migrating from QuranJS API"
+sidebar_label: Migration Guide
+---
+
+If you previously used the `@quranjs/api` SDK against the Quran.com endpoints, switching to the new Quran Foundation API requires a few changes.
+
+1. **Base URLs** – The new SDK defaults to `https://apis.quran.foundation` and `https://oauth2.quran.foundation`. Remove any overrides pointing to quran.com.
+2. **Authentication** – OAuth2 is now mandatory. Calls without a valid token will fail. Make sure to call `configure` with both `clientId` and `clientSecret`.
+3. **API Differences** – Several endpoint paths have changed and some fields were renamed. Consult the [Endpoint Reference](endpoints.md) and the official API docs for the exact routes.
+4. **Utility Functions** – Validation helpers now live under `quran.utils` and return boolean values.
+
+Most method names remain the same, so in many cases updating the configuration and endpoint URLs is all that is needed.

docs/sdk/usage.md

@@ -0,0 +1,82 @@
+---
+id: usage
+title: "📚 SDK Usage"
+sidebar_label: Usage Examples
+---
+
+This page highlights the main wrappers exported by the SDK. All examples assume you have already called `configure`.
+
+## Chapters
+
+```javascript
+// List all chapters
+const chapters = await quran.qf.chapters.findAll();
+
+// Get a single chapter by ID
+const chapter = await quran.qf.chapters.findById('1');
+
+// Retrieve chapter information
+const info = await quran.qf.chapters.findInfoById('1');
+```
+
+## Verses
+
+```javascript
+// Get verses of a chapter
+const verses = await quran.qf.verses.findByChapter('1');
+
+// Fetch a verse by key
+const verse = await quran.qf.verses.findByKey('1:1');
+
+// Retrieve a random verse
+const random = await quran.qf.verses.findRandom();
+```
+
+Additional helpers include `findByPage`, `findByJuz`, `findByHizb` and `findByRub`.
+
+## Juzs
+
+```javascript
+const juzs = await quran.qf.juzs.findAll();
+```
+
+## Audio
+
+```javascript
+// All chapter recitations for a reciter
+const files = await quran.qf.audio.findAllChapterRecitations('2');
+
+// Verse recitations by chapter
+const recitations = await quran.qf.audio.findVerseRecitationsByChapter('1', '2');
+```
+
+Other helpers cover pages, hizbs, rubs and specific verses.
+
+## Resources
+
+```javascript
+// Available translations
+const translations = await quran.qf.resources.findAllTranslations();
+
+// Reciter information
+const reciterInfo = await quran.qf.resources.findRecitationInfo('1');
+```
+
+This wrapper also exposes methods for languages, tafsirs, recitation styles, chapter reciters and more.
+
+## Search
+
+```javascript
+const results = await quran.qf.search.search('mercy');
+```
+
+## Utilities
+
+```javascript
+import { quran } from '@quranjs/api';
+
+quran.utils.isValidVerseKey('2:255'); // true
+quran.utils.isValidChapterId('115'); // false
+```
+
+See the [Endpoint Reference](endpoints.md) for a list of API routes these wrappers use.

docusaurus.config.js

@@ -153,6 +153,12 @@ const config = {
             position: "left",
             label: "🚀 Quick Start",
           },
+          {
+            type: "doc",
+            docId: "sdk/index",
+            position: "left",
+            label: "SDK",
+          },
           {
             type: "doc",
             docId: "updates/index",

sidebars.js

@@ -57,6 +57,17 @@ const sidebars = {
       id: "quickstart/index", // ✅ Add here too if needed in sidebar
       label: "🚀 Quick Start Guide",
     },
+    {
+      type: "category",
+      label: "SDK",
+      link: { type: "doc", id: "sdk/index" },
+      items: [
+        "sdk/authentication",
+        "sdk/usage",
+        "sdk/endpoints",
+        "sdk/migration",
+      ],
+    },
 
     // {
     //   type: "html",