[codex] Add v4 content parity SDK methods

.changeset/v4-content-parity.md

@@ -0,0 +1,5 @@
+---
+"@quranjs/api": minor
+---
+
+Add typed v4 hadith reference SDK methods and expose the full chapter info response with resource selection support.

packages/api/mocks/handlers.ts

@@ -662,18 +662,62 @@ export const handlers = [
 
   http.get(
     "https://apis.quran.foundation/content/api/v4/chapters/:chapter_id/info",
-    () => {
+    ({ request }) => {
+      const url = new URL(request.url);
+      const includeResources =
+        url.searchParams.get("include_resources") === "true";
+      const resourceId = url.searchParams.get("resource_id");
+      const chapterInfoResourceId =
+        resourceId === "en-tafsir-ibn-ashur"
+          ? 167
+          : resourceId
+            ? Number(resourceId) || 58
+            : 58;
+      const chapterInfo =
+        resourceId === "missing-resource"
+          ? null
+          : {
+              id: 1,
+              chapter_id: 1,
+              language_name: "english",
+              resource_id: chapterInfoResourceId,
+              short_text:
+                "This Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.",
+              source:
+                "Sayyid Abul Ala Maududi - Tafhim al-Qur'an - The Meaning of the Quran",
+              text: "<h2>Name</h2>\r\n<p>This Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.</p>\r\n<h2>Period of Revelation</h2>...",
+            };
+
       return HttpResponse.json({
-        chapterInfo: {
-          id: 1,
-          chapter_id: 1,
-          language_name: "english",
-          short_text:
-            "This Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.",
-          source:
-            "Sayyid Abul Ala Maududi - Tafhim al-Qur'an - The Meaning of the Quran",
-          text: "<h2>Name</h2>\r\n<p>This Surah is named Al-Fatihah because of its subject-matter. Fatihah is that which opens a subject or a book or any other thing. In other words, Al-Fatihah is a sort of preface.</p>\r\n<h2>Period of Revelation</h2>...",
-        },
+        chapter_info: chapterInfo,
+        ...(includeResources
+          ? {
+              resources: [
+                {
+                  id: 58,
+                  name: "Chapter Info",
+                  author_name: "Sayyid Abul Ala Maududi",
+                  slug: "",
+                  language_name: "english",
+                  translated_name: {
+                    name: "Chapter Info",
+                    language_name: "english",
+                  },
+                },
+                {
+                  id: 167,
+                  name: "Tafsir al-Tahrir wa'l-Tanwir",
+                  author_name: "Ibn Ashur",
+                  slug: "en-tafsir-ibn-ashur",
+                  language_name: "english",
+                  translated_name: {
+                    name: "Tafsir al-Tahrir wa'l-Tanwir",
+                    language_name: "english",
+                  },
+                },
+              ],
+            }
+          : {}),
       });
     },
   ),
@@ -747,6 +791,91 @@ export const handlers = [
     },
   ),
 
+  http.get(
+    "https://apis.quran.foundation/content/api/v4/hadith_references/by_ayah/:ayah_key",
+    ({ params }) => {
+      return HttpResponse.json({
+        verse_key: params.ayah_key,
+        verse_number: 12,
+        chapter_number: 12,
+        language: "en",
+        direction: "ltr",
+        hadith_references: [
+          {
+            id: 10,
+            collection: "bukhari",
+            hadith_number: "1",
+            our_hadith_number: 1,
+            arabic_urn: 111,
+            english_urn: 211,
+            surah_number: 12,
+            ayah_start_number: 11,
+            ayah_end_number: 12,
+          },
+          {
+            id: 11,
+            collection: "muslim",
+            hadith_number: "3",
+            our_hadith_number: 1,
+            arabic_urn: 113,
+            english_urn: 213,
+            surah_number: 12,
+            ayah_start_number: 12,
+            ayah_end_number: 14,
+          },
+        ],
+      });
+    },
+  ),
+
+  http.get(
+    "https://apis.quran.foundation/content/api/v4/hadith_references/by_ayah/:ayah_key/hadiths",
+    () => {
+      return HttpResponse.json({
+        hadiths: [
+          {
+            urn: 201,
+            collection: "bukhari",
+            bookNumber: "1",
+            chapterId: "1",
+            hadithNumber: "1",
+            name: "Sahih al-Bukhari",
+            hadith: [
+              {
+                lang: "en",
+                chapterNumber: "1",
+                chapterTitle: "Revelation",
+                body: "Narrated Umar bin Al-Khattab:...",
+                urn: 31,
+                grades: [
+                  {
+                    graded_by: "Ahmad Muhammad Shakir",
+                    grade: "Sahih",
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+        page: 1,
+        limit: 4,
+        has_more: true,
+        language: "en",
+        direction: "ltr",
+      });
+    },
+  ),
+
+  http.get(
+    "https://apis.quran.foundation/content/api/v4/hadith_references/count_within_range",
+    () => {
+      return HttpResponse.json({
+        "12:12": 2,
+        "12:13": 2,
+      });
+    },
+  ),
+
   http.get(
     "https://apis.quran.foundation/content/api/v4/resources/verse_media",
     () => {

packages/api/src/runtime/create-client.ts

@@ -1,3 +1,4 @@
+import type { AuthService } from "@/generated/public-contracts";
 import type {
   ApiParams,
   ChapterId,
@@ -14,13 +15,13 @@ import type {
   VerseKey,
 } from "@/types";
 import { operationCatalog } from "@/generated/contracts";
-import type { AuthService } from "@/generated/public-contracts";
 import { toUserSession } from "@/lib/http-utils";
 import { createGeneratedGroups, createRawClient } from "@/lib/runtime-utils";
 import { replacePathParams } from "@/lib/url";
 import { QuranAudio } from "@/sdk/audio";
 import { QuranChapters } from "@/sdk/chapters";
 import { QuranFetcher } from "@/sdk/fetcher";
+import { QuranHadithReferences } from "@/sdk/hadith-references";
 import { QuranJuzs } from "@/sdk/juzs";
 import { QuranResources } from "@/sdk/resources";
 import { QuranSearch } from "@/sdk/search";
@@ -348,6 +349,7 @@ const createContentFacade = (
   verses: QuranVerses,
   juzs: QuranJuzs,
   audio: QuranAudio,
+  hadithReferences: QuranHadithReferences,
   resources: QuranResources,
   raw: Record<string, RawOperation>,
 ) => {
@@ -374,8 +376,18 @@ const createContentFacade = (
       get: (id: ChapterId, query?: ApiParams) => chapters.findById(id, query),
       getInfo: (id: ChapterId, query?: ApiParams) =>
         chapters.findInfoById(id, query),
+      getInfoResponse: (id: ChapterId, query?: ApiParams) =>
+        chapters.findInfoResponseById(id, query),
       list: (query?: ApiParams) => chapters.findAll(query),
     },
+    hadithReferences: {
+      byAyah: (key: VerseKey, query?: ApiParams) =>
+        hadithReferences.findByAyah(key, query),
+      countWithinRange: (from: VerseKey, to: VerseKey, query?: ApiParams) =>
+        hadithReferences.countWithinRange(from, to, query),
+      hadithsByAyah: (key: VerseKey, query?: ApiParams) =>
+        hadithReferences.findHadithsByAyah(key, query),
+    },
     juzs: {
       list: () => juzs.findAll(),
     },
@@ -439,6 +451,7 @@ export const createRuntimeClient = (
   const verses = new QuranVerses(fetcher);
   const juzs = new QuranJuzs(fetcher);
   const audio = new QuranAudio(fetcher);
+  const hadithReferences = new QuranHadithReferences(fetcher);
   const resources = new QuranResources(fetcher);
   const searchClient = new QuranSearch(fetcher);
 
@@ -465,6 +478,7 @@ export const createRuntimeClient = (
     verses,
     juzs,
     audio,
+    hadithReferences,
     resources,
     raw.content.v4,
   );
@@ -501,6 +515,7 @@ export const createRuntimeClient = (
       v4: contentV4,
     },
     getUserSession: () => fetcher.getUserSession(),
+    hadithReferences,
     juzs,
     oauth2: {
       ...oauth2V1,

packages/api/src/runtime/create-public-client.ts

@@ -1,11 +1,11 @@
+import type { AuthService } from "@/generated/public-contracts";
 import type {
   ApiParams,
   HTTPMethod,
   OperationRequest,
   PublicClientConfig,
   TokenResponse,
 } from "@/types";
-import type { AuthService } from "@/generated/public-contracts";
 import { publicOperationCatalog } from "@/generated/public-contracts";
 import { toUserSession } from "@/lib/http-utils";
 import { createGeneratedGroups, createRawClient } from "@/lib/runtime-utils";
@@ -357,6 +357,7 @@ export const createPublicRuntimeClient = (config: PublicClientConfig) => {
     clearCachedTokens: () => fetcher.clearCachedTokens(),
     content: serverOnlyGuard,
     getUserSession: () => fetcher.getUserSession(),
+    hadithReferences: serverOnlyGuard,
     juzs: serverOnlyGuard,
     oauth2: {
       ...oauth2V1,

packages/api/src/sdk/chapters.ts

@@ -3,11 +3,16 @@ import type {
   Chapter,
   ChapterId,
   ChapterInfo,
+  ChapterInfoResponse,
   QuranFetchClient,
 } from "@/types";
 import { isValidChapterId } from "@/utils";
 
 type GetChapterOptions = BaseApiParams;
+type GetChapterInfoOptions = BaseApiParams & {
+  resourceId?: string | number;
+  includeResources?: boolean;
+};
 
 /**
  * Chapters API methods
@@ -55,21 +60,38 @@ export class QuranChapters {
    * Get chapter info by id.
    * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
    * @param {ChapterId} id chapter id, minimum 1, maximum 114
-   * @param {GetChapterOptions} options
+   * @param {GetChapterInfoOptions} options
    * @example
    * client.chapters.findInfoById('1')
    * client.chapters.findInfoById('114')
    */
   async findInfoById(
     id: ChapterId,
-    options?: GetChapterOptions,
-  ): Promise<ChapterInfo> {
-    if (!isValidChapterId(id)) throw new Error("Invalid chapter id");
-
-    const { chapterInfo } = await this.fetcher.fetch<{
-      chapterInfo: ChapterInfo;
-    }>(`/content/api/v4/chapters/${id}/info`, options);
+    options?: GetChapterInfoOptions,
+  ): Promise<ChapterInfo | null> {
+    const { chapterInfo } = await this.findInfoResponseById(id, options);
 
     return chapterInfo;
   }
+
+  /**
+   * Get the full chapter info response, including available resources when requested.
+   * @description https://api-docs.quran.com/docs/quran.com_versioned/4.0.0/get-chapter-info
+   * @param {ChapterId} id chapter id, minimum 1, maximum 114
+   * @param {GetChapterInfoOptions} options
+   * @example
+   * client.chapters.findInfoResponseById('1', { includeResources: true })
+   * client.chapters.findInfoResponseById('1', { resourceId: 'en-tafsir-ibn-ashur' })
+   */
+  async findInfoResponseById(
+    id: ChapterId,
+    options?: GetChapterInfoOptions,
+  ): Promise<ChapterInfoResponse> {
+    if (!isValidChapterId(id)) throw new Error("Invalid chapter id");
+
+    return this.fetcher.fetch<ChapterInfoResponse>(
+      `/content/api/v4/chapters/${id}/info`,
+      options,
+    );
+  }
 }

packages/api/src/sdk/client.ts

@@ -14,6 +14,7 @@ import humps from "humps";
 
 import { QuranAudio } from "./audio";
 import { QuranChapters } from "./chapters";
+import { QuranHadithReferences } from "./hadith-references";
 import { QuranJuzs } from "./juzs";
 import { QuranResources } from "./resources";
 import { QuranSearch } from "./search";
@@ -132,6 +133,7 @@ export class QuranClient {
   public readonly verses: QuranVerses;
   public readonly juzs: QuranJuzs;
   public readonly audio: QuranAudio;
+  public readonly hadithReferences: QuranHadithReferences;
   public readonly resources: QuranResources;
   public readonly search: QuranSearch;
 
@@ -153,6 +155,7 @@ export class QuranClient {
     this.verses = new QuranVerses(this.fetcher);
     this.juzs = new QuranJuzs(this.fetcher);
     this.audio = new QuranAudio(this.fetcher);
+    this.hadithReferences = new QuranHadithReferences(this.fetcher);
     this.resources = new QuranResources(this.fetcher);
     this.search = new QuranSearch(this.fetcher);
   }