@glomopay/react-native-sdk 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.0] - 2026-09-22
+
+### Breaking Changes
+
+- **`jail-monkey` is now a required peer dependency, and device compliance fails closed.** It was optional in v4 and the SDK warned and proceeded when it was missing. A device whose security cannot be verified is now refused on a `live_` key rather than assumed clean: `start()` returns `false` and `onSdkError` fires with `type: "device_forbidden"`. Mock and test keys are never blocked, so this does not show up in a `test_` key QA pass. **See [MIGRATION.md](MIGRATION.md) first** - this can take a working live integration off the air.
+- **`onUserRefusedCameraPermissions` renamed to `onUserRefusedDevicePermissions`.** The signature is unchanged, so the compiler points at every call site. The new name reflects what the callback covers - a device permission the bank's page asked for - rather than the camera specifically.
+- **`paymentId` and `signature` are optional on `GlomoCheckoutPayload`.** The checkout page can report a terminal outcome before the backend has resolved those ids; v4 dropped such outcomes entirely rather than report an incomplete one. With `strict` enabled this surfaces as a compile error wherever either value is forwarded to something expecting a `string`, which is the intended guardrail.
+- **`onPaymentTerminate` receives a `GlomoTerminationPayload`.** Carries `source`, from the new `TERMINATION_SOURCES` enum. An existing `() => void` handler stays assignable and compiles unchanged.
+
+### Added
+
+- **Document downloads.** A checkout page can now ask the SDK to save a document to the device, which a page cannot do for itself inside a WebView. Available on every flow. Requires two optional peer dependencies - `react-native-blob-util` and `@react-native-documents/picker` - and a rebuild of the app after installing them; without both the SDK does not advertise the capability and the page keeps its existing behaviour, so nothing breaks by leaving them out. A save that fails reports through `onSdkError` with `field: "file.save"` and never affects the payment session.
+- **`TERMINATION_SOURCES` enum and `GlomoTerminationPayload` type**, both exported.
+- Emulators and simulators now pass device compliance on live keys. The SDK computes its own root verdict from `jail-monkey`'s per-check breakdown instead of its aggregate, which reports every stock Android emulator image as rooted. Every strong root indicator is still enforced.
+- `product` and `surface` query parameters on the checkout and education carousel URLs, so an SDK-originated order is distinguishable from a dashboard one.
+
+### Fixed
+
+- **A `mock_` public key ran in live mode.** It passed validation and then had `mode=live` built into its checkout URL.
+- **Camera now works on LRS checkouts.** The LRS flow had no permission handling wired on either platform, so a bank page requesting camera access got no prompt on Android and no grant on iOS. It now behaves identically to the standard checkout.
+- **`onUserRefusedDevicePermissions` is now forwarded to LRS.** The unified `GlomoCheckout` accepted the callback and advertised it in its types, but never passed it to the LRS flow - so on an LRS order it could never fire. Note it remains Android-only: on iOS the WebView raises its own prompt and never reports the answer back.
+- **Terminal payment outcomes are no longer dropped silently.** A payload the SDK could not route left no trace in a release build - no callback, no telemetry, nothing for support to find. It now reports through `onSdkError` and telemetry.
+- The SDK's back chevron has a touch target that meets the 44dp / 44pt minimum, an accessibility label and a button role.
+
+### Internal
+
+- WebView configuration, permission handling and bridge message routing moved into a shared layer used by every checkout flow, so capabilities land on all flows at once rather than being wired per flow.
+- Improved SDK diagnostics: events now correlate per checkout attempt, carry current checkout status, and record dependency availability, upload attempts, document save outcomes and refused device permissions.
+
 ## [4.0.0] - 2026-06-11
 
 ### Breaking Changes

package/MIGRATION.md

@@ -1,5 +1,117 @@
 # Migration Guide
 
