feat: migrate SDK to Quran Foundation Content APIs with OAuth2 support #27
Conversation
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
with OAuth2 support
- Migrated API base URL from Quran.com to Quran Foundation's Content APIs.
- Implemented OAuth2 Client Credentials flow using `configure()` and `tokenManager.ts`.
- Added global SDK config via `configure()` and `getConfig()` functions.
- Updated fetcher logic to include automatic token injection and refresh.
- Created `src/sdk/qf/` namespace for new API wrappers (chapters, verses, etc.).
- Updated endpoint wrappers to use new API base (`/content/api/v4`) and auth headers.
- Preserved legacy `v4` namespace for backward compatibility.
- Reorganized project to support modular endpoint structure.
BREAKING CHANGE: Users must now call `configure({ clientId, clientSecret })` before using the SDK.
APIs (pre-publish) - Refactored internal fetcher and token manager to support Quran Foundation Content APIs - Implemented OAuth2 Client Credentials flow using configure() setup - Migrated all wrappers (chapters, verses, search, juzs, audio, etc.) to qf.* namespace - Updated response parsing and added internal test coverage for all major endpoints Note: README and npm publish are deferred until documentation is migrated and finalized.
…rapper Update README for Quran Foundation SDK
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
There was a problem hiding this comment.
Pull Request Overview
This PR migrates the existing @quranjs/api SDK to use Quran Foundation’s v4 Content APIs with OAuth2 client-credentials support, introduces a global configure() call, and restructures everything under a qf namespace.
- Swap out legacy endpoints for
/content/api/v4and wrap calls underquran.qf.* - Implement OAuth2 Client Credentials flow with token caching
- Convert all response types and parameters to snake_case and add a
mergeApiOptionshelper
Reviewed Changes
Copilot reviewed 35 out of 37 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/manual.test.ts | Added a manual smoke-test script for all qf endpoints |
| src/utils/misc.ts | Introduced mergeApiOptions helper |
| src/types/api/*.ts | Updated all API type interfaces to snake_case |
| src/sdk/qf/* | Updated wrapper modules (chapters, verses, etc.) to v4 endpoints and merged options |
| src/auth/tokenManager.ts | Added OAuth2 token manager with caching and retries |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (3)
test/manual.test.ts:30
- There's an extra
}in the template literal (${verseById.text_uthmani}}). It should be${verseById.text_uthmani}.
console.log(`✅ Verse 1 text: ${verseById.text_uthmani}}`);
test/manual.test.ts:41
- This reuses
findAll()for Juz but logs "Juz 1"—likely you intended to call a method for fetching a single Juz mapping or by ID rather than listing all.
const juz = await quran.qf.juzs.findAll();
src/types/api/Resources.ts:74
- The closing brace is on the same line as
translated_name, making this invalid syntax. Move the}to its own line.
translated_name: TranslatedName;}
| @@ -1,3 +1,7 @@ | |||
| export const removeBeginningSlash = (url: string) => { | |||
| return url.startsWith('/') ? url.slice(1) : url; | |||
| }; | |||
|
|
|||
| export function mergeApiOptions<T>(defaults: T, overrides?: Partial<T>): T { | |||
There was a problem hiding this comment.
mergeApiOptions expects (defaults, overrides), but callers often pass (options, defaultOptions), inverting merge priority. Swap arguments in calls or adjust the function signature to ensure user-provided options override defaults.
Suggested change
| export function mergeApiOptions<T>(defaults: T, overrides?: Partial<T>): T { | |
| export function mergeApiOptions<T>(overrides?: Partial<T>, defaults: T): T { |
Copilot uses AI. Check for mistakes.
src/sdk/qf/verses.ts
Outdated
| }; | ||
|
|
||
| const mergeVerseOptions = (options: GetVerseOptions = {}) => { | ||
| const result = mergeApiOptions(options, defaultOptions); |
There was a problem hiding this comment.
Here options and defaultOptions are passed in the wrong order to mergeApiOptions, causing defaults to override user input. Swap to mergeApiOptions(defaultOptions, options).
Suggested change
| const result = mergeApiOptions(options, defaultOptions); | |
| const result = mergeApiOptions(defaultOptions, options); |
Copilot uses AI. Check for mistakes.
…geapioptions-calls fix: correct argument order for mergeApiOptions calls
Revert argument order in v4 SDK
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.
This PR completes the migration of the @quranjs/api SDK to the new Quran Foundation Content APIs.
✅ Summary of changes:
configure()method for user-supplied credentialsqf.*namespace for all updated wrappers (chapters, verses, search, etc.)📝 Note:
This PR does not publish to npm yet. Final publish and README release will follow once documentation is live on api-docs.quran.foundation.