feat: more KYC fallbacks

[shazarre]

Summary

This branch adds KYC provider fallback escape hatches at multiple points in the
document registration flow. When a user gets stuck — due to hardware limitations,
scan failures, or simply wanting to bail — they can now fall back to third-party KYC
verification instead of being trapped.

What changed

• DocumentNFCScanScreen — Shows a "Try Alternative Verification" button when
  NFC hardware is missing or NFC is disabled. Shows a KYC fallback modal when the user
  taps "Cancel" (only when NFC is supported and enabled, since the button is already
  shown otherwise).
• DocumentCameraScreen — Tapping "Cancel" during MRZ scanning now shows a KYC
  fallback modal instead of navigating home directly.
• DocumentOnboardingScreen — Tapping "Cancel" on the scan instructions screen
  now shows a KYC fallback modal instead of navigating back directly.
• DataConfirmationScreen — When reached via the NFC failure screen ("Check
  scanned data" button), shows an additional "Try Alternative Verification" button
  below "Continue". On the happy path (first visit from MRZ camera), no fallback button
  is shown.
• RegistrationFallbackNFCScreen — Now passes fromNfcFailure: true route param
  when navigating to DataConfirmation.
• useKycLauncher hook — New shared hook that encapsulates KYC session creation,
  provider SDK launch, error handling, and a reusable fallback modal.
• errorInjectionStore — New dev-only store with injectable error types (MRZ,
  NFC, API, KYC) for testing fallback paths without real hardware failures.

How to QA

1 — Device has no NFC hardware

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Enable "NFC: Not supported"
4. Navigate through: Country picker → ID type → Logo confirmation → MRZ scan → Data
   confirmation → NFC scan
5. Verify: "Start Scan" button is disabled, message says device doesn't have NFC
6. Verify: "Try Alternative Verification" button is visible at the bottom
7. Tap it → KYC provider SDK launches

---

2 — NFC supported but disabled

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Enable "NFC: Disabled"
4. Navigate through: Country picker → ID type → Logo confirmation → MRZ scan → Data
   confirmation → NFC scan
5. Verify: Message says NFC is not enabled, button says "Open settings"
6. Verify: "Try Alternative Verification" button is visible at the bottom
7. Tap it → KYC provider SDK launches

---

3 — Can't correct MRZ data on DataConfirmation (after NFC failure)

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Enable "NFC: Timeout" (or any NFC error)
4. Navigate through: Country picker → ID type → Logo confirmation → MRZ scan → Data
   confirmation → NFC scan
5. NFC scan fails → lands on RegistrationFallbackNFC screen
6. Tap "Check scanned data"
7. Verify: DataConfirmation screen now shows two buttons: "Continue" and "Try
   Alternative Verification"
8. Tap "Try Alternative Verification" → KYC provider SDK launches

Negative check: Disable all error injections and navigate to DataConfirmation the
first time (happy path, from MRZ camera). Verify only "Continue" is shown — no
fallback button.

---

4 — User cancels MRZ camera scan

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Make sure all errors are disabled
4. Navigate through: Country picker → ID type → Logo confirmation → MRZ scan (camera
   opens)
5. Tap "Cancel"
6. Verify: Modal appears with two buttons: "Try Alternative Verification" and
   "Cancel Registration"
7. Tap "Try Alternative Verification" → KYC provider SDK launches

---

5 — User cancels NFC scan (soft-exit modal)

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Make sure all errors are disabled
4. Navigate through: Country picker → ID type → Logo confirmation → MRZ scan → Data
   confirmation → NFC scan
5. Tap "Cancel"
6. Verify: Modal appears with two buttons: "Try Alternative Verification" and
   "Cancel Registration"
7. Tap "Try Alternative Verification" → KYC provider SDK launches

---

6 — User abandons at onboarding/instructions

1. Go to Settings > Debug Settings
2. Scroll to Error Injection section
3. Make sure all errors are disabled
4. Navigate through: Country picker → ID type → Logo confirmation → Document
   onboarding screen (shows "Open Camera" instructions)
5. Tap "Cancel"
6. Verify: Modal appears with two buttons: "Try Alternative Verification" and
   "Cancel Registration"
7. Tap "Try Alternative Verification" → KYC provider SDK launches

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
self-webview-app	Ignored	Preview	Apr 23, 2026 0:24am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1d3db7d5-0329-49a3-ac4d-37e2d0a88de5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch shazarre/feat/more_kyc_fallbacks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

This PR adds KYC provider fallback escape hatches at six points in the document registration flow, allowing users stuck due to hardware limitations, scan failures, or user choice to switch to third-party KYC verification rather than being trapped.

Key changes:

• useKycLauncher hook — extended with showKycFallbackModal, a shared helper that presents a two-button modal ("Try Alternative Verification" / "Cancel Registration"), then transitions the modal to a non-dismissible loading state while KYC launches, using AlertModal's finally cleanup to dismiss it on completion
• DocumentNFCScanScreen — shows a direct "Try Alternative Verification" button when NFC hardware is absent or disabled; shows the fallback modal when NFC is available but user taps "Cancel"
• DocumentCameraScreen / DocumentOnboardingScreen — "Cancel" now shows the KYC fallback modal instead of navigating home directly
• DataConfirmationScreen — shows a "Try Alternative Verification" secondary button only when reached via fromNfcFailure: true route param (set by RegistrationFallbackNFCScreen)
• errorInjectionStore — two new dev-only error types (nfc_not_supported, nfc_disabled) for testing fallback paths without real hardware
• AlertModal — new optional disablePrimaryButton prop to support the loading state in the fallback modal
• New test file DataConfirmationScreen-nfcFallback.test.tsx with four targeted cases for the fromNfcFailure flag

Confidence Score: 4/5

Safe to merge; all fallback paths are well-structured and the only findings are non-blocking style suggestions.

The implementation is thorough — six entry points, a shared hook, new tests, and dev tooling for testing. No logical bugs were found. The modal loading-state pattern relies on AlertModal's finally cleanup for dismissal, which works correctly but is a subtle coupling. The untyped useRoute() in DataConfirmationScreen is a minor type-safety gap. Both are style-level improvements, not blockers.

app/src/hooks/useKycLauncher.ts — the modal-lifecycle coupling in showKycFallbackModal is worth a follow-up cleanup. app/src/screens/documents/scanning/DataConfirmationScreen.tsx — the untyped useRoute() cast.

Important Files Changed

Filename	Overview
app/src/hooks/useKycLauncher.ts	New showKycFallbackModal function added; relies on AlertModal's finally block for loading-modal cleanup, which is non-obvious but functional. Minor isLoading visibility gap for modal-triggered flows.
app/src/screens/documents/scanning/DataConfirmationScreen.tsx	Adds KYC fallback button conditionally on fromNfcFailure route param; useRoute() is untyped (manual cast). Logic and rendering are otherwise correct.
app/src/screens/documents/scanning/DocumentNFCScanScreen.tsx	Correctly splits KYC entry points: direct button when NFC is unsupported/disabled, modal when NFC is ok but user cancels. useFeedback cleanup is valid since it's now called inside useKycLauncher.
app/src/screens/documents/scanning/DocumentCameraScreen.tsx	Cancel now shows KYC fallback modal instead of navigating home directly. Change is minimal and correct.
app/src/screens/documents/selection/DocumentOnboardingScreen.tsx	Cancel now shows KYC fallback modal. `countryCode
app/src/screens/documents/scanning/RegistrationFallbackNFCScreen.tsx	One-liner change to pass fromNfcFailure: true to DataConfirmation. Correct and minimal.
app/src/stores/errorInjectionStore.ts	Adds nfc_not_supported and nfc_disabled to the dev-only error injection store; changes are additive and low-risk.
app/src/components/AlertModal.tsx	Adds optional disablePrimaryButton prop; wired correctly to the PrimaryButton's disabled prop.
app/src/navigation/types.ts	Properly extends DataConfirmation route to accept optional fromNfcFailure param while keeping backward compatibility via `
app/src/screens/documents/scanning/DataConfirmationScreen-nfcFallback.test.tsx	New test file covering all four key cases (no param, false, true, button press). Mocking is thorough and consistent with the existing test file.
app/src/screens/documents/scanning/DataConfirmationScreen.test.tsx	Updated to mock the new SDK components and useKycLauncher hook; adds useRoute mock returning undefined params to preserve happy-path behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[DocumentOnboardingScreen\nCancel] -->|showKycFallbackModal| M{KYC Fallback Modal}
    B[DocumentCameraScreen\nCancel] -->|showKycFallbackModal| M
    C[DocumentNFCScanScreen\nCancel - NFC ok] -->|showKycFallbackModal| M
    D[DocumentNFCScanScreen\nNFC not supported/disabled] -->|launchKycVerification| KYC
    E[DataConfirmationScreen\nfromNfcFailure=true] -->|launchKycVerification| KYC

    M -->|Try Alternative Verification| L[Loading Modal\npreventDismiss=true]
    L --> KYC[launchKycVerification]
    M -->|Cancel Registration| H[navigateToHome]

    KYC -->|success| S[KycSuccess screen]
    KYC -->|failed - mrz_scan_failed| R1[RegistrationFallbackMRZ]
    KYC -->|failed - nfc_scan_failed| R2[RegistrationFallbackNFC]
    KYC -->|cancelled| X[onCancel callback]

    R2 -->|Check scanned data\nfromNfcFailure=true| E

Loading

_{Reviews (1): Last reviewed commit: "feat: more KYC fallbacks" | Re-trigger Greptile}