Integrate SDK documentation and sync fixes-branch updates

docs/sdk/audio.mdx

@@ -0,0 +1,99 @@
+---
+title: Audio API
+description: Access Quran audio recitations from different reciters.
+slug: /sdk/audio
+---
+
+The Audio API provides access to audio recitations including chapter audio and verse-by-verse audio with timing.
+
+## Chapter Recitations
+
+### Get All Chapter Recitations
+
+```ts
+const recitations = await client.audio.findAllChapterRecitations("2");
+
+console.log(recitations[0]);
+// {
+//   id: 1,
+//   chapterId: 1,
+//   fileSize: 12345,
+//   format: "mp3",
+//   audioUrl: "https://audio.quran.com/..."
+// }
+```
+
+### ChapterRecitation Type
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `number` | Unique identifier for the chapter audio record. |
+| `chapterId` | `number` | Surah that the audio recitation belongs to. |
+| `fileSize` | `number` | File size in bytes. |
+| `format` | `string` | Audio format, typically `mp3`. |
+| `audioUrl` | `string` | Download URL for the chapter recitation. |
+
+### Get Specific Chapter
+
+```ts
+const audio = await client.audio.findChapterRecitationById("2", "1");
+
+console.log(`URL: ${audio.audioUrl}`);
+console.log(`Format: ${audio.format}`);
+```
+
+## Verse Recitations
+
+### By Chapter
+
+```ts
+const { audioFiles, pagination } = await client.audio.findVerseRecitationsByChapter(
+  "1",  // Chapter ID
+  "2"   // Recitation ID
+);
+
+audioFiles.forEach((audio) => {
+  console.log(`${audio.verseKey}: ${audio.url}`);
+});
+```
+
+### VerseRecitation Type
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `verseKey` | `string` | Verse identifier such as `2:255`. |
+| `url` | `string` | Direct URL to the verse audio file. |
+| `id` | `number` | Unique identifier for the verse recitation. |
+| `chapterId` | `number` | Surah that the verse belongs to. |
+| `segments` | `Segment[]` | Optional timing metadata for word-level playback. |
+| `format` | `string` | Audio format, e.g. `mp3`. |
+
+`Segment` entries include the timestamp ranges (`start`, `end`) that power word-level playback.
+
+### By Verse Key
+
+```ts
+const { audioFiles } = await client.audio.findVerseRecitationsByKey(
+  "2:255",
+  "2"
+);
+
+const audio = audioFiles[0];
+console.log(`URL: ${audio.url}`);
+console.log(`Format: ${audio.format ?? "stream"}`);
+```
+
+## Field Selection
+
+```ts
+const { audioFiles } = await client.audio.findVerseRecitationsByChapter("1", "2", {
+  fields: {
+    segments: true,
+    format: true,
+    id: true,
+    chapterId: false,
+  },
+});
+
+// Available verse fields: id, chapterId, segments, format
+```

docs/sdk/chapters.mdx

@@ -0,0 +1,78 @@
+---
+title: Chapters API
+description: Access Quran chapter (surah) information and metadata.
+slug: /sdk/chapters
+---
+
+The Chapters API provides access to information about the 114 chapters (surahs) of the Quran.
+
+## Get All Chapters
+
+```ts
+const chapters = await client.chapters.findAll();
+
+chapters.forEach((chapter) => {
+  console.log(`${chapter.id}. ${chapter.nameSimple} (${chapter.nameArabic})`);
+  console.log(`   Verses: ${chapter.versesCount}`);
+  console.log(`   Revelation: ${chapter.revelationPlace}`);
+});
+```
+
+### Chapter Type
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `number` | Sequential chapter identifier. |
+| `versesCount` | `number` | Total verses in the chapter. |
+| `bismillahPre` | `boolean` | Indicates if Bismillah precedes the chapter. |
+| `revelationOrder` | `number` | Order of revelation. |
+| `revelationPlace` | `string` | `meccan` or `medinan`. |
+| `pages` | `number[]` | Mushaf page range for the chapter. |
+| `nameComplex` | `string` | Full transliterated name (e.g., `Al-Baqarah`). |
+| `nameSimple` | `string` | Common English name. |
+| `transliteratedName` | `string` | Transliteration suitable for URLs. |
+| `nameArabic` | `string` | Arabic chapter name. |
+| `translatedName` | `TranslatedName` | Localized name with language metadata. |
+
+### With Language Options
+
+```ts
+import { Language } from "@quranjs/api";
+
+const arabicChapters = await client.chapters.findAll({
+  language: Language.ARABIC,
+});
+
+const urduChapters = await client.chapters.findAll({
+  language: Language.URDU,
+});
+```
+
+## Get Chapter by ID
+
+```ts
+const alFatiha = await client.chapters.findById("1");
+const alBaqarah = await client.chapters.findById("2");
+const anNas = await client.chapters.findById("114");
+```
+
+## Get Chapter Info
+
+```ts
+const info = await client.chapters.findInfoById("1");
+
+console.log(info.shortText); // Brief description
+console.log(info.text); // Full description
+console.log(info.source); // Source attribution
+```
+
+### ChapterInfo Type
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `number` | Unique identifier for the info record. |
+| `chapterId` | `number` | Chapter the info is associated with. |
+| `text` | `string` | Full descriptive text. |
+| `shortText` | `string` | Condensed overview for quick display. |
+| `source` | `string` | Attribution for the content. |
+| `languageName` | `string` | Language of the info text (e.g., `english`). |

