RlxChap2 · Oct 4, 2026 · Oct 4, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,24 +1,32 @@
 name: Documentation checks
 on:
-    pull_request:
-    push:
-        branches: [main]
+  pull_request:
+  push:
+    branches: [main]
 permissions:
-    contents: read
+  contents: read
 jobs:
-    validate:
-        strategy:
-            matrix:
-                os: [ubuntu-latest, windows-latest]
-        runs-on: ${{ matrix.os }}
-        steps:
-            - uses: actions/checkout@v4
-            - uses: pnpm/action-setup@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version: 24
-                  cache: pnpm
-            - run: pnpm install --frozen-lockfile
-            - run: pnpm check
-            - run: pnpm build
-            - run: pnpm broken-links
+  validate:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm build
+      - run: pnpm broken-links
+      - uses: actions/checkout@v7
+        with:
+          repository: BonyanOSS/Bonyan-API
+          ref: c851b1a610c5169d3bffd822ed68886338ea3067
+          path: work/api
+      - run: pnpm --dir work/api install --frozen-lockfile
+      - run: pnpm --dir work/api build
+      - run: pnpm check:api work/api
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.1.0 - 2026-10-04
+
+- Align English and Arabic endpoint descriptions, response schemas and examples with API commit c851b1a, package 2.1.0 and OpenAPI contract 3.0.0.
+- Document SDK 2.0.0: fixed search decoding, moshaf selection, prayer timezone, normalized types, validation and per-request cancellation.
+- Replace outdated provider, cache, audio, calendar, hadith-range and deployment guidance. Document native Cloudflare Workers and Node 24 API hosting.
+- Add checks for all 31 SDK operations against both HTTP adapters and both OpenAPI locales, including local fallback and error behavior.
+- Validate against published SDK 2.0.0, with its merged source revision and registry distribution integrity recorded.
+- Update compatible Mintlify, parser and YAML dependencies, pnpm and CI actions. Retain React 19.2.3 and TypeScript 6.0.3 for CLI/compiler compatibility.
diff --git a/README.md b/README.md
@@ -1,53 +1,25 @@
 # Bonyan documentation
 
-English and Arabic documentation for Bonyan API and its JavaScript/TypeScript SDK. The Mintlify site contains 31 HTTP operations per language.
+English and Arabic Mintlify documentation for Bonyan API and its JavaScript/TypeScript SDK. Docs 1.1.0 covers all 31 HTTP operations per language.
 
-## Run locally
+Reviewed API: `c851b1a610c5169d3bffd822ed68886338ea3067`. The API package is 2.1.0 while its OpenAPI and changelog label the normalized contract 3.0.0. Both labels are preserved in `sources.lock.json`; the generated reference describes the actual controllers.
 
-Use Node.js 22 or later and the pnpm version declared in package.json.
+Docs install the published SDK 2.0.0 from npm. The source revision and SHA-256, registry tarball URL and integrity are recorded in sources.lock.json; pnpm-lock.yaml pins the installed distribution.
+
+## Run
+
+Use Node.js 22.12 or later and pnpm 11.22.0, as declared in package.json.
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm dev
 ```
 
-Open the URL printed by the CLI. English starts at `/locales/en/introduction`; Arabic at `/locales/ar/introduction`.
-
-The local search dialog requires an authenticated Mintlify session (`pnpm exec mintlify login`). Page rendering, navigation and the API playground work without that session. Check hosted search after deploying through the connected Mintlify project.
-
-## Structure
-
-```text
-locales/
-  en/                       English documentation
-  api-reference/            API index and endpoint pages by module (generated)
-  concepts/                 Architecture, responses, search, caching, fallback, limits
-  guides/                   Integration, hosting, operations, maintenance
-  sdk/                      SDK guides and generated method table
-  openapi.yaml              English OpenAPI (generated)
-  ar/                       Identical structure, translated into Arabic
-assets/                     Supplied brand asset
-examples/search.mjs         Tested search compatibility helper
-patches/                    Pinned Mintlify Windows path correction
-scripts/
-  api-catalog.mjs            Endpoint metadata in both languages
-  api-schemas.mjs            Response contracts and field descriptions
-  generate-api.mjs           OpenAPI and endpoint generation
-  generate-index.mjs         API indexes and SDK method tables
-  check-docs.mjs             MDX, links, languages, schemas, SDK examples
-  check-source.mjs           Source revisions and GET route parity
-  search.test.mjs            Compatibility and error-path tests
-.github/workflows/docs.yml   CI validation
-docs.json                   Theme, language navigation, legacy redirects
-sources.lock.json           Reviewed source commits and package versions
-styles.css                  Arabic text direction, code isolation and diagram overflow
-```
+Open the CLI's preview URL. English starts at `/locales/en/introduction` and Arabic at `/locales/ar/introduction`. Local search requires `pnpm exec mintlify login`; page rendering, navigation and the playground do not require that session. Verify hosted search after publication.
 
-Published pages belong in a language directory. Every page must appear once in navigation and have a matching translation. Do not keep duplicate root-level guides.
+## Edit and check
 
-## Edit and verify
-
-Edit ordinary MDX guides in both languages. For endpoint changes, edit `scripts/api-catalog.mjs` and `scripts/api-schemas.mjs`, then regenerate:
+Edit ordinary MDX guides in both languages. Update `scripts/api-catalog.mjs` for endpoint parameters and bilingual descriptions, and `scripts/api-schemas.mjs` for response contracts. Then run:
 
 ```bash
 pnpm generate
