Merge pull request #44 from basit3407/feature/verses-by-range-endpoint

feat(api): add support for verses/by_range endpoint

Author: osamasayed

packages/api/mocks/handlers.ts

@@ -45,6 +45,27 @@ export const handlers = [
     },
   ),
 
+  http.get(
+    "https://apis.quran.foundation/content/api/v4/verses/by_range",
+    ({ request }) => {
+      return HttpResponse.json({
+        verses: [
+          {
+            id: 1,
+            verse_number: 1,
+            page_number: 1,
+            verse_key: "1:1",
+            juz_number: 1,
+            hizb_number: 1,
+            rub_number: 1,
+            sajdah_type: null,
+            sajdah_number: null,
+          },
+        ],
+      });
+    },
+  ),
+
   http.get(
     "https://apis.quran.foundation/content/api/v4/chapters",
     ({ request }) => {

packages/api/src/sdk/verses.ts

@@ -62,6 +62,38 @@ export class QuranVerses {
     return verse;
   }
 
+  /**
+   * Get verses by range.
+   * @param {VerseKey} from start verse key (e.g., "1:1")
+   * @param {VerseKey} to end verse key (e.g., "1:7")
+   * @param {GetVerseOptions} options
+   * @example
+   * client.verses.findByRange('1:1', '1:7')
+   */
+  async findByRange(
+    from: VerseKey,
+    to: VerseKey,
+    options?: GetVerseOptions,
+  ): Promise<Verse[]> {
+    // We could validate keys here, but the API will also valid it.
+    // simpler to just pass through for now, or use isValidVerseKey if desired.
+    if (!isValidVerseKey(from) || !isValidVerseKey(to)) {
+      throw new Error("Invalid verse key");
+    }
+
+    const { verses } = await this.fetcher.fetch<{ verses: Verse[] }>(
+      "/content/api/v4/verses/by_range",
+      {
+        words: false, // verses-specific default
+        ...options,
+        from,
+        to,
+      },
+    );
+
+    return verses;
+  }
+
   /**
    * Get verses by chapter.
    * @param {ChapterId} id chapter id, minimum 1, maximum 114

packages/api/src/types/api/Tafsir.ts

@@ -4,4 +4,11 @@ export interface Tafsir {
   text?: string;
   resourceName?: string;
   languageName?: string;
+  slug?: string;
+  languageId?: number;
+  groupVerseKeyFrom?: string;
+  groupVerseKeyTo?: string;
+  groupTafsirId?: number;
+  startVerseId?: number;
+  endVerseId?: number;
 }

packages/api/test/verses.test.ts

@@ -60,6 +60,31 @@ describe("Verses API", () => {
     });
   });
 
+  describe("findByRange()", () => {
+    it("should return verses for valid range", async () => {
+      const response = await testClient.verses.findByRange(
+        VALID_VERSE_KEY,
+        VALID_VERSE_KEY,
+      );
+      expect(response).toBeInstanceOf(Array);
+      expect(response).toBeDefined();
+    });
+
+    it("should throw error when 'from' key is invalid", async () => {
+      await expect(
+        // @ts-expect-error - testing invalid verse key
+        testClient.verses.findByRange(INVALID_VERSE_KEY, VALID_VERSE_KEY),
+      ).rejects.toThrowError();
+    });
+
+    it("should throw error when 'to' key is invalid", async () => {
+      await expect(
+        // @ts-expect-error - testing invalid verse key
+        testClient.verses.findByRange(VALID_VERSE_KEY, INVALID_VERSE_KEY),
+      ).rejects.toThrowError();
+    });
+  });
+
   describe("findByPage()", () => {
     it("should return an array of verses for valid page", async () => {
       const response = await testClient.verses.findByPage(VALID_PAGE_NUMBER);