feat(api): add Qira'at content API v4 endpoints

[basit3407]

Summary

Adds first-class SDK support for the Qira'at Content API v4 endpoints, following the same layout as the Answers and Hadith References endpoints: an SDK class, camelCase response types, a content.v4 facade, a public-client server-only guard, mocks, tests, docs, README and a changeset.

• New QuranQiraat class (packages/api/src/sdk/qiraat.ts), exposed as client.qiraat and client.content.v4.qiraat.
• New types in packages/api/src/types/api/Qiraat.ts, mirrored from the Rails controllers and jbuilder views. The fetcher camelizes keys, so types are camelCase like the other content types.
• Verse keys and chapter ids are validated client-side (Invalid verse key / Invalid chapter id), same as the other endpoints.
• Docs page apps/docs/content/docs/qiraat.mdx, README section, and a minor changeset.

Routes (all GET, under /content/api/v4/qiraat/)

SDK method	Route
findAllReaders(options?)	readers (include: transmitters, bio)
findReaderById(id)	readers/:id
findAllTransmitters(options?)	transmitters (readerId becomes reader_id)
findTransmitterById(id)	transmitters/:id
findJuncturesByVerse(key, options?)	junctures/by_verse/:verse_key (category, include=readings)
findJuncturesByChapter(chapter, options?)	junctures/by_chapter/:chapter_number (page, perPage, category)
findJunctureById(id)	junctures/:id
findReadingById(id)	readings/:id
findMatrixByVerse(key, options?)	matrix/by_verse/:verse_key (textField)
findMatrixByChapter(chapter, options?)	matrix/by_chapter/:chapter_number (page, perPage, textField)
countMatrixWithinRange(from, to)	matrix/count_within_range?from=1:1&to=2:10

The facade mirrors these as content.v4.qiraat.{readers,transmitters,junctures,readings,matrix}.{list,get,byVerse,byChapter,countWithinRange}. matrix/by_verse returns a 404 when a verse has no variations, which surfaces as a QuranHttpError with status 404.

Scope note

These endpoints require the OAuth scope qiraat.read (the qiraat scope is also accepted). The server client's app-token resolver now requests qiraat.read for any /api/v4/qiraat/ path, the same way it already requests post.read / comment.read for QuranReflect routes. Docs and README state that the client must be granted this scope. The legacy QuranClient (fixed content search scope) is intentionally not extended.

Not done / caveats

• src/generated/specs/*operation-catalog.json were not regenerated. They are generated from the OpenAPI specs in quran/qf-api-docs, and that script was not run here.
• No local build, tests, lint, install or typecheck were run (no npm/yarn/pnpm commands). Types, tests and formatting are unverified locally and rely on CI.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-15T04:08:07.917463Z	dda4d36	PR opened
🔒 Security Review	✅ Completed 2026-10-15T04:08:17.454025Z	dda4d36	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

size-limit report 📦

Path	Size
dist/index.min.js	7.85 KB (0%)
dist/index.min.mjs	7.85 KB (0%)
dist/server.min.js	15.35 KB (+1.98% 🔺)
dist/public.min.js	10.05 KB (+0.07% 🔺)