[codex] Add v4 content parity SDK methods#53
Merged
Conversation
Contributor
size-limit report 📦
|
There was a problem hiding this comment.
Pull request overview
Updates @quranjs/api to match recently-added v4 Content API capabilities by adding first-class typed SDK surfaces (and runtime-facade exposure) for chapter-info resource selection and hadith reference endpoints, plus contract coverage for grouped tafsir list operations.
Changes:
- Added typed v4 Hadith References SDK module + runtime facade wiring (server-only guarded for public runtime).
- Extended Chapters SDK to support
resourceId/includeResources, and added a full-responsefindInfoResponseByIdmethod (nullablechapterInfo). - Updated MSW mocks, unit tests, and operation-contract representative coverage; added a changeset for release.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/api/test/hadith-references.test.ts | Adds unit coverage for new hadith references SDK methods and runtime facade exposure. |
| packages/api/test/contracts.test.ts | Extends representative operations coverage for hadith references + grouped tafsir list operation names/paths. |
| packages/api/test/chapters.test.ts | Adds coverage for resourceId, includeResources, and nullable chapterInfo behavior. |
| packages/api/src/types/api/index.ts | Re-exports new Hadith Reference API types. |
| packages/api/src/types/api/HadithReference.ts | Introduces typed response shapes for hadith references, hadith payloads, and range counts. |
| packages/api/src/types/api/ChapterInfo.ts | Adds resourceId and full ChapterInfoResponse shape with optional resources list. |
| packages/api/src/sdk/hadith-references.ts | Implements typed SDK methods for hadith reference endpoints with verse-key validation. |
| packages/api/src/sdk/client.ts | Exposes hadithReferences on the classic QuranClient. |
| packages/api/src/sdk/chapters.ts | Adds findInfoResponseById and supports resourceId/includeResources query options. |
| packages/api/src/runtime/create-public-client.ts | Adds server-only guarding for hadithReferences on the public runtime client surface. |
| packages/api/src/runtime/create-client.ts | Wires hadith references into the server runtime facade (content.v4.hadithReferences + root). |
| packages/api/mocks/handlers.ts | Extends MSW handlers for chapter-info resources/null cases and new hadith reference endpoints. |
| .changeset/v4-content-parity.md | Declares a minor bump for the new typed SDK surfaces. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
osamasayed
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR brings the JavaScript SDK up to date with the v4 Content API work that was recently merged in
quran/quran.com-api:The goal is for SDK consumers to be able to use the new API behavior through typed SDK methods where we have first-class SDK surfaces, and through the generated raw v4 operation client where the SDK already exposes operation-catalog endpoints.
What Changed
Chapter Info Resource Support
ChapterInfoResponse, including:chapterInfo: ChapterInfo | nullresourcescatalog whenincludeResourcesis requestedresourceIdonChapterInfoQuranChapters.findInfoResponseById(id, options)for callers that need the full response shape.QuranChapters.findInfoById(id, options)as the convenience method, now returningChapterInfo | nullbecause resource-specific lookups can legitimately miss.client.content.v4.chapters.getInfoResponse(...).resourceIdandincludeResourcesquery options.Hadith References
QuranHadithReferencesSDK module with:findByAyah(key, options?)findHadithsByAyah(key, options?)countWithinRange(from, to, options?)client.content.v4.hadithReferences.byAyah(...)client.content.v4.hadithReferences.hadithsByAyah(...)client.content.v4.hadithReferences.countWithinRange(...)hadithReferences, consistent with other app-authenticated Content API reads.Grouped Tafsir List Endpoint Parity
client.content.v4.raw.listSurahTafsirs(...)textfrom both prelive and production for:No additional first-class typed tafsir wrapper was added in this PR because these endpoints are already exposed through the generated raw operation catalog.
Tests, Mocks, and Release Metadata
@quranjs/api.Docs
The SDK docs have been updated in the existing docs PR:
sdk-updatesDocs updates include:
getInfoResponse,includeResources,resourceId, and nullablechapterInfo.llms.txtregeneration and docs config test updates.Validation
SDK Local Checks
pnpm --filter @quranjs/api exec vitest run test/hadith-references.test.ts test/chapters.test.ts test/contracts.test.tspnpm --filter @quranjs/api buildpnpm --filter @quranjs/api lintpackages/api/src/types/quran-client.tsfor@typescript-eslint/consistent-type-importsDocs Checks
Run from the
qf-api-docssdk-updatesworktree:node --test (Get-ChildItem .\tests -Filter *.test.cjs | ForEach-Object { $_.FullName })yarn typecheckLive SDK Smoke Test
Run from
C:\Code\qf-user-pocusing the POC credentials, but importing this branch's local SDK build from:C:\Code\api-js\packages\api\dist\server.min.mjsThis verified that the SDK itself generates the app token through
createServerClientand then calls the new SDK methods/endpoints. No credentials or tokens were printed.Prelive
client.content.v4.chapters.getInfoResponse(1, { includeResources: true })client.content.v4.chapters.getInfoResponse(1, { resourceId })chapterInfoclient.content.v4.hadithReferences.byAyah("1:1")client.content.v4.hadithReferences.hadithsByAyah("1:1", { limit: 1 })client.content.v4.hadithReferences.countWithinRange("1:1", "1:7")client.content.v4.raw.listSurahTafsirs(...),listPageTafsirs(...), andlistJuzTafsirs(...)926/ Arabic Jalalayn TafseertextProduction
client.content.v4.chapters.getInfoResponse(1, { includeResources: true })client.content.v4.chapters.getInfoResponse(1, { resourceId })chapterInfoclient.content.v4.hadithReferences.byAyah("1:1")client.hadithReferences.findByAyah("1:1")client.content.v4.hadithReferences.hadithsByAyah("1:1", { limit: 1 })client.content.v4.hadithReferences.countWithinRange("1:1", "1:7")1:1through1:7client.content.v4.raw.listSurahTafsirs(...),listPageTafsirs(...), andlistJuzTafsirs(...)926/ Arabic Jalalayn TafseertextPrelive Data Caveat
Initial testing used
12:12because that appears in local mocks and examples. In prelive,12:12returns404 Not Foundeven through the normal verse endpoint:client.content.v4.verses.byKey("12:12")=>404 Not Foundin preliveclient.content.v4.verses.byKey("12:12")=> resolves in productionSo the prelive
12:12failure is a prelive content-data issue, not an SDK token, route, or method issue. The final prelive validation used1:1, which resolves successfully there.Known Unrelated Test Issue
The full
pnpm --filter @quranjs/api testcommand still hits the pre-existingpackages/api/test/operation-catalog-generator.test.jsmodule-load failure before assertions withSyntaxError: Invalid or unexpected token. The targeted test files for this change pass, and the package build succeeds.