@@ -56,40 +28,39 @@ pnpm build
 pnpm broken-links
 ```
 
-`pnpm check` verifies generated-file drift, OpenAPI 3.1, MDX compilation, internal links, redirects, language parity, TypeScript SDK examples and the search helper. `pnpm build` is Mintlify build validation, not standalone HTML export. Preview layout changes in both languages.
-
-`patches/` fixes a Windows path-separator mismatch in `@mintlify/link-rot` 3.0.1334 that otherwise marks valid nested links as broken. Keep the patch and lockfile together; remove the patch only after a newer CLI passes `pnpm broken-links` on Windows. React and React DOM are pinned to the same version to satisfy the CLI's rendering peers. The remaining deprecated packages are transitive CLI dependencies.
+`check` detects generated-file drift, validates both OpenAPI documents, compiles MDX, checks navigation/links/redirects and language parity, type-checks SDK examples, and tests the search example against the published SDK. `build` runs Mintlify validation, without exporting standalone HTML.
 
-For documentation-only installs, `pnpm install --frozen-lockfile --ignore-scripts --no-optional` skips optional native tools that these checks and the preview do not need.
+Build the reviewed API checkout, then verify real API controllers against the published SDK and both translated schemas:
 
 ```bash
+pnpm --dir /path/to/Bonyan-API build
+pnpm check:api /path/to/Bonyan-API
 node scripts/check-source.mjs /path/to/Bonyan-API /path/to/bonyan-sdk-js
 ```
 
-This command expects the revisions in `sources.lock.json`. Review changed controllers, services and types before updating the lock. Do not claim a hosted deployment uses an exact commit unless the deployment exposes it.
-
-## Platform decision
+`check:api` exercises every SDK operation against Fastify and the Worker entrypoint with synthetic upstream fixtures. It also checks local fallbacks, sparse hadith numbering and error propagation. It performs no live provider requests. CI builds the pinned API revision on Linux and Windows before running this check.
 
-Reviewed 7 September 2026. **Keep Mintlify.** The project already uses it, and it supports Arabic language navigation, RTL and OpenAPI request builders. Replacing the platform would not fix inaccurate source contracts. [Mintlify internationalization](https://www.mintlify.com/docs/guides/internationalization), [OpenAPI setup](https://www.mintlify.com/docs/api-playground/openapi-setup).
+The source check verifies the API revision and package version, SDK revision, source digest/version and installed package integrity and GET route parity. It detects unreviewed source changes; update the lock only after reviewing and testing them.
 
-| Option         | Project assessment                                                                                                                                                                                                                    |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Mintlify       | Selected: existing hosting workflow, language navigation, RTL and OpenAPI rendering. Translations live in this repository.                                                                                                            |
-| Docusaurus     | Suitable if independently hosted static documentation becomes a requirement. It supports i18n and RTL. Migration adds theme, search, hosting and API-reference integration work.                                                      |
-| nodejs/doc-kit | Uses API-shaped Markdown and a generator pipeline. The reviewed docs demonstrate multiple outputs. I did not establish an equivalent ready-to-use Arabic/RTL plus OpenAPI request-builder workflow, so it is not the selected target. |
-
-Sources: [Docusaurus i18n](https://docusaurus.io/docs/i18n/introduction), [doc-kit](https://doc-kit.nodejs.org/). Migration-effort estimates are project-specific judgments, not claims that alternatives cannot support these features.
-
-## Known source differences
+## Structure
 
-The public API uses `https://api.bonyanoss.org`, without the old `/bonyan-api/v1` prefix. SDK 1.0.2 has a search-envelope mismatch; `examples/search.mjs` avoids it. Public tafsir IDs differ from upstream IDs. See [source status](locales/en/guides/source-status.mdx) and [Arabic source status](locales/ar/guides/source-status.mdx).
+| Path | Purpose |
+| --- | --- |
+| `locales/en`, `locales/ar` | Translated guides, SDK reference and generated API pages/specifications. |
+| `scripts/api-catalog.mjs`, `scripts/api-schemas.mjs` | Source metadata for generated contracts. |
+| `scripts/generate-*.mjs` | API pages, OpenAPI and method tables. |
+| `scripts/check-*.mjs` | Documentation, source and API integration checks. |
+| `scripts/source-digest.mjs` | Portable source/archive fingerprinting. |
+| `examples/search.mjs` | Tested application helper using SDK search directly. |
+| `sources.lock.json` | Reviewed revisions, versions and hashes. |
+| `docs.json`, `styles.css` | Existing theme, bilingual navigation, redirects and RTL styling. |
 
