@glomopay/react-native-sdk 4.1.0 → 5.0.0

package/lib/utils/validation.d.ts

@@ -7,6 +7,12 @@
  * @returns true if valid, false otherwise
  */
 export declare function isValidPublicKey(publicKey: string): boolean;
+/**
+ * Whether this public key should run in mock mode.
+ *
+ * Case-insensitive, matching what the call sites already did.
+ */
+export declare function isMockModeKey(publicKey?: string): boolean;
 /**
  * Validates that an order ID has the correct format
  * @param orderId - The order ID to validate
@@ -21,14 +27,42 @@ export declare function isValidOrderId(orderId: string): boolean;
 export declare function isValidUrl(url: string): boolean;
 /**
  * Validates the payment payload structure
+ *
+ * `orderId` is the only field the SDK can route on and the only one required. The other two are
+ * reported when present and named in telemetry when absent - see missingPaymentFields.
+ *
+ * Relaxed in v5. Before this, a payload missing either optional field failed here and the whole
+ * outcome was dropped behind a devMode-only log: no callback, no telemetry, no trace in a release
+ * build. `strict: true` in tsconfig is what makes the looser shape safe for merchants - an optional
+ * field cannot reach anything expecting a `string` without a narrowing check, so this lands as a
+ * compile error rather than a runtime surprise.
+ *
+ * An empty `orderId` is accepted, and must stay accepted. Open banking and pay-via-bank post
+ * `payment.success` with empty fields when the payment completes on the bank's side before the
+ * checkout backend has resolved ids - so rejecting `""` here would drop a payment that actually
+ * succeeded, which is the exact failure the widening above exists to remove. v4 carried the same
+ * rule in a comment; a length check briefly reintroduced the bug in v5 before review caught it.
+ * Type is the only thing checked: a non-string `orderId` is malformed, an empty one is early.
+ *
  * @param payload - The payload to validate
- * @returns true if valid, false otherwise
+ * @returns true if the payload carries a usable orderId
  */
 export declare function isValidPaymentPayload(payload: unknown): payload is {
     orderId: string;
-    paymentId: string;
-    signature: string;
+    paymentId?: string;
+    signature?: string;
 };