+## v4 to v5
+
+### Start here: `jail-monkey` is now required, and it can block live checkouts
+
+This is the one change that can take a working integration off the air, so do it before anything else.
+
+`jail-monkey` was an optional peer dependency in v4. The SDK warned when it was missing and carried on. In v5 it is a required peer dependency and the compliance gate **fails closed**: a device whose security the SDK cannot verify is refused on a `live_` key rather than assumed clean.
+
+```bash
+npm install jail-monkey
+cd ios && pod install
+```
+
+Then rebuild the app. Installing without rebuilding leaves the native module unlinked, which the SDK treats exactly as if the package were absent.
+
+If you skip this, every live checkout returns `false` from `start()` and fires `onSdkError` with `type: "device_forbidden"`. Mock and test keys are unaffected, so this will not show up in a `test_` key QA pass — check with a live key before you ship.
+
+**Emulators are no longer a problem.** v4 relied on `jail-monkey`'s aggregate verdict, which reports stock Android emulator images as rooted because they ship AOSP test-keys and debuggable system properties. v5 computes its own verdict from the per-check breakdown and ignores those two signals, so integration-testing with a live key on an emulator now works. Every strong root indicator is still enforced.
+
+### Renamed Callbacks
+
+| v4 | v5 |
+|---|---|
+| `onUserRefusedCameraPermissions` | `onUserRefusedDevicePermissions` |
+
+The rename is mechanical - the signature is unchanged and the compiler points at every call site. The new name reflects what the callback has always covered: a device permission the bank's page asked for, rather than the camera specifically.
+
+### `onUserRefusedDevicePermissions` now works on LRS checkouts
+
+Previously the unified `GlomoCheckout` accepted this callback but never forwarded it to the LRS flow, so it could not fire on an LRS order - and LRS had no camera support at all on either platform. Both are fixed. If your integration is LRS-only and you skipped this callback because it never fired, it is now worth supplying.
+
+It remains Android-only: on iOS the WebView raises its own permission prompt and never reports the answer back, so the SDK cannot know what the user chose.
+
+### `paymentId` and `signature` are now optional on payment payloads
+
+```ts
+interface GlomoCheckoutPayload {
+  orderId: string;
+  paymentId?: string;   // was: string
+  signature?: string;   // was: string
+}
+```
+
+This is a widening, not a new failure mode. The checkout page has always been able to report a terminal outcome before the backend resolved those ids — open banking completes on the bank's side first — and v4 responded by **dropping the outcome entirely** behind a `devMode`-only log. In a release build that meant no callback, no telemetry, and no trace of a payment that actually happened. v5 reports it with the fields it has.
+
+With `strict` on, this surfaces at compile time anywhere you forward either value to something expecting a `string`:
+
+```tsx
+onPaymentSuccess={(payload) => {
+  // v4: compiled
+  // v5: Type 'string | undefined' is not assignable to type 'string'
+  confirmOnOurBackend(payload.paymentId);
+
+  // v5: narrow first
+  if (payload.paymentId && payload.signature) {
+    confirmOnOurBackend(payload.paymentId, payload.signature);
+  } else {
+    awaitWebhookFor(payload.orderId);
+  }
+}}
+```
+
+That error is the migration, and it is the point: the alternative was forwarding `undefined` to your backend at runtime.
+
+### `onPaymentTerminate` now receives a payload
+
+```ts
+interface GlomoTerminationPayload {
+  source: TERMINATION_SOURCES;   // "checkout_closed" | "device_back_button" | "modal_dismiss"
+}
+```
+
+**Nothing breaks.** A handler may take fewer parameters than the signature provides, so your existing `() => void` stays assignable and compiles unchanged. Take the payload when you want to tell the page's own close control apart from a device gesture.
+
+The back chevron over a bank flow still does **not** fire this callback, deliberately. It returns the customer to the checkout with the session intact and the ability to pay. If you cancel the order on terminate, wiring the chevron here would cancel live orders every time a customer backed out of one bank to try another.
+
+### A `mock_` public key now runs in mock mode
+
+`isValidPublicKey` accepted `live_`, `mock_` and `test_`, but only `test_` selected mock mode — so a `mock_` key passed validation and then ran against live. If you have been using a `mock_` key and compensating for it, stop.
+
+### New: document downloads (optional)
+
+Some checkout flows offer a document for the customer to save. Install both packages and rebuild to enable it:
+
+```bash
+npm install react-native-blob-util @react-native-documents/picker
+cd ios && pod install
+```
+
+On React Native < 0.79, pin `@react-native-documents/picker` to `10.1.x`.
+
+Leaving them out is supported: the SDK does not advertise the capability, the page keeps its own download behaviour, and nothing breaks. `start()` warns on the console, and `onSdkError` fires once per mount — see below, because that last part changes what `onSdkError` means.
+
+### `onSdkError` can now report a missing capability, not just a misconfiguration
+
+**Check this if your `onSdkError` handler aborts the checkout or shows a blocking error.**
+
+In v4, `onSdkError` only ever meant the integration was misconfigured — a malformed `publicKey`, a missing `orderId` — so treating any error on that callback as fatal was a reasonable reading. In v5 it also fires once per mount, with `type: "validation_error"` and `field: "file.save"`, when the two document-download packages above are not installed. Nothing is wrong in that case: the checkout works and the page keeps its own download path.
+
+If you treat every `onSdkError` as fatal and you have not installed those packages, your checkout will now stop on a condition that is not an error. Filter on `field` rather than on `type`:
+
+```tsx
+onSdkError={(errors) => {
+    const blocking = errors.filter((e) => e.field !== "file.save");
+    if (blocking.length > 0) {
+        // your existing handling
+    }
+}}
+```
+
+The report is deliberately not tied to whether a page actually requests a download: whether this build can write a file to the device is a property of the build, so you learn it once at integration rather than the first time a customer taps download in production.
+
 ## v3 to v4
 
 v4 consolidates the asynchronous payment flow callbacks into a single generic callback.