docs/sdk/index.mdx

@@ -0,0 +1,109 @@
+---
+title: Getting Started
+description: Install and configure @quranjs/api - a TypeScript SDK for the Quran.com API.
+slug: /sdk
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Installation
+
+<Tabs groupId="sdk-install" queryString>
+  <TabItem value="npm" label="npm">
+
+  ```bash
+  npm install @quranjs/api
+  ```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+
+  ```bash
+  pnpm install @quranjs/api
+  ```
+
+  </TabItem>
+  <TabItem value="yarn" label="yarn">
+
+  ```bash
+  yarn add @quranjs/api
+  ```
+
+  </TabItem>
+  <TabItem value="bun" label="bun">
+
+  ```bash
+  bun add @quranjs/api
+  ```
+
+  </TabItem>
+</Tabs>
+
+## Quick Start
+
+```ts
+import { Language, QuranClient } from "@quranjs/api";
+
+// Initialize the client
+const client = new QuranClient({
+  clientId: process.env.QURAN_CLIENT_ID!,
+  clientSecret: process.env.QURAN_CLIENT_SECRET!,
+  defaults: {
+    language: Language.ENGLISH,
+  },
+});
+
+// Fetch all chapters
+const chapters = await client.chapters.findAll();
+
+// Get a specific verse
+const verse = await client.verses.findByKey("2:255", {
+  translations: [20],
+  words: true,
+});
+
+// Search
+const results = await client.search.search("light", {
+  language: Language.ENGLISH,
+  size: 10,
+});
+```
+
+## Environment Variables
+
+```bash
+# .env
+QURAN_CLIENT_ID=your_client_id
+QURAN_CLIENT_SECRET=your_client_secret
+```
+
+```ts
+const client = new QuranClient({
+  clientId: process.env.QURAN_CLIENT_ID!,
+  clientSecret: process.env.QURAN_CLIENT_SECRET!,
+});
+```
+
+## Runtime Configuration
+
+```ts
+// Get current config
+const config = client.getConfig();
+
+// Update config
+client.updateConfig({
+  defaults: { language: Language.ARABIC },
+});
+
+// Clear auth token
+client.clearCachedToken();
+```
+
+## Next Steps
+
+- [Chapters API](/docs/sdk/chapters)
+- [Verses API](/docs/sdk/verses)
+- [Audio API](/docs/sdk/audio)
+- [Resources API](/docs/sdk/resources)
+- [Migration Guide](/docs/sdk/migration)

docs/sdk/juzs.mdx

@@ -0,0 +1,51 @@
+---
+title: Juzs API
+description: Access information about the 30 Juzs (Para/Siparah) of the Quran.
+slug: /sdk/juzs
+---
+
+The Juzs API provides information about the 30 Juzs, which are traditional divisions of the Quran.
+
+## Get All Juzs
+
+```ts
+const juzs = await client.juzs.findAll();
+
+console.log(juzs[0]); // First Juz
+// {
+//   id: 1,
+//   juzNumber: 1,
+//   verseMapping: {
+//     "1:1": "1:7",
+//     "2:1": "2:141"
+//   },
+//   firstVerseId: 1,
+//   lastVerseId: 148,
+//   versesCount: 148
+// }
+```
+
+## Juz Type
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `number` | Unique identifier for the Juz. |
+| `juzNumber` | `number` | Juz sequence from 1 to 30. |
+| `verseMapping` | `Record<string, string>` | Maps start/end verse keys for each section within the Juz. |
+| `firstVerseId` | `number` | Identifier of the first verse in the Juz. |
+| `lastVerseId` | `number` | Identifier of the last verse in the Juz. |
+| `versesCount` | `number` | Total verses contained in the Juz. |
+
+## Understanding Verse Mapping
+
+```ts
+const juz = juzs[0];
+
+Object.entries(juz.verseMapping).forEach(([start, end]) => {
+  console.log(`${start} to ${end}`);
+});
+
+// Output:
+// 1:1 to 1:7     (Al-Fatiha complete)
+// 2:1 to 2:141   (First part of Al-Baqarah)
+```