-The conduct policy has no configured private reporting contact. A maintainer needs to provide one; no address is invented here.
+Published pages need a translation and exactly one navigation entry. Preview layout changes in both languages. Keep API JSON keys and SDK names unchanged in translations.
 
-## Publish
+## Tool compatibility
 
-Review and merge through the existing documentation repository workflow. Keep the current Mintlify project connected to this repository. The rework does not publish a deployment or change DNS. Legacy page URLs redirect through `docs.json`.
+Mintlify is updated to 4.2.981. React and React DOM remain 19.2.3 to match its CLI renderer; 19.3.0 caused an invalid-hook error. pnpm remains on the updated 11.22.0 line because Mintlify rejects pnpm 12's multi-document lockfile. TypeScript remains 6.0.3 because checks use its JavaScript compiler API, which the current TypeScript 7 package does not expose. The remaining deprecated packages belong to the CLI's transitive dependencies.
 
-## العربية
+The Windows path correction now targets `@mintlify/link-rot` 3.0.1414. Without it, the updated checker incorrectly reports valid nested links as broken. Keep the patch and lockfile together; remove it only when a newer checker passes on Windows.
 
-المحتوى العربي في `locales/ar/` وله بنية `locales/en/` نفسها. عدّل الأدلة باللغتين، أو عدّل بيانات API المشتركة ثم شغّل `pnpm generate`. افحص باستخدام `pnpm check` و`pnpm build` و`pnpm broken-links`. راجع [دليل الصيانة](locales/ar/guides/maintenance.mdx) لمعرفة مصدر كل ملف وخطوات تحديث الترجمة.
+See [English source status](locales/en/guides/source-status.mdx) and [Arabic source status](locales/ar/guides/source-status.mdx).
diff --git a/examples/search.mjs b/examples/search.mjs
@@ -1,48 +1,19 @@
-import { BonyanApiError, BonyanRequestError } from "@bonyanoss/bonyan-api";
+import { BonyanClient, ValidationError } from "@bonyanoss/bonyan-api";
 