package/README.md

@@ -12,39 +12,74 @@ Official React Native SDK for integrating GlomoPay payment checkout flows into y
 
 ## System Requirements
 
-| Requirement            | Version      |
-| ---------------------- | ------------ |
-| Node.js                | >= 16.0.0    |
-| npm                    | >= 8.0.0     |
-| React                  | >= 17.0.0    |
-| React Native           | >= 0.68.0    |
-| react-native-webview   | ^13.0.0      |
-| jail-monkey (optional) | ^2.6.0       |
+| Requirement                                | Version   |
+| ------------------------------------------ | --------- |
+| Node.js                                    | >= 16.0.0 |
+| npm                                        | >= 8.0.0  |
+| React                                      | >= 17.0.0 |
+| React Native                               | >= 0.68.0 |
+| react-native-webview                       | ^13.0.0   |
+| jail-monkey                                | ^2.6.0    |
+| react-native-blob-util (optional)          | ^0.25.0   |
+| @react-native-documents/picker (optional)  | >= 10.1.3 |
 
 ## Installation
 
 ### React Native CLI
 
 ```bash
-npm install @glomopay/react-native-sdk react-native-webview
+npm install @glomopay/react-native-sdk react-native-webview jail-monkey
 cd ios && pod install
 ```
 
 ### Expo
 
 ```bash
-npx expo install @glomopay/react-native-sdk react-native-webview
+npx expo install @glomopay/react-native-sdk react-native-webview jail-monkey
 ```
 
-### Recommended: Device Security Compliance
+### Required: Device Security Compliance
 
-For rooted/jailbroken device detection (strongly recommended for regulated flows):
+`jail-monkey` is a **required** peer dependency as of v5. It was optional in v4.
 
 ```bash
 npm install jail-monkey
 ```
 
-The SDK works without `jail-monkey`, but installing it enables automatic device security checks. Without it, the SDK logs a warning on every `start()` call.
+**Without it, live checkouts are blocked.** The SDK cannot tell a clean device from a compromised
+one, and on a `live_` key it refuses to start rather than assume the device is safe. `start()`
+returns `false` and `onSdkError` fires with `type: "device_forbidden"`.
+
+Test and mock keys are never blocked, so QA on a rooted handset or an emulator still works.
+
+### Optional: Document Downloads
+
+Some checkout flows offer a document (an agreement PDF, for example) for the customer to save. A
+web page cannot write a file to the device from inside a WebView, so the SDK does it — but only if
+both of these are installed:
+
+```bash
+npm install react-native-blob-util @react-native-documents/picker
+cd ios && pod install
+```
+
+Leaving them out is a supported choice: the SDK does not advertise the capability, the checkout page
+keeps its own download behaviour, and nothing breaks.
+
+Five things worth knowing before you install them:
+
+1. **Installing is not enabling.** Both ship native code, so the app must be rebuilt. Until then the
+   SDK treats them exactly as if they were absent.
+2. **Reset the Metro cache** after installing (`npx react-native start --reset-cache`). A stale
+   bundle resolves the old module graph and the capability stays off.
+3. **Expo needs a development build.** Neither package works in Expo Go. `react-native-blob-util`
+   ships a config plugin; `@react-native-documents/picker` does not, so add it to your config
+   plugins list yourself if your setup needs one.
+4. **`@react-native-documents/picker` 11 and above requires React Native >= 0.79.** On older React
+   Native, pin `10.1.x` — the API this SDK uses is identical.
+5. **Degradation is silent by design**, which is why it is noisy in development: `start()` logs an
+   ungated warning naming the missing package, and `onSdkError` fires once per mount with
+   `field: "file.save"`.
 
 ## Quick Start
 