+/**
+ * Which optional fields a valid payload did not carry.
+ *
+ * Empty for a complete payload. Treats the empty string as missing: the page sends `""` rather than
+ * omitting the key when the backend has not resolved an id, and the two mean the same thing to
+ * anyone reading the event.
+ */
+export declare function missingPaymentFields(payload: {
+    paymentId?: string;
+    signature?: string;
+}): string[];
 /**
  * Safely executes a callback with error handling
  *

package/lib/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM/C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB,CAYA;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAC3D,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,OAAe,GACzB,IAAI,CAWN"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAU3D;AAWD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAMzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM/C;AAYD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAYA;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAElG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAC3D,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,OAAe,GACzB,IAAI,CAWN"}

package/lib/utils/validation.js

@@ -4,9 +4,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidPublicKey = isValidPublicKey;
+exports.isMockModeKey = isMockModeKey;
 exports.isValidOrderId = isValidOrderId;
 exports.isValidUrl = isValidUrl;
 exports.isValidPaymentPayload = isValidPaymentPayload;
+exports.missingPaymentFields = missingPaymentFields;
 exports.safeCallback = safeCallback;
 /**
  * Validates that a public key has the correct format
@@ -21,6 +23,26 @@ function isValidPublicKey(publicKey) {
     return (publicKey.length > 5 &&
         (publicKey.startsWith("live_") || publicKey.startsWith("mock_") || publicKey.startsWith("test_")));
 }
+/**
+ * Prefixes that run the checkout against mocks instead of taking a live payment.
+ *
+ * `isValidPublicKey` has always accepted all three prefixes while every mock-mode check tested only
+ * `test_`, so a `mock_` key passed validation and then had `mode=live` built into its checkout URL -
+ * a mock key taking a real payment. Declared once here so the two cannot drift again.
+ */
+const MOCK_MODE_PREFIXES = ["test_", "mock_"];
+/**
+ * Whether this public key should run in mock mode.
+ *
+ * Case-insensitive, matching what the call sites already did.
+ */
+function isMockModeKey(publicKey) {
+    const normalized = publicKey === null || publicKey === void 0 ? void 0 : publicKey.toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return MOCK_MODE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
 /**
  * Validates that an order ID has the correct format
  * @param orderId - The order ID to validate
@@ -44,23 +66,57 @@ function isValidUrl(url) {
     }
     return url.startsWith("http://") || url.startsWith("https://");
 }
+/**
+ * The fields a payment payload may be missing and still be usable
+ *
+ * `paymentId` and `signature` are resolved by the checkout backend, and a page can report a
+ * terminal outcome before that has happened - open banking completes on the bank's side first.
+ * Requiring them meant the SDK dropped a real payment outcome on the floor rather than reporting an
+ * incomplete one, so the merchant learned nothing at all.
+ */
+const OPTIONAL_PAYMENT_FIELDS = ["paymentId", "signature"];
 /**
  * Validates the payment payload structure
+ *
+ * `orderId` is the only field the SDK can route on and the only one required. The other two are
+ * reported when present and named in telemetry when absent - see missingPaymentFields.
+ *
+ * Relaxed in v5. Before this, a payload missing either optional field failed here and the whole
+ * outcome was dropped behind a devMode-only log: no callback, no telemetry, no trace in a release
+ * build. `strict: true` in tsconfig is what makes the looser shape safe for merchants - an optional
+ * field cannot reach anything expecting a `string` without a narrowing check, so this lands as a
+ * compile error rather than a runtime surprise.
+ *
+ * An empty `orderId` is accepted, and must stay accepted. Open banking and pay-via-bank post
+ * `payment.success` with empty fields when the payment completes on the bank's side before the
+ * checkout backend has resolved ids - so rejecting `""` here would drop a payment that actually
+ * succeeded, which is the exact failure the widening above exists to remove. v4 carried the same
+ * rule in a comment; a length check briefly reintroduced the bug in v5 before review caught it.
+ * Type is the only thing checked: a non-string `orderId` is malformed, an empty one is early.
+ *
  * @param payload - The payload to validate
- * @returns true if valid, false otherwise
+ * @returns true if the payload carries a usable orderId
  */
 function isValidPaymentPayload(payload) {
     if (!payload || typeof payload !== "object") {
         return false;
     }
     const p = payload;
-    /**
-     * Accept payloads where orderId, paymentId, and signature are strings.
-     * Empty strings are allowed because some flows (e.g. open banking / pay via bank)
-     * send payment.success with empty fields when the payment completes on the
-     * bank's side before the checkout backend has resolved ids.
-     */
-    return typeof p.orderId === "string" && typeof p.paymentId === "string" && typeof p.signature === "string";
+    if (typeof p.orderId !== "string") {
+        return false;
+    }
+    // Present-but-wrong-type is a malformed payload, unlike absent, which is merely incomplete
+    return OPTIONAL_PAYMENT_FIELDS.every((field) => p[field] === undefined || typeof p[field] === "string");
+}
+/**
+ * Which optional fields a valid payload did not carry.
+ *
+ * Empty for a complete payload. Treats the empty string as missing: the page sends `""` rather than
+ * omitting the key when the backend has not resolved an id, and the two mean the same thing to
+ * anyone reading the event.
+ */
+function missingPaymentFields(payload) {
+    return OPTIONAL_PAYMENT_FIELDS.filter((field) => !payload[field]);
 }
 /**
  * Safely executes a callback with error handling

package/lib/webview/capability-props.d.ts

@@ -0,0 +1,27 @@
+/** Shared WebView configuration for every GlomoPay checkout WebView */
+import { type WebViewProps } from "react-native-webview";
+import { type WebViewPermissionRequest } from "./use-permission-request";
+/**
+ * react-native-webview's props plus the Android-only permission handler, which is
+ * missing from its type definitions. Declaring it here removes the @ts-expect-error
+ * each call site used to carry.
+ */
+export type CapabilityWebViewProps = Partial<WebViewProps> & {
+    onPermissionRequest?: (request: WebViewPermissionRequest) => void;
+};
+/** The options for buildCapabilityProps */
+export interface CapabilityPropsOptions {
+    devMode?: boolean;
+    /** From usePermissionRequest. Omit only for WebViews that render our own content. */
+    onPermissionRequest?: (request: WebViewPermissionRequest) => void;
+}
+/**
+ * Configuration shared by every WebView the SDK renders, regardless of flow.
+ *
+ * Only configuration belongs here - things that describe how a WebView behaves. Per-WebView
+ * concerns (source, refs, message handlers, injected scripts, styles) stay at the call site,
+ * and defensive patches against a bank's markup stay in the flow injection script, since the
+ * WebViews that render our own pages have no third-party markup to defend against.
+ */
+export declare function buildCapabilityProps({ devMode, onPermissionRequest, }: CapabilityPropsOptions): CapabilityWebViewProps;
+//# sourceMappingURL=capability-props.d.ts.map

package/lib/webview/capability-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-props.d.ts","sourceRoot":"","sources":["../../src/webview/capability-props.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG;IACzD,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACrE,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qFAAqF;IACrF,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACrE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EACjC,OAAe,EACf,mBAAmB,GACtB,EAAE,sBAAsB,GAAG,sBAAsB,CAmDjD"}

package/lib/webview/capability-props.js

@@ -0,0 +1,61 @@
+"use strict";
+/** Shared WebView configuration for every GlomoPay checkout WebView */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapabilityProps = buildCapabilityProps;
+/**
+ * Configuration shared by every WebView the SDK renders, regardless of flow.
+ *
+ * Only configuration belongs here - things that describe how a WebView behaves. Per-WebView
+ * concerns (source, refs, message handlers, injected scripts, styles) stay at the call site,
+ * and defensive patches against a bank's markup stay in the flow injection script, since the
+ * WebViews that render our own pages have no third-party markup to defend against.
+ */
+function buildCapabilityProps({ devMode = false, onPermissionRequest, }) {
+    return {
+        webviewDebuggingEnabled: __DEV__ && devMode,
+        javaScriptEnabled: true,
+        domStorageEnabled: true,
+        javaScriptCanOpenWindowsAutomatically: true,
+        setSupportMultipleWindows: true,
+        incognito: true,
+        cacheEnabled: false,
+        cacheMode: "LOAD_NO_CACHE",
+        pullToRefreshEnabled: false,
+        limitsNavigationsToAppBoundDomains: false,
+        menuItems: [],
+        showsHorizontalScrollIndicator: false,
+        showsVerticalScrollIndicator: false,
+        mixedContentMode: "always",
+        thirdPartyCookiesEnabled: true,
+        sharedCookiesEnabled: true,
+        allowsInlineMediaPlayback: true,
+        mediaPlaybackRequiresUserAction: false,
+        /**
+         * Camera for bank authentication. iOS raises its own prompt; Android routes through
+         * onPermissionRequest below.
+         */
+        mediaCapturePermissionGrantType: "prompt",
+        onPermissionRequest,
+        /**
+         * File access props.
+         *
+         * These only apply to JavaScript running inside a file:// document, and no file://
+         * document can load here - neither factory sets originWhitelist, so
+         * react-native-webview's default of ['http://*', 'https://*'] applies and a file://
+         * navigation is never taken. Every WebView loads remote https under incognito. So
+         * these are inert, and kept for uniformity across flows rather than because anything
+         * needs them.
+         *
+         * Note allowFileAccess is not inert in the same way: rnw defaults it to false on
+         * Android, so we are the ones turning it on. Deliberate, and safe only because of the
+         * originWhitelist default above.
+         *
+         * If originWhitelist is ever set to admit file://, all three become live and this
+         * needs revisiting.
+         */
+        allowFileAccess: true,
+        allowUniversalAccessFromFileURLs: true,
+        allowFileAccessFromFileURLs: true,
+        androidLayerType: "hardware",
+    };
+}

package/lib/webview/use-permission-request.d.ts

@@ -0,0 +1,33 @@
+/** Shared WebView permission handling for every GlomoPay checkout flow */
+/** Android-only WebView permission request, not yet in react-native-webview type definitions */
+export interface WebViewPermissionRequest {
+    nativeEvent: {
+        resources: string[];
+    };
+    grant: (resources: string[]) => void;
+    deny: () => void;
+}
+/** The options for the usePermissionRequest hook */
+export interface UsePermissionRequestOptions {
+    /** Log prefix of the calling flow, e.g. "[Glomo-RN-SDK LRS]" */
+    logPrefix: string;
+    /**
+     * Called when the user refuses camera access, or when the request errors out.
+     * The caller owns what happens next - closing the checkout, moving its status,
+     * and notifying the merchant are all flow-level concerns and stay outside this hook.
+     */
+    onDenied: () => void;
+    devMode?: boolean;
+}
+/**
+ * Handler for WebView permission requests (e.g. camera access for bank authentication).
+ * On Android, prompts the user for camera permission via PermissionsAndroid.
+ * On iOS, grants camera access automatically (iOS handles its own permission prompt).
+ * Non-camera permissions are denied by default.
+ *
+ * Lives here rather than inside a flow hook so every flow gets the same behaviour.
+ * It previously existed only on the standard checkout, which left LRS with no camera
+ * support at all on either platform.
+ */
+export declare function usePermissionRequest({ logPrefix, onDenied, devMode }: UsePermissionRequestOptions): (request: WebViewPermissionRequest) => Promise<void>;
+//# sourceMappingURL=use-permission-request.d.ts.map

package/lib/webview/use-permission-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-permission-request.d.ts","sourceRoot":"","sources":["../../src/webview/use-permission-request.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAK1E,gGAAgG;AAChG,MAAM,WAAW,wBAAwB;IACrC,WAAW,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACrC,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACrC,IAAI,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IACxC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAC;IAErB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAe,EAAE,EAAE,2BAA2B,aAElF,wBAAwB,mBA0E/C"}

package/lib/webview/use-permission-request.js

@@ -0,0 +1,89 @@
+"use strict";
+/** Shared WebView permission handling for every GlomoPay checkout flow */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePermissionRequest = usePermissionRequest;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+/**
+ * Handler for WebView permission requests (e.g. camera access for bank authentication).
+ * On Android, prompts the user for camera permission via PermissionsAndroid.
+ * On iOS, grants camera access automatically (iOS handles its own permission prompt).
+ * Non-camera permissions are denied by default.
+ *
+ * Lives here rather than inside a flow hook so every flow gets the same behaviour.
+ * It previously existed only on the standard checkout, which left LRS with no camera
+ * support at all on either platform.
+ */
+function usePermissionRequest({ logPrefix, onDenied, devMode = false }) {
+    return (0, react_1.useCallback)(async (request) => {
+        try {
+            const { resources } = request.nativeEvent;
+            // Checking if the requested permission is camera-related
+            const isCameraPermissionRequest = resources.some((resource) => resource === "camera" || resource.toLowerCase().includes("camera"));
+            if (!isCameraPermissionRequest) {
+                if (devMode) {
+                    console.log(`${logPrefix} Non-camera permission requested, denying:`, resources);
+                }
+                request.deny();
+                return;
+            }
+            if (devMode) {
+                console.log(`${logPrefix} Camera permission requested by webpage`);
+            }
+            if (react_native_1.Platform.OS === "android") {
+                try {
+                    const granted = await react_native_1.PermissionsAndroid.request(react_native_1.PermissionsAndroid.PERMISSIONS.CAMERA, {
+                        title: "Camera Permission",
+                        message: "This app needs camera access for identity verification during checkout",
+                        buttonNeutral: "Ask Me Later",
+                        buttonNegative: "Cancel",
+                        buttonPositive: "OK",
+                    });
+                    if (granted === react_native_1.PermissionsAndroid.RESULTS.GRANTED) {
+                        if (devMode) {
+                            console.log(`${logPrefix} Camera permission granted`);
+                        }
+                        request.grant(resources);
+                    }
+                    else {
+                        if (devMode) {
+                            console.log(`${logPrefix} Camera permission denied by user`);
+                        }
+                        onDenied();
+                        request.deny();
+                    }
+                }
+                catch (err) {
+                    if (devMode) {
+                        console.error(`${logPrefix} Error requesting camera permission:`, err);
+                    }
+                    onDenied();
+                    request.deny();
+                }
+            }
+            else if (react_native_1.Platform.OS === "ios") {
+                /**
+                 * Granting to the WebView, not to the user - WKWebView raises its own prompt
+                 * from here and never reports the answer back, so the SDK cannot know whether
+                 * the user allowed it. onDenied is unreachable on this path.
+                 */
+                if (devMode) {
+                    console.log(`${logPrefix} Granting camera permission request on iOS`);
+                }
+                request.grant(resources);
+            }
+            else {
+                if (devMode) {
+                    console.warn(`${logPrefix} Unsupported platform for camera permissions`);
+                }
+                request.deny();
+            }
+        }
+        catch (error) {
+            if (devMode) {
+                console.error(`${logPrefix} Error in handlePermissionRequest:`, error);
+            }
+            request.deny();
+        }
+    }, [logPrefix, onDenied, devMode]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@glomopay/react-native-sdk",
-    "version": "4.1.0",
+    "version": "5.0.0",
     "description": "The React Native SDK for GlomoPay",
     "license": "Apache-2.0",
     "main": "lib/index.js",
@@ -55,26 +55,34 @@
         "axios": "1.13.2"
     },
     "peerDependenciesMeta": {
-        "jail-monkey": {
+        "react-native-blob-util": {
+            "optional": true
+        },
+        "@react-native-documents/picker": {
             "optional": true
         }
     },
     "peerDependencies": {
+        "@react-native-documents/picker": ">=10.1.3",
         "jail-monkey": "^2.6.0",
         "react": ">=17.0.0",
         "react-native": ">=0.68.0",
+        "react-native-blob-util": "^0.25.0",
         "react-native-webview": "^13.0.0"
     },
     "devDependencies": {
+        "@react-native-documents/picker": "^10.1.7",
         "@types/react": "^18.0.0",
         "@types/react-native": "^0.73.0",
         "@typescript-eslint/eslint-plugin": "^8.60.1",
         "eslint": "^9.39.4",
         "eslint-plugin-react-hooks": "^7.1.1",
+        "jail-monkey": "^2.8.5",
         "jest": "^29.6.3",
         "prettier": "^3.0.0",
         "react": "18.2.0",
         "react-native": "0.73.5",
+        "react-native-blob-util": "^0.25.0",
         "typescript": "^5.0.0",
         "typescript-eslint": "^8.60.1"
     },

package/src/bridge/file-input-handler.ts

@@ -0,0 +1,66 @@
+/** The `file.input` bridge message - the user tapped a file input on a bank's page */
+
+import { type WebViewMessageHandler } from "./message-router";
+import { normalizeAcceptTypes } from "../utils/file-metadata";
+import { type FlowType, trackFileUploadRequested } 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 function createFileInputHandler({
+    flowType,
+    orderId,
+    publicKey,
+    checkoutUrl,
+    mockMode,
+    devMode,
+}: CreateFileInputHandlerOptions): WebViewMessageHandler {
+    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}`);
+        }
+
+        trackFileUploadRequested(
+            normalizeAcceptTypes(accept),
+            hasCapture,
+            orderId,
+            publicKey,
+            devMode,
+            mockMode,
+            checkoutUrl,
+            flowType
+        );
+    };
+}

package/src/bridge/file-save-handler.ts

@@ -0,0 +1,141 @@
+/** The `file.save` bridge message, wired once and registered on every WebView that can receive it */
+
+import { type WebViewMessage, type WebViewMessageHandler } from "./message-router";
+import {
+    FILE_SAVE_OUTCOMES,
+    type FileSaveResult,
+    isFileSaveFailure,
+    saveDocumentToDevice,
+    toFileSaveEventData,
+    toFileSaveSdkError,
+} from "../services/file-saver";
+import { EXTENSION_EXTRACTION_FAILED, SIZE_UNAVAILABLE } from "../utils/file-metadata";
+import { type FlowType, type SdkError, trackFileSaveCompleted, trackFileSaveRequested } from "../utils/analytics";
+import { safeCallback } from "../utils/validation";
+
+/** 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;
+}
+
+/**
+ * Correlates the request/completion pair when the page supplies no id.
+ *
+ * Module scope rather than per handler, because the same SDK session registers this on the main and
+ * flow WebViews and a per-handler counter would have both minting `sdk-1`. Saves are not serialised
+ * either - the agreements screen has three download controls, so two taps in quick succession
+ * interleave and would otherwise be indistinguishable in telemetry.
+ */
+let fallbackSaveId = 0;
+
+/** Prefers the page's requestId so one id spans both sides' telemetry. */
+function resolveSaveId(message: WebViewMessage): string {
+    const supplied = message.requestId;
+    if (typeof supplied === "string" && supplied.length > 0) {
+        return supplied;
+    }
+    return `sdk-${++fallbackSaveId}`;
+}
+
+/**
+ * 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 function createFileSaveHandler({
+    flowType,
+    orderId,
+    publicKey,
+    checkoutUrl,
+    mockMode,
+    devMode,
+    onSdkError,
+}: CreateFileSaveHandlerOptions): WebViewMessageHandler {
+    return (message) => {
+        const saveId = resolveSaveId(message);
+
+        const report = (result: FileSaveResult) => {
+            if (devMode) {
+                console.log(`[Glomo-RN-SDK] file.save ${saveId} completed: ${result.outcome}`);
+            }
+            trackFileSaveCompleted(
+                saveId,
+                toFileSaveEventData(result),
+                orderId,
+                publicKey,
+                devMode,
+                mockMode,
+                checkoutUrl,
+                flowType
+            );
+
+            if (isFileSaveFailure(result)) {
+                safeCallback(onSdkError, [[toFileSaveSdkError(result)]], "onSdkError", devMode);
+            }
+        };
+
+        if (devMode) {
+            console.log(`[Glomo-RN-SDK] file.save ${saveId} requested`);
+        }
+        trackFileSaveRequested(saveId, orderId, publicKey, devMode, mockMode, checkoutUrl, flowType);
+
+        const url = message.url;
+        if (typeof url !== "string" || url.length === 0) {
+            /**
+             * Reported rather than dropped. The Flutter SDK returns here without emitting anything
+             * and relies on its error tracker to surface it; RN has none yet, so silence would make
+             * a malformed message invisible. Completing the pair keeps the "every request has an
+             * outcome" invariant that makes a missing completion mean the handler died.
+             */
+            report({
+                outcome: FILE_SAVE_OUTCOMES.REJECTED,
+                fileExtension: EXTENSION_EXTRACTION_FAILED,
+                fileSize: SIZE_UNAVAILABLE,
+                failureType: "missing_url",
+            });
+            return;
+        }
+
+        void saveDocumentToDevice({
+            url,
+            filename: typeof message.filename === "string" ? message.filename : undefined,
+            devMode,
+        })
+            .then(report)
+            .catch((error) => {
+                /**
+                 * saveDocumentToDevice is documented never to throw, so this is the case where that
+                 * promise is broken. It still has to close the pair - and only the failure type
+                 * leaves here, never the message that produced it.
+                 */
+                if (devMode) {
+                    console.error("[Glomo-RN-SDK] file.save handler failed:", error);
+                }
+                report({
+                    outcome: FILE_SAVE_OUTCOMES.SAVE_FAILED,
+                    fileExtension: EXTENSION_EXTRACTION_FAILED,
+                    fileSize: SIZE_UNAVAILABLE,
+                    failureType: "handler_threw",
+                });
+            });
+    };
+}