docs: align v2 guides with current sdk behavior

[basit3407]

• remove the outdated quran.v4 fallback from the migration guide and call out the requirement to instantiate QuranClient with credentials
• refresh audio, resources, search, and verses examples to match live typings (correct field names, supported options, and returned properties)
• tidy field-selection snippets and guard search results iteration so docs mirror real-world responses

Summary by CodeRabbit

• Documentation
  • Updated API response examples across audio, resources, verses, and search documentation to reflect current field structure.
  • Updated field selection examples with new available fields, including format and location options.
  • Clarified v2 migration requirements with updated guidance on authentication setup.
  • Added graceful handling of missing values in code examples for recitations, translations, and tafsirs.

[vercel]

@basit3407 is attempting to deploy a commit to the Ahmed Riad Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

Documentation updated across multiple files to reflect API response changes, including removed and new fields, improved null-value handling with fallback defaults, and adjusted field selections in code examples.

Changes

Cohort / File(s)	Summary
Audio API Examples apps/docs/content/docs/audio.mdx	Duration field removed from Chapter Recitations example; Format field added to Get Specific Chapter and Verse Recitations examples with "stream" default; Field Selection updated to exclude url/duration and include format/id with chapterId set to false; Available verse fields documented.
Resources API Examples apps/docs/content/docs/resources.mdx	Console outputs refactored to use safe fallbacks for missing values (reciterName → "Unknown", style → "N/A", arabicName → "n/a"); Single info field replaces individual fields in Recitation/Tafsir details; Languages output uses isoCode and nativeName; Verse Media replaced with media.name and media.languageName.
Search API Examples apps/docs/content/docs/search.mdx	Safe fallbacks added: results.results iteration uses nullish coalescing (?? []); highlighted text access falls back to result.text.
Migration Guide apps/docs/content/docs/v1-migration-guide.mdx	Backward Compatibility sections updated to remove legacy quran.v4 usage example and document its removal in v2; QuranClient instantiation with clientId/clientSecret documented as required upgrade path.
Verses API Examples apps/docs/content/docs/verses.mdx	Translation fields: text replaced with verseKey; Word fields: transliteration/translation/audio removed, verseKey and location added; Verse fields: pageNumber/juzNumber replaced with codeV1/v1Page.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Documentation-only changes with consistent patterns across files (field replacements, null-handling improvements, example updates). Straightforward verification of accuracy without complex logic assessment needed.

Poem

📚✨ Our docs now dance with fields so new,
Safe fallbacks catch what's missing too,
Old names and ages fade away,
While format flows and verseKeys play! 🐰

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "docs: align v2 guides with current sdk behavior" directly and accurately reflects the main objective of the pull request. The changeset updates documentation across multiple files (audio.mdx, resources.mdx, search.mdx, v1-migration-guide.mdx, and verses.mdx) to align with the current SDK implementation, correcting field names, API response structures, removing outdated references, and adding proper error handling. The title is specific and clear—it immediately conveys that documentation is being synchronized with the current SDK state—and avoids vague or generic phrasing. A teammate reviewing the git history would clearly understand that this PR modernizes the documentation to match live SDK behavior.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d71eea7 and d95a059.

📒 Files selected for processing (5)

• apps/docs/content/docs/audio.mdx (3 hunks)
• apps/docs/content/docs/resources.mdx (7 hunks)
• apps/docs/content/docs/search.mdx (1 hunks)
• apps/docs/content/docs/v1-migration-guide.mdx (1 hunks)
• apps/docs/content/docs/verses.mdx (4 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Use kebab-case for files and directories

Files:

• apps/docs/content/docs/v1-migration-guide.mdx
• apps/docs/content/docs/search.mdx
• apps/docs/content/docs/resources.mdx
• apps/docs/content/docs/audio.mdx
• apps/docs/content/docs/verses.mdx

🔇 Additional comments (9)

apps/docs/content/docs/search.mdx (1)

15-17: Good defensive pattern for iterating search results.

The safe fallback (results.results ?? []) and text fallback result.highlighted ?? result.text are appropriate guards that handle cases where these fields may be undefined, reflecting real-world API response variability.

apps/docs/content/docs/v1-migration-guide.mdx (1)

105-107: Clear and explicit backward compatibility statement.

The removal of the quran.v4 namespace and the requirement for explicit clientId and clientSecret credentials are well-documented. The warning that legacy code "will throw at runtime" is appropriately direct, giving users clear guidance on migration necessity.

apps/docs/content/docs/audio.mdx (1)

73-73: Good defensive default for format field and clean field selection.

The fallback audio.format ?? "stream" provides a sensible default for cases where format might be undefined. The field selection example is tidied up and the comment on available verse fields adds helpful clarity.

Also applies to: 80-88

apps/docs/content/docs/resources.mdx (3)

16-16: Consistent fallback patterns for optional fields.

The null coalescing fallbacks (r.reciterName ?? "Unknown" and r.arabicName ?? "n/a") appropriately handle cases where these fields may not be present in API responses.

Also applies to: 151-151

---

32-32: Pattern shift to info object for resource details.

The documentation now shows accessing info.info for recitation, translation, and tafsir details (instead of individual fields like reciterName, bio, photo). This represents a meaningful API shape change—ensure this reflects the actual API contract and that the type definitions in the auto-type-table components are aligned.

Also applies to: 65-65, 99-99

---

115-115: Field name and property changes require verification.

Lines 115 and 183–184 introduce field name changes (iso → isoCode, nativeName property, media.name / media.languageName instead of URLs). Confirm these match the actual API response structure and the types referenced in the auto-type-table components (especially for LanguageResource and VerseMediaResource).

Also applies to: 183-184

apps/docs/content/docs/verses.mdx (3)

32-32: Field selection updated to use verseKey instead of text.

The shift from translationFields.text: true to translationFields.verseKey: true represents an API change in how translation field data is accessed. Ensure this aligns with the actual type definitions for TranslationResult and that code using these examples will not break due to missing fields.

Also applies to: 122-122

---

108-109: New word fields added (verseKey, location).

The word field selection now includes verseKey and location alongside textUthmani. Confirm these are available fields in the Word type and that any removed fields (like transliteration or audio) are intentionally deprioritized in the examples.

---

134-135: Verse field names updated to codeV1 and v1Page.

The shift from pageNumber and juzNumber to codeV1 and v1Page suggests API property renames. This is a breaking change if users' code references the old names—ensure the type definitions and auto-type-table components for the Verse type clearly document this change so users understand the migration path.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}