@@ -99,8 +134,8 @@ export default function PaymentScreen() {
               break;
           }
         }}
-        onUserRefusedCameraPermissions={() => {
-          console.log("User refused camera - cannot proceed with bank authentication");
+        onUserRefusedDevicePermissions={() => {
+          console.log("User refused a device permission - cannot proceed with bank authentication");
         }}
         onSdkError={(errors: SdkError[]) => {
           errors.forEach((e) => console.error(e.type, e.message, e.field));
@@ -111,6 +146,27 @@ export default function PaymentScreen() {
 }
 ```
 
+## Breaking Changes (v5)
+
+- **`jail-monkey` is now required, and an unverifiable device blocks a live checkout.** It was an
+  optional peer dependency in v4 and warned when absent; it now fails closed. Mock and test keys are
+  never blocked.
+- **`onUserRefusedCameraPermissions` renamed to `onUserRefusedDevicePermissions`.** Signature
+  unchanged, so the compiler points at every call site.
+- **`paymentId` and `signature` are optional on payment payloads.** The page can report a terminal
+  outcome before the backend has resolved them, and the SDK used to drop those outcomes entirely
+  rather than report an incomplete one. With `strict` on, this surfaces as a compile error wherever
+  you forward the value to something expecting a `string` — that narrowing check is the point.
+- **`onPaymentTerminate` now receives a payload.** `GlomoTerminationPayload` carries a `source` from
+  the new `TERMINATION_SOURCES` enum. An existing `() => void` handler stays assignable, so this
+  compiles unchanged.
+- **A `mock_` public key now runs in mock mode.** It passed validation in v4 and then ran against
+  live, which was a bug.
+- New exports: `TERMINATION_SOURCES` enum and `GlomoTerminationPayload` type.
+- New optional capability: document downloads, behind two optional peer dependencies.
+
+For migration details, see MIGRATION.md included in this package.
+
 ## Breaking Changes (v4)
 
 - `GlomoLrsCheckout` has been replaced by `GlomoCheckout` - the new component now works for all checkout orders (including LRS)
@@ -158,8 +214,9 @@ When `subscriptionId` is provided:
 - **TypeScript** - full type definitions for all exports
 - **Unified checkout** - renders the correct checkout flow automatically based on your order
 - **Asynchronous payment flows** - single `onUserJourneyCompleted` callback for bank transfer and pay via bank events
-- **Camera permissions** - built-in handling for bank authentication
-- **Device security** - optional **(but strongly recommended)** `jail-monkey` integration for rooted/jailbroken device detection
+- **Device permissions** - built-in camera handling for bank authentication, on every checkout flow
+- **Document downloads** - saves a document the page offers to the customer's device, on every checkout flow, behind two optional peer dependencies
+- **Device security** - required `jail-monkey` integration for rooted/jailbroken device detection, failing closed on live keys
 - **Input validation** - publicKey and orderId format enforcement before checkout starts
 - **Mock mode** - test with `test_` / `mock_` prefixed keys without hitting production
 
@@ -214,10 +271,10 @@ The unified checkout component. Place it in your render tree and control it via
 | `onPaymentSuccess`               | `(payload: GlomoCheckoutPayload) => void`       | Yes      | Called when payment succeeds                                        |
 | `onPaymentFailure`               | `(payload: GlomoCheckoutPayload) => void`       | Yes      | Called when payment fails                                           |
 | `onConnectionError`              | `(error: unknown) => void`                      | No       | Called on network/connection errors                                 |
-| `onPaymentTerminate`             | `() => void`                                    | No       | Called when user dismisses checkout (back button or swipe)          |
+| `onPaymentTerminate`             | `(payload: GlomoTerminationPayload) => void`    | No       | Called when the checkout ends without a payment outcome. `payload.source` names how. An existing `() => void` handler stays assignable. |
 | `onSdkError`                     | `(errors: SdkError[]) => void`                  | Yes      | Called on validation errors or device compliance failures           |
-| `onUserJourneyCompleted`         | `(payload: GlomoUserJourneyCompletedPayload) => void` | No | Called when an asynchronous payment flow completes (bank transfer submission, pay via bank completion). Check `payload.journeyType` to determine the flow. |
-| `onUserRefusedCameraPermissions` | `() => void`                                    | No       | Called when user denies camera access needed for bank authentication                |
+| `onUserJourneyCompleted`         | `(payload: GlomoUserJourneyCompletedPayload) => void` | No | Called when an asynchronous payment flow completes (bank transfer submission, pay via bank completion) - not a confirmed payment. Check `payload.journeyType` to determine the flow. Accepted on `GlomoCheckout` but silently ignored on LRS orders - LRS never produces an asynchronous journey, so it never fires there. |
+| `onUserRefusedDevicePermissions` | `() => void`                                    | No       | Called when the user denies a device permission the bank's page asked for - camera today. Android only; see [Device Permissions](#device-permissions). |
 
 *Exactly one of `orderId` or `subscriptionId` must be provided. If both or neither are set, `onSdkError` fires and `start()` returns `false`.
 
@@ -248,11 +305,16 @@ The unified checkout component. Place it in your render tree and control it via
 ```ts
 interface GlomoCheckoutPayload {
   orderId: string;
-  paymentId: string;
-  signature: string;
+  paymentId?: string;
+  signature?: string;
 }
 ```
 
+`paymentId` and `signature` became optional in v5. The checkout page can report a terminal outcome
+before the backend has resolved them - open banking completes on the bank's side first - and the SDK
+previously dropped those outcomes rather than report an incomplete one. Narrow before forwarding
+either value.
+
 #### ASYNC_PAYMENT_EVENTS
 
 ```ts
@@ -274,16 +336,52 @@ interface GlomoUserJourneyCompletedPayload {
 }
 ```
 
+#### TERMINATION_SOURCES
+
+```ts
+enum TERMINATION_SOURCES {
+  CHECKOUT_CLOSED = "checkout_closed",        // the page's own close control
+  DEVICE_BACK_BUTTON = "device_back_button",  // Android hardware back or back gesture
+  MODAL_DISMISS = "modal_dismiss",            // iOS swipe-down on the modal
+}
+```
+
+The back chevron over a bank flow is deliberately **not** in this list. It returns the user to the
+checkout with the session intact and the ability to pay, so reporting it as a termination would be
+false - and for a merchant who cancels the order on terminate, it would cancel live orders every
+time a customer backed out of one bank to try another.
+
+#### GlomoTerminationPayload
+
+```ts
+interface GlomoTerminationPayload {
+  source: TERMINATION_SOURCES;
+}
+```
+
+An object rather than a bare enum, so a later field can be added without changing the signature or
+redefining what an existing value means.
+
 #### SdkError
 
 ```ts
 interface SdkError {
   type: "validation_error" | "device_forbidden";
   message: string;
-  field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
+  field?:
+    | "publicKey"
+    | "orderId"
+    | "subscriptionId"
+    | "baseCheckoutUrl"
+    | "generatedCheckoutUrl"
+    | "file.save";
 }
 ```
 
+The first five name configuration you supplied. `file.save` is a bridge message type, and is here so
+a document that failed to save can be filtered apart from a bad public key on a callback that carries
+both — see [Document downloads](#document-downloads) for when it fires.
+
 ## Asynchronous Payment Flows
 
 The SDK fires `onUserJourneyCompleted` when an asynchronous payment flow completes. Use `payload.journeyType` to determine which flow triggered the callback:
@@ -313,9 +411,11 @@ onUserJourneyCompleted={(payload) => {
 
 The checkout status transitions to `bank_transfer_submitted` or `pay_via_bank_completed` respectively. Use `getStatus()` for granular programmatic checks.
 
-## Camera Permissions
+## Device Permissions
 
-Some checkout flows may require camera access for bank authentication. The SDK handles permission prompts automatically, but you must declare the permissions in your native project config.
+Some bank pages require camera access for authentication. The SDK handles permission prompts automatically on every checkout flow, but you must declare the permissions in your native project config.
+
+File upload permissions are requested by `react-native-webview` itself and never reach the SDK, so they do not surface through `onUserRefusedDevicePermissions`.
 
 ### Android
 
@@ -336,8 +436,8 @@ Add to `ios/<YourApp>/Info.plist`:
 
 ### Behavior
 
-- **Android**: SDK prompts the user via a native permission dialog. If denied, checkout closes and `onUserRefusedCameraPermissions` fires.
-- **iOS**: SDK grants the WebView permission request; iOS shows its own system prompt. If the user denies at the system level, the WebView handles the denial.
+- **Android**: SDK prompts the user via a native permission dialog. If denied, checkout closes and `onUserRefusedDevicePermissions` fires.
+- **iOS**: SDK grants the WebView permission request; iOS shows its own system prompt. If the user denies at the system level, the WebView handles the denial and never reports it back, so `onUserRefusedDevicePermissions` does not fire on iOS.
 
 ## Platform Behavior
 
@@ -346,11 +446,29 @@ Add to `ios/<YourApp>/Info.plist`:
 
 ## Device Security Compliance
 
-The SDK optionally integrates with `jail-monkey` to detect rooted (Android) or jailbroken (iOS) devices.
+The SDK uses `jail-monkey` to detect rooted (Android) or jailbroken (iOS) devices. As of v5 it is a
+required peer dependency and the gate **fails closed**: a device the SDK cannot verify is refused on
+a live key rather than assumed clean.
+
+| Device                                | `test_` / `mock_` key | `live_` key |
+| ------------------------------------- | --------------------- | ----------- |
+| Clean                                 | allowed               | allowed     |
+| Emulator / simulator                  | allowed               | allowed     |
+| Rooted / jailbroken                   | allowed               | **blocked** |
+| Unverifiable (`jail-monkey` missing)  | allowed               | **blocked** |
+
+When blocked, `start()` returns `false` and `onSdkError` fires with `type: "device_forbidden"`. The
+message distinguishes a compromised device from an unverifiable one.
+
+**Emulators are allowed on live keys, deliberately.** Android emulators ship AOSP test-keys and
+debuggable system properties, which trip two of the checks behind `isJailBroken()` — so the
+aggregate verdict reports every stock emulator as rooted. The SDK computes its own verdict from
+`jail-monkey`'s per-check breakdown and ignores those two, because merchants integration-test with
+live keys on emulators and an emulator is not the threat this gate exists for. Every strong root
+indicator (su binaries, Magisk, root-manager apps, remounted system paths) is still enforced.
 
-- If `jail-monkey` is installed and the device is compromised: `start()` returns `false` and `onSdkError` fires with `type: "device_forbidden"`.
-- If `jail-monkey` is installed and the device is clean: checkout proceeds normally.
-- If `jail-monkey` is not installed: SDK logs a warning and proceeds without checking. This is not recommended for production deployments handling regulated transactions.
+The cost is custom-ROM detection on physical devices, the weakest signal in the set. On iOS, and on
+any build that exposes no breakdown, the SDK falls back to `isJailBroken()` unchanged.
 
 ## Mock Mode
 
@@ -387,9 +505,11 @@ Validation failures fire `onSdkError` with `type: "validation_error"` and the re
 
 Providing both `orderId` and `subscriptionId` (or neither) also fires `onSdkError`.
 
-## Migration from v1/v3
+## Migration
 
-See MIGRATION.md included in this package for migration guides with before/after code examples.
+See MIGRATION.md included in this package for migration guides with before/after code examples,
+covering v1 through v5. **If you are upgrading from v4, read the v5 section first** - `jail-monkey`
+became a required dependency and can block live checkouts.
 
 ## Troubleshooting
 
@@ -400,17 +520,33 @@ Check `onSdkError` for details. Common causes:
 - Invalid `orderId` format (must start with `order_`)
 - Invalid `subscriptionId` format (must start with `sub_`, non-empty after trimming)
 - Both `orderId` and `subscriptionId` provided (or neither)
-- Device is rooted/jailbroken (when `jail-monkey` is installed)
+- Device is rooted or jailbroken, on a `live_` key
+- Device security could not be verified on a `live_` key, because `jail-monkey` is missing or its
+  native module is not linked. Install it and rebuild the app; the console warning names this case.
 
 ### Checkout opens but shows a blank screen
 
 - Verify network connectivity
 - Check that the `publicKey` and `orderId` are valid
 
+### Document downloads do nothing
+
+The capability is only advertised when both `react-native-blob-util` and
+`@react-native-documents/picker` load successfully, and the checkout page falls back to its own
+behaviour when it is absent. Check, in order:
+
+- Both packages installed, and the app rebuilt afterwards - installing alone is not enough
+- Metro cache reset (`npx react-native start --reset-cache`)
+- Not running in Expo Go, which cannot load either package
+- On React Native < 0.79, `@react-native-documents/picker` pinned to `10.1.x`
+
+`start()` logs an ungated warning naming the package it could not load, and `onSdkError` fires once
+per mount with `field: "file.save"`.
+
 ### Camera permission denied
 
 - Ensure `AndroidManifest.xml` and `Info.plist` include camera permission declarations
-- The `onUserRefusedCameraPermissions` callback will fire when the user denies camera permissions to your app
+- The `onUserRefusedDevicePermissions` callback will fire when the user denies camera permissions to your app, on Android only
 
 ## Exports
 
@@ -422,7 +558,7 @@ export { GlomoCheckout } from "@glomopay/react-native-sdk";
 export { useGlomoCheckout } from "@glomopay/react-native-sdk";
 
 // Enums
-export { ASYNC_PAYMENT_EVENTS } from "@glomopay/react-native-sdk";
+export { ASYNC_PAYMENT_EVENTS, TERMINATION_SOURCES } from "@glomopay/react-native-sdk";
 
 // Types
 export type {
@@ -431,6 +567,7 @@ export type {
   GlomoCheckoutPayload,
   CheckoutStatus,
   GlomoUserJourneyCompletedPayload,
+  GlomoTerminationPayload,
   UseGlomoCheckoutReturn,  // deprecated
   SdkError,
 } from "@glomopay/react-native-sdk";

package/lib/bridge/file-input-handler.d.ts

@@ -0,0 +1,25 @@
+/** The `file.input` bridge message - the user tapped a file input on a bank's page */
+import { type WebViewMessageHandler } from "./message-router";
+import { type FlowType } from "../utils/analytics";
+/** The context an upload attempt needs in order to report itself */
+export interface CreateFileInputHandlerOptions {
+    flowType: FlowType;
+    orderId?: string;
+    publicKey: string;
+    checkoutUrl: string;
+    mockMode: boolean;
+    devMode: boolean;
+}
+/**
+ * Builds the handler for `file.input`.
+ *
+ * Telemetry only, and there is nothing else it could be: the chooser is opened and resolved
+ * natively by react-native-webview, so this message is the attempt and no outcome follows it.
+ * Nothing merchant-facing fires here - an SDK that reported "upload started" with no way to report
+ * "upload finished" would be worse than silent.
+ *
+ * Reports the shape of the input, never its identity. `accept` is normalised so it joins with
+ * anything else reported for the same click.
+ */
+export declare function createFileInputHandler({ flowType, orderId, publicKey, checkoutUrl, mockMode, devMode, }: CreateFileInputHandlerOptions): WebViewMessageHandler;
+//# sourceMappingURL=file-input-handler.d.ts.map

package/lib/bridge/file-input-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-input-handler.d.ts","sourceRoot":"","sources":["../../src/bridge/file-input-handler.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,KAAK,QAAQ,EAA4B,MAAM,oBAAoB,CAAC;AAE7E,oEAAoE;AACpE,MAAM,WAAW,6BAA6B;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EACnC,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,QAAQ,EACR,OAAO,GACV,EAAE,6BAA6B,GAAG,qBAAqB,CA+BvD"}

package/lib/bridge/file-input-handler.js

@@ -0,0 +1,38 @@
+"use strict";
+/** The `file.input` bridge message - the user tapped a file input on a bank's page */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileInputHandler = createFileInputHandler;
+const file_metadata_1 = require("../utils/file-metadata");
+const analytics_1 = require("../utils/analytics");
+/**
+ * Builds the handler for `file.input`.
+ *
+ * Telemetry only, and there is nothing else it could be: the chooser is opened and resolved
+ * natively by react-native-webview, so this message is the attempt and no outcome follows it.
+ * Nothing merchant-facing fires here - an SDK that reported "upload started" with no way to report
+ * "upload finished" would be worse than silent.
+ *
+ * Reports the shape of the input, never its identity. `accept` is normalised so it joins with
+ * anything else reported for the same click.
+ */
+function createFileInputHandler({ flowType, orderId, publicKey, checkoutUrl, mockMode, devMode, }) {
+    return (message) => {
+        const accept = typeof message.accept === "string" ? message.accept : undefined;
+        /**
+         * Read as a boolean, not derived from the attribute's value. `capture` is an enumerated
+         * attribute and its commonest spelling on a bank's KYC form is valueless - `<input
+         * type="file" capture>` - for which getAttribute returns "". Measuring string length there
+         * reported hasCapture: false on exactly the camera-backed inputs this exists to count.
+         */
+        const hasCapture = message.hasCapture === true;
+        /**
+         * Logged as well as tracked. Nothing merchant-facing fires for an upload attempt - the
+         * chooser is opened and resolved natively - so without this there is no observable signal
+         * that the bridge received it, and the path cannot be tested.
+         */
+        if (devMode) {
+            console.log(`[Glomo-RN-SDK] file.input requested: hasCapture=${hasCapture}`);
+        }
+        (0, analytics_1.trackFileUploadRequested)((0, file_metadata_1.normalizeAcceptTypes)(accept), hasCapture, orderId, publicKey, devMode, mockMode, checkoutUrl, flowType);
+    };
+}

package/lib/bridge/file-save-handler.d.ts

@@ -0,0 +1,32 @@
+/** The `file.save` bridge message, wired once and registered on every WebView that can receive it */
+import { type WebViewMessageHandler } from "./message-router";
+import { type FlowType, type SdkError } from "../utils/analytics";
+/** The context a save needs in order to report itself. Supplied by whichever flow registered it. */
+export interface CreateFileSaveHandlerOptions {
+    flowType: FlowType;
+    orderId?: string;
+    publicKey: string;
+    checkoutUrl: string;
+    mockMode: boolean;
+    devMode: boolean;
+    /**
+     * The merchant's error callback.
+     *
+     * Reached directly, and deliberately not through whatever a flow uses to end a checkout: a
+     * document failing to save must not touch checkout status or end the customer's payment session.
+     */
+    onSdkError: (errors: Array<SdkError>) => void;
+}
+/**
+ * Builds the handler for `file.save`.
+ *
+ * Fire-and-forget by contract - the page gets no acknowledgement and must not wait for one. Once
+ * past the guard below, every outcome lands on `File Save Completed`, and a failure additionally
+ * reaches the host's onSdkError without ending the checkout.
+ *
+ * The handler itself is synchronous because the router's handlers are; the save runs detached and
+ * reports through telemetry rather than a return value, which is the same shape the contract
+ * describes on the page side.
+ */
+export declare function createFileSaveHandler({ flowType, orderId, publicKey, checkoutUrl, mockMode, devMode, onSdkError, }: CreateFileSaveHandlerOptions): WebViewMessageHandler;
+//# sourceMappingURL=file-save-handler.d.ts.map

package/lib/bridge/file-save-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-save-handler.d.ts","sourceRoot":"","sources":["../../src/bridge/file-save-handler.ts"],"names":[],"mappings":"AAAA,qGAAqG;AAErG,OAAO,EAAuB,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAUnF,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAkD,MAAM,oBAAoB,CAAC;AAGlH,oGAAoG;AACpG,MAAM,WAAW,4BAA4B;IACzC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;OAKG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;CACjD;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,EAClC,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,QAAQ,EACR,OAAO,EACP,UAAU,GACb,EAAE,4BAA4B,GAAG,qBAAqB,CAqEtD"}