-// Compatibility helper for the flat search envelope returned by API 2.0.0.
+// Application helper using the supported SDK search methods.
 export async function searchContent(
   resource,
   text,
   {
     limit = 10,
     baseUrl = "https://api.bonyanoss.org",
-    fetch: fetchFn = globalThis.fetch,
+    fetch = globalThis.fetch,
     signal = AbortSignal.timeout(45000),
   } = {},
 ) {
-  if (!["ayat", "azkar"].includes(resource))
-    throw new TypeError("resource must be ayat or azkar");
-  const maximum = resource === "ayat" ? 500 : 200;
-  if (!Number.isInteger(limit) || limit < 1 || limit > maximum)
-    throw new RangeError("Invalid limit");
-  if (typeof text !== "string" || !/[\u0621-\u064A]/u.test(text))
-    throw new TypeError("Use an Arabic query");
-  const url = new URL(baseUrl.replace(/\/+$/, "") + "/" + resource + "/search");
-  url.searchParams.set("text", text);
-  url.searchParams.set("limit", String(limit));
-  let response;
-  try {
-    response = await fetchFn(url, {
-      signal,
-      headers: { Accept: "application/json" },
-    });
-  } catch (error) {
-    throw BonyanRequestError.from(error);
+  if (!["ayat", "azkar"].includes(resource)) {
+    throw new ValidationError("resource must be ayat or azkar", "resource");
   }
-  const body = await response.json().catch(() => null);
-  if (!response.ok)
-    throw BonyanApiError.fromResponse(
-      response.status,
-      body,
-      response.statusText,
-    );
-  if (
-    body?.success !== true ||
-    !Array.isArray(body.data) ||
-    !Number.isInteger(body.total)
-  ) {
-    throw new BonyanRequestError("Unexpected search response", body);
-  }
-  return { total: body.total, results: body.data };
+  const client = new BonyanClient({ baseUrl, fetch, timeoutMs: 45000, retry: 0 });
+  return client[resource].search(text, { limit }, { signal });
 }
diff --git a/locales/ar/api-reference/ayat/all.mdx b/locales/ar/api-reference/ayat/all.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/ayat/ayat.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/ayat/ayat.controller.ts)
diff --git a/locales/ar/api-reference/ayat/get-by-number.mdx b/locales/ar/api-reference/ayat/get-by-number.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/ayat/ayat.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/ayat/ayat.controller.ts)
diff --git a/locales/ar/api-reference/ayat/get-by-surah-aya.mdx b/locales/ar/api-reference/ayat/get-by-surah-aya.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/ayat/ayat.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/ayat/ayat.controller.ts)
diff --git a/locales/ar/api-reference/ayat/search.mdx b/locales/ar/api-reference/ayat/search.mdx
@@ -1,13 +1,9 @@
 ---
 title: "البحث في نص القرآن"
-description: "يعيد {success, total, data: [...]}. يحسب total النتائج المعادة بعد تطبيق الحد، وليس جميع التطابقات في القرآن."
+description: "يعيد {success, total, data: [...]}؛ total هو عدد النتائج المعادة بعد limit. كل نتيجة تحتوي apiName."
 openapi: "locales/ar/openapi.yaml GET /ayat/search"
 ---
 
-<Warning>
-توجد مشكلة في فك الاستجابة داخل client.ayat.search() في SDK 1.0.2. استخدم مثال fetch هنا أو الدالة البديلة في دليل SDK.
-</Warning>
-
 ## مثال الطلب
 
 <CodeGroup>
@@ -28,6 +24,14 @@ const body = await response.json();
 console.log(body);
 ```
 
+```ts SDK
+import { BonyanClient } from '@bonyanoss/bonyan-api';
+
+const client = new BonyanClient({ timeoutMs: 45000, retry: 1 });
+const result = await client.ayat.search('الرحمن', { limit: 10 });
+console.log(result);
+```
+
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/ayat/ayat.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/ayat/ayat.controller.ts)
diff --git a/locales/ar/api-reference/azkar/categories.mdx b/locales/ar/api-reference/azkar/categories.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/azkar/azkar.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/azkar/azkar.controller.ts)
diff --git a/locales/ar/api-reference/azkar/category.mdx b/locales/ar/api-reference/azkar/category.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/azkar/azkar.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/azkar/azkar.controller.ts)
diff --git a/locales/ar/api-reference/azkar/random.mdx b/locales/ar/api-reference/azkar/random.mdx
@@ -30,4 +30,4 @@ console.log(result);
 
 </CodeGroup>
 
-[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/azkar/azkar.controller.ts)
+[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/azkar/azkar.controller.ts)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,4 +30,4 @@ console.log(result);

		</CodeGroup>

		[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/e76bc4e114f2f174bc93d0c7f90b163f0721a9f4/src/modules/ayat/ayat.controller.ts)
		[الاستجابات والأخطاء](/locales/ar/concepts/errors) · [دليل SDK](/locales/ar/sdk/overview) · [كود المسار](https://github.com/BonyanOSS/Bonyan-API/blob/c851b1a610c5169d3bffd822ed68886338ea3067/src/modules/ayat/ayat.controller.ts)