@glomopay/react-native-sdk 4.1.0 → 5.0.0

package/lib/services/file-saver.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Fetches a document and offers it to the user through the platform save dialog
+ *
+ * This is the whole of the SDK's answer to a `file.save` bridge message. Nothing here is reachable
+ * from the merchant API - the bridge handler is the only caller.
+ *
+ * Exists because there is no web-only way to put a file on the device from inside a WebView:
+ * Android drops `anchor[download]` on a `blob:` URL unless the host registers a DownloadListener,
+ * and the Web Share API is absent from Android WebView entirely. The page sends the message only
+ * after finding `file.save` in the capability list the injection scripts publish.
+ */
+import { type SdkError } from "../utils/analytics";
+/**
+ * How a save attempt ended.
+ *
+ * Named for the condition rather than carrying a message, for the same reason FileSaveResult
+ * carries no filename: every value here reaches telemetry.
+ *
+ * Values are camelCase where this repo's other string enums are snake_case, and the deviation is
+ * deliberate. ASYNC_PAYMENT_EVENTS is merchant-facing API surface, so it follows the SDK's own
+ * convention; this one is telemetry that has to join against the Flutter SDK's already-shipped
+ * `file.save_completed`, where the binding constraint is that `outcome` reads the same on both.
+ */
+export declare enum FILE_SAVE_OUTCOMES {
+    /** The user chose a destination and the bytes were written to it. */
+    SAVED = "saved",
+    /** The save dialog was dismissed without choosing one. A normal user action, not a failure. */
+    DISMISSED = "dismissed",
+    /** The URL failed the scheme check, so no request was made. */
+    REJECTED = "rejected",
+    /** The document could not be fetched: stall, transport, or non-200. */
+    FETCH_FAILED = "fetchFailed",
+    /** Larger than FILE_SAVE_MAX_BYTES. Refused mid-stream, so the excess never reached disk. */
+    TOO_LARGE = "tooLarge",
+    /** The platform refused to present the save dialog, or failed writing to the chosen target. */
+    SAVE_FAILED = "saveFailed",
+    /**
+     * The optional save packages are not usable in this build, so the message should not have been
+     * sent at all.
+     *
+     * No Flutter counterpart - there the two packages are hard dependencies and this state cannot
+     * exist. It is reachable here whenever a page sends `file.save` without gating on the capability
+     * list, which is the failure this outcome exists to make visible rather than silent.
+     */
+    UNAVAILABLE = "unavailable"
+}
+/**
+ * Outcome of one save, shaped for telemetry.
+ *
+ * Carries no filename and no URL. The agreement URLs are signed links - a signed link is a bearer
+ * credential, and the filename is the same class of data file-metadata exists to keep out of events.
+ * Extension and byte count are what a field investigation actually needs.
+ */
+export interface FileSaveResult {
+    outcome: FILE_SAVE_OUTCOMES;
+    /** From extensionOf, so it is a known extension or a sentinel. */
+    fileExtension: string;
+    /** SIZE_UNAVAILABLE when the document was never fetched. */
+    fileSize: number;
+    /** Error name or code, never a message - RN network errors interpolate the full URL. */
+    failureType?: string;
+}
+/** The options for saveDocumentToDevice */
+export interface SaveDocumentOptions {
+    url: string;
+    filename?: string;
+    devMode?: boolean;
+}
+/**
+ * The largest document this will put on the device.
+ *
+ * Held at the Flutter SDK's figure so a merchant does not see one platform refuse what the other
+ * accepts, but the reason differs and that matters if either is ever revisited. Flutter is bounded
+ * by memory: `FilePicker.saveFile` takes bytes, so the whole document is materialised before the
+ * dialog. Here nothing is ever held in memory - blob-util streams to disk and the picker takes a
+ * URI - so this bounds device storage and the user's patience instead.
+ *
+ * Deliberately not justified by agreement PDFs being small. `file.save` is generic device-save
+ * capability, reached by any bank or segment, so a response far past a typical agreement is an
+ * ordinary case rather than evidence of a misrouted URL.
+ */
+export declare const FILE_SAVE_MAX_BYTES: number;
+/**
+ * True for outcomes that mean the user did not get the document.
+ *
+ * Dismissal is excluded: the user was offered the file and declined it.
+ */
+export declare function isFileSaveFailure(result: FileSaveResult): boolean;
+/** The telemetry projection of a result. Everything here is safe to send; the inputs are not. */
+export declare function toFileSaveEventData(result: FileSaveResult): Record<string, unknown>;
+/**
+ * The host-facing form of a failure.
+ *
+ * `validation_error` rather than anything terminal because onSdkError is also the bridge's generic
+ * catch - without a type these arrive mixed with parse failures and a merchant cannot filter them
+ * apart. `field` names the message that produced it for the same reason.
+ *
+ * Must never be routed anywhere that sets checkout status: a document failing to save must not end
+ * the customer's payment session.
+ */
+export declare function toFileSaveSdkError(result: FileSaveResult): SdkError;
+/**
+ * Fetches the document at `url` and offers it to the user.
+ *
+ * Never throws: every failure is an outcome, because the caller is a bridge message handler whose
+ * only other option is to drop the user's tap silently.
+ */
+export declare function saveDocumentToDevice({ url, filename, devMode, }: SaveDocumentOptions): Promise<FileSaveResult>;
+//# sourceMappingURL=file-saver.d.ts.map

package/lib/services/file-saver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-saver.d.ts","sourceRoot":"","sources":["../../src/services/file-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;;;;;;;;GAUG;AACH,oBAAY,kBAAkB;IAC1B,qEAAqE;IACrE,KAAK,UAAU;IAEf,+FAA+F;IAC/F,SAAS,cAAc;IAEvB,+DAA+D;IAC/D,QAAQ,aAAa;IAErB,uEAAuE;IACvE,YAAY,gBAAgB;IAE5B,6FAA6F;IAC7F,SAAS,aAAa;IAEtB,+FAA+F;IAC/F,WAAW,eAAe;IAE1B;;;;;;;OAOG;IACH,WAAW,gBAAgB;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,kBAAkB,CAAC;IAE5B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IAEtB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IAEjB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAuCrD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEjE;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CASnE;AAuED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,EACvC,GAAG,EACH,QAAQ,EACR,OAAe,GAClB,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+M/C"}

package/lib/services/file-saver.js

@@ -0,0 +1,416 @@
+"use strict";
+/**
+ * Fetches a document and offers it to the user through the platform save dialog
+ *
+ * This is the whole of the SDK's answer to a `file.save` bridge message. Nothing here is reachable
+ * from the merchant API - the bridge handler is the only caller.
+ *
+ * Exists because there is no web-only way to put a file on the device from inside a WebView:
+ * Android drops `anchor[download]` on a `blob:` URL unless the host registers a DownloadListener,
+ * and the Web Share API is absent from Android WebView entirely. The page sends the message only
+ * after finding `file.save` in the capability list the injection scripts publish.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_SAVE_MAX_BYTES = exports.FILE_SAVE_OUTCOMES = void 0;
+exports.isFileSaveFailure = isFileSaveFailure;
+exports.toFileSaveEventData = toFileSaveEventData;
+exports.toFileSaveSdkError = toFileSaveSdkError;
+exports.saveDocumentToDevice = saveDocumentToDevice;
+const file_save_1 = require("../capabilities/file-save");
+const file_metadata_1 = require("../utils/file-metadata");
+/** Log prefix. Deliberately unqualified by flow - a save is not owned by one. */
+const LOG_PREFIX = "[Glomo-RN-SDK]";
+/**
+ * How a save attempt ended.
+ *
+ * Named for the condition rather than carrying a message, for the same reason FileSaveResult
+ * carries no filename: every value here reaches telemetry.
+ *
+ * Values are camelCase where this repo's other string enums are snake_case, and the deviation is
+ * deliberate. ASYNC_PAYMENT_EVENTS is merchant-facing API surface, so it follows the SDK's own
+ * convention; this one is telemetry that has to join against the Flutter SDK's already-shipped
+ * `file.save_completed`, where the binding constraint is that `outcome` reads the same on both.
+ */
+var FILE_SAVE_OUTCOMES;
+(function (FILE_SAVE_OUTCOMES) {
+    /** The user chose a destination and the bytes were written to it. */
+    FILE_SAVE_OUTCOMES["SAVED"] = "saved";
+    /** The save dialog was dismissed without choosing one. A normal user action, not a failure. */
+    FILE_SAVE_OUTCOMES["DISMISSED"] = "dismissed";
+    /** The URL failed the scheme check, so no request was made. */
+    FILE_SAVE_OUTCOMES["REJECTED"] = "rejected";
+    /** The document could not be fetched: stall, transport, or non-200. */
+    FILE_SAVE_OUTCOMES["FETCH_FAILED"] = "fetchFailed";
+    /** Larger than FILE_SAVE_MAX_BYTES. Refused mid-stream, so the excess never reached disk. */
+    FILE_SAVE_OUTCOMES["TOO_LARGE"] = "tooLarge";
+    /** The platform refused to present the save dialog, or failed writing to the chosen target. */
+    FILE_SAVE_OUTCOMES["SAVE_FAILED"] = "saveFailed";
+    /**
+     * The optional save packages are not usable in this build, so the message should not have been
+     * sent at all.
+     *
+     * No Flutter counterpart - there the two packages are hard dependencies and this state cannot
+     * exist. It is reachable here whenever a page sends `file.save` without gating on the capability
+     * list, which is the failure this outcome exists to make visible rather than silent.
+     */
+    FILE_SAVE_OUTCOMES["UNAVAILABLE"] = "unavailable";
+})(FILE_SAVE_OUTCOMES || (exports.FILE_SAVE_OUTCOMES = FILE_SAVE_OUTCOMES = {}));
+/**
+ * The largest document this will put on the device.
+ *
+ * Held at the Flutter SDK's figure so a merchant does not see one platform refuse what the other
+ * accepts, but the reason differs and that matters if either is ever revisited. Flutter is bounded
+ * by memory: `FilePicker.saveFile` takes bytes, so the whole document is materialised before the
+ * dialog. Here nothing is ever held in memory - blob-util streams to disk and the picker takes a
+ * URI - so this bounds device storage and the user's patience instead.
+ *
+ * Deliberately not justified by agreement PDFs being small. `file.save` is generic device-save
+ * capability, reached by any bank or segment, so a response far past a typical agreement is an
+ * ordinary case rather than evidence of a misrouted URL.
+ */
+exports.FILE_SAVE_MAX_BYTES = 100 * 1024 * 1024;
+/** Matches the Flutter SDK's fetch timeout, and blob-util applies it to connect only (see below). */
+const CONNECT_TIMEOUT_MS = 30000;
+/**
+ * How long a started download may go without delivering bytes before it is abandoned.
+ *
+ * Needed because blob-util sets `readTimeout(0)` for file-to-disk responses on Android - deliberate
+ * on their side, so a slow but healthy transfer of a large file is not killed by OkHttp's 60s
+ * default. The consequence is that a genuinely wedged socket never resolves, and the user is left
+ * on a button that already reported success.
+ *
+ * A stall bound rather than a total bound: a total timeout large enough for FILE_SAVE_MAX_BYTES on
+ * a slow connection is too large to catch anything, and one small enough to catch a stall would
+ * fail legitimate large downloads. The Flutter SDK applies a 30s total, which is the tradeoff worth
+ * revisiting there now that its own cap is 100 MB.
+ */
+const STALL_TIMEOUT_MS = 30000;
+/** Only the basename survives, and only from an allowlist */
+const UNSAFE_CHARS = /[^A-Za-z0-9._-]/g;
+/** Both sides of this protocol independently default to this, which is why collisions are designed out */
+const DEFAULT_FILENAME = "document.pdf";
+/** Reported when a thrown value carries neither a code nor a name */
+const UNKNOWN_ERROR_TYPE = "UNKNOWN_ERROR_TYPE";
+/** Distinguishes one save's staging directory from another's. Saves are not serialised. */
+let stagingCounter = 0;
+/**
+ * True for outcomes that mean the user did not get the document.
+ *
+ * Dismissal is excluded: the user was offered the file and declined it.
+ */
+function isFileSaveFailure(result) {
+    return result.outcome !== FILE_SAVE_OUTCOMES.SAVED && result.outcome !== FILE_SAVE_OUTCOMES.DISMISSED;
+}
+/** The telemetry projection of a result. Everything here is safe to send; the inputs are not. */
+function toFileSaveEventData(result) {
+    return {
+        outcome: result.outcome,
+        fileExtension: result.fileExtension,
+        fileSize: result.fileSize,
+        ...(result.failureType ? { failureType: result.failureType } : {}),
+    };
+}
+/**
+ * The host-facing form of a failure.
+ *
+ * `validation_error` rather than anything terminal because onSdkError is also the bridge's generic
+ * catch - without a type these arrive mixed with parse failures and a merchant cannot filter them
+ * apart. `field` names the message that produced it for the same reason.
+ *
+ * Must never be routed anywhere that sets checkout status: a document failing to save must not end
+ * the customer's payment session.
+ */
+function toFileSaveSdkError(result) {
+    return {
+        type: "validation_error",
+        message: result.outcome === FILE_SAVE_OUTCOMES.TOO_LARGE
+            ? `Downloads above ${Math.floor(exports.FILE_SAVE_MAX_BYTES / (1024 * 1024))} MB are not supported.`
+            : "Could not save the document to your device.",
+        field: "file.save",
+    };
+}
+/**
+ * https only, except on loopback.
+ *
+ * isValidUrl admits any http URL, which is right for bank redirects and wrong here: this fetch
+ * carries a signed link and its bytes become a document the user is told is theirs. The loopback
+ * exception is what lets the checkout page's dev mock server serve agreements over http.
+ *
+ * Gated on `devMode`, so a release build is https-only with no exception at all. Ungated, a page
+ * could point a production build at a service listening on the customer's own device and have the
+ * response written to their files - a dev convenience is not worth a hole in the one rule this
+ * function exists to enforce.
+ *
+ * Loopback only, and deliberately not the Android emulator's `10.0.2.2` alias for the host:
+ * reaching a dev server from an emulator is what `adb reverse` is for, which keeps the host
+ * `localhost` on both platforms. No other private address belongs in shipped code.
+ */
+function isFetchableUrl(url, devMode) {
+    var _a, _b, _c;
+    const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/?#]+)/.exec(url);
+    if (!match) {
+        return false;
+    }
+    const scheme = match[1].toLowerCase();
+    // Host only - a userinfo or port section must not be mistaken for one
+    const host = (_c = (_b = (_a = match[2].split("@").pop()) === null || _a === void 0 ? void 0 : _a.split(":")[0]) === null || _b === void 0 ? void 0 : _b.toLowerCase()) !== null && _c !== void 0 ? _c : "";
+    if (scheme === "https") {
+        return true;
+    }
+    return devMode && scheme === "http" && (host === "localhost" || host === "127.0.0.1");
+}
+/**
+ * Basename, allowlisted, with a `.pdf` default.
+ *
+ * The page supplies this and it becomes a path segment under the staging directory, so it is
+ * untrusted input: `../../databases/x` would otherwise escape. Falls back to the URL's last
+ * segment, then to a constant.
+ */
+function sanitize(name) {
+    var _a, _b, _c;
+    if (!name) {
+        return null;
+    }
+    const base = (_c = (_b = (_a = name.split("/").pop()) === null || _a === void 0 ? void 0 : _a.split("\\").pop()) === null || _b === void 0 ? void 0 : _b.trim()) !== null && _c !== void 0 ? _c : "";
+    const cleaned = base.replace(UNSAFE_CHARS, "_");
+    // A name that is only dots and separators sanitises to something like `..`, still a traversal
+    if (cleaned.length === 0 || cleaned.replace(/\./g, "").length === 0) {
+        return null;
+    }
+    return cleaned.length > 100 ? cleaned.slice(cleaned.length - 100) : cleaned;
+}
+/** Prefers what the page asked for, then what the URL implies, then a constant. */
+function resolveFilename(supplied, url) {
+    const path = url.split("?")[0].split("#")[0];
+    const fromUrl = path.split("/").pop();
+    for (const candidate of [supplied, fromUrl]) {
+        const cleaned = sanitize(candidate);
+        if (cleaned) {
+            return cleaned;
+        }
+    }
+    return DEFAULT_FILENAME;
+}
+/**
+ * Fetches the document at `url` and offers it to the user.
+ *
+ * Never throws: every failure is an outcome, because the caller is a bridge message handler whose
+ * only other option is to drop the user's tap silently.
+ */
+async function saveDocumentToDevice({ url, filename, devMode = false, }) {
+    var _a, _b;
+    /**
+     * Resolved before every other check so a rejection still reports the real extension rather than
+     * the EXTRACTION_FAILED sentinel, which means something else entirely. Neither call touches the
+     * network or the filesystem.
+     */
+    const safeName = resolveFilename(filename, url);
+    const fileExtension = (0, file_metadata_1.extensionOf)(safeName);
+    const failed = (outcome, failureType, fileSize = file_metadata_1.SIZE_UNAVAILABLE) => ({
+        outcome,
+        fileExtension,
+        fileSize,
+        ...(failureType ? { failureType } : {}),
+    });
+    if (!isFetchableUrl(url, devMode)) {
+        if (devMode) {
+            console.log(`${LOG_PREFIX} file.save rejected: unsupported URL scheme`);
+        }
+        return failed(FILE_SAVE_OUTCOMES.REJECTED);
+    }
+    const blobUtil = (0, file_save_1.loadBlobUtil)();
+    const picker = (0, file_save_1.loadDocumentPicker)();
+    if (!blobUtil || !picker) {
+        // Reachable only from a page that sent the message without gating on the capability list
+        if (devMode) {
+            console.warn(`${LOG_PREFIX} file.save received but the save packages are not usable in this build`);
+        }
+        return failed(FILE_SAVE_OUTCOMES.UNAVAILABLE);
+    }
+    /**
+     * A directory this SDK owns, unique per save.
+     *
+     * The Flutter SDK has to hunt for a free name because `file_picker` stages into the app
+     * documents directory under the page-chosen name and deletes whatever is already there. Nothing
+     * equivalent applies here: the destination path is ours to choose, so a page-supplied name can
+     * only ever land inside this directory, and two concurrent saves of the same name cannot meet.
+     * The name still has to survive `sanitize` because it is a path segment either way - and on iOS
+     * it is also the name the dialog pre-fills, which is taken from the source URI.
+     */
+    const stagingDirectory = `${blobUtil.fs.dirs.CacheDir}/glomopay-file-save/${Date.now()}-${++stagingCounter}`;
+    const stagingPath = `${stagingDirectory}/${safeName}`;
+    let cancelReason = null;
+    let stallTimer;
+    try {
+        await blobUtil.fs.mkdir(stagingDirectory);
+    }
+    catch (error) {
+        return failed(FILE_SAVE_OUTCOMES.SAVE_FAILED, errorTypeOf(error));
+    }
+    try {
+        const task = blobUtil
+            .config({ path: stagingPath, timeout: CONNECT_TIMEOUT_MS, overwrite: true })
+            .fetch("GET", url);
+        const cancelWith = (reason) => {
+            if (cancelReason) {
+                return;
+            }
+            cancelReason = reason;
+            task.cancel();
+        };
+        const armStallTimer = () => {
+            if (stallTimer) {
+                clearTimeout(stallTimer);
+            }
+            stallTimer = setTimeout(() => cancelWith({ outcome: FILE_SAVE_OUTCOMES.FETCH_FAILED, failureType: "stalled" }), STALL_TIMEOUT_MS);
+        };
+        armStallTimer();
+        task.progress({ count: -1, interval: 250 }, (received, total) => {
+            armStallTimer();
+            /**
+             * Content-Length first when the server sends one, so an oversized response is refused
+             * before any of it reaches disk; the running total is the backstop for chunked
+             * responses that send none.
+             */
+            const advertised = total > 0 ? total : file_metadata_1.SIZE_UNAVAILABLE;
+            if (advertised > exports.FILE_SAVE_MAX_BYTES || received > exports.FILE_SAVE_MAX_BYTES) {
+                cancelWith({
+                    outcome: FILE_SAVE_OUTCOMES.TOO_LARGE,
+                    size: advertised > 0 ? advertised : received,
+                });
+            }
+        });
+        const response = await task;
+        /**
+         * Disarmed here rather than only in `finally`, because `finally` does not run until the
+         * picker has resolved and the user may sit in it for minutes choosing a folder. A timer
+         * left armed across that would fire on a settled request - harmless, since blob-util
+         * replaces `cancel` with a no-op once the promise settles, but it is a live timer holding
+         * this closure for no reason.
+         */
+        if (stallTimer) {
+            clearTimeout(stallTimer);
+            stallTimer = undefined;
+        }
+        /**
+         * A cancel we asked for does not always reject. blob-util makes `cancel` a no-op once the
+         * promise has settled, so a response that crosses the cap and finishes inside the 250ms
+         * before the next progress tick resolves normally with the oversized body already on disk.
+         * Checked here as well as in the catch, or the cap silently does not apply in the one case
+         * it exists for - a chunked response whose Content-Length could not refuse it up front.
+         */
+        if (cancelReason) {
+            const reason = cancelReason;
+            return failed(reason.outcome, reason.failureType, (_a = reason.size) !== null && _a !== void 0 ? _a : file_metadata_1.SIZE_UNAVAILABLE);
+        }
+        const info = response.info();
+        /**
+         * blob-util resolves on any status and writes the body regardless, so an error page is on
+         * disk at this point rather than the document
+         */
+        if (info.status !== 200) {
+            return failed(FILE_SAVE_OUTCOMES.FETCH_FAILED, `http_${info.status}`);
+        }
+        /**
+         * The scheme allowlist only ever saw the URL the page sent, and redirects are followed -
+         * OkHttp and NSURLSession both allow an https to http downgrade by default, so a signed
+         * link can land the document on a plaintext hop without isFetchableUrl being consulted
+         * again. Checking the chain after the fact cannot un-fetch those bytes, but it can decline
+         * to hand the user a document that travelled in the clear.
+         *
+         * The chain entries are full URLs, so they are signed links themselves: read here, never
+         * reported. The Flutter SDK has the same gap and no equivalent check.
+         */
+        const redirects = info.redirects;
+        if (Array.isArray(redirects) &&
+            !redirects.every((hop) => typeof hop === "string" && isFetchableUrl(hop, devMode))) {
+            if (devMode) {
+                console.log(`${LOG_PREFIX} file.save rejected: redirected through an unsupported scheme`);
+            }
+            return failed(FILE_SAVE_OUTCOMES.REJECTED, "insecure_redirect");
+        }
+        const fileSize = await sizeOf(blobUtil, stagingPath);
+        try {
+            /**
+             * `copy: false` is iOS-only and is the default - the staged file is moved to where the
+             * user chose, which is what keeps a copy from being left behind in the app container.
+             * Android always copies and the cleanup below is what handles it there.
+             *
+             * `mimeType` is derived from the extension rather than forwarded from the page. Android
+             * puts it straight onto an `ACTION_CREATE_DOCUMENT` intent, and the page's field is
+             * untrusted; the Flutter SDK declines to forward the same field for the same reason.
+             */
+            await picker.saveDocuments({
+                sourceUris: [encodeURI(`file://${stagingPath}`)],
+                fileName: safeName,
+                mimeType: (0, file_metadata_1.mimeTypeFor)(fileExtension),
+                copy: false,
+            });
+            return { outcome: FILE_SAVE_OUTCOMES.SAVED, fileExtension, fileSize };
+        }
+        catch (error) {
+            if (picker.isErrorWithCode(error) && error.code === picker.errorCodes.OPERATION_CANCELED) {
+                return { outcome: FILE_SAVE_OUTCOMES.DISMISSED, fileExtension, fileSize };
+            }
+            if (devMode) {
+                console.error(`${LOG_PREFIX} file.save dialog failed:`, errorTypeOf(error));
+            }
+            return failed(FILE_SAVE_OUTCOMES.SAVE_FAILED, errorTypeOf(error), fileSize);
+        }
+    }
+    catch (error) {
+        // A cancel this code asked for rejects the fetch exactly as a transport failure does
+        if (cancelReason) {
+            const reason = cancelReason;
+            return failed(reason.outcome, reason.failureType, (_b = reason.size) !== null && _b !== void 0 ? _b : file_metadata_1.SIZE_UNAVAILABLE);
+        }
+        if (devMode) {
+            console.error(`${LOG_PREFIX} file.save fetch failed:`, errorTypeOf(error));
+        }
+        return failed(FILE_SAVE_OUTCOMES.FETCH_FAILED, errorTypeOf(error));
+    }
+    finally {
+        if (stallTimer) {
+            clearTimeout(stallTimer);
+        }
+        // Recursive on both platforms, and a no-op once iOS has moved the file out
+        try {
+            await blobUtil.fs.unlink(stagingDirectory);
+        }
+        catch (error) {
+            if (devMode) {
+                console.error(`${LOG_PREFIX} file.save could not clear the staging directory:`, errorTypeOf(error));
+            }
+        }
+    }
+}
+/** Size of what was staged, or the sentinel. Never fatal - the document is already on disk. */
+async function sizeOf(blobUtil, path) {
+    try {
+        const stat = await blobUtil.fs.stat(path);
+        const size = Number(stat.size);
+        return Number.isFinite(size) ? size : file_metadata_1.SIZE_UNAVAILABLE;
+    }
+    catch (_a) {
+        return file_metadata_1.SIZE_UNAVAILABLE;
+    }
+}
+/**
+ * The name or code of a thrown value, never its message.
+ *
+ * RN's network errors and blob-util's own both interpolate the request URL into `message`, which is
+ * the signed link. A sentinel rather than an omission, so the field is always present and "could
+ * not tell" is something to filter on.
+ */
+function errorTypeOf(error) {
+    if (error && typeof error === "object") {
+        const candidate = error;
+        if (typeof candidate.code === "string" && candidate.code.length > 0) {
+            return candidate.code;
+        }
+        if (typeof candidate.name === "string" && candidate.name.length > 0) {
+            return candidate.name;
+        }
+    }
+    return UNKNOWN_ERROR_TYPE;
+}

package/lib/types/checkout.d.ts

@@ -1,11 +1,20 @@
-/** Unified v4 type definitions for GlomoCheckout */
+/** Unified type definitions for GlomoCheckout */
 import { type GlomoServer } from "../config/base";
 import { type SdkError } from "../utils/analytics";
-/** The payload for a successful or failed payment (unified across LRS and standard) */
+/**
+ * The payload for a successful or failed payment (unified across LRS and standard)
+ *
+ * `paymentId` and `signature` are optional as of 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 used to drop those outcomes entirely rather than report an incomplete one.
+ *
+ * With `strict` on, this lands as a compile error anywhere the value is forwarded to something
+ * expecting a `string`, which is the point: the narrowing check is the guardrail, not a nuisance.
+ */
 export interface GlomoCheckoutPayload {
     orderId: string;
-    paymentId: string;
-    signature: string;
+    paymentId?: string;
+    signature?: string;
 }
 /**
  * Enum of asynchronous payment events that trigger the
@@ -24,6 +33,40 @@ export interface GlomoUserJourneyCompletedPayload {
     senderAccountNumber?: string;
     transactionReference?: string;
 }
+/**
+ * How a checkout ended, when it ended without a payment outcome.
+ *
+ * **Must stay exhaustive by construction.** Any future call site that terminates a checkout adds a
+ * member here rather than passing `undefined` or a catch-all - the whole value of "the payload
+ * always carries its source" is in the "always", and one lazy call site turns `source` into a field
+ * every merchant has to null-check.
+ *
+ * Deliberately does not include the back chevron over the bank flow. That returns the user to the
+ * main 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 user backed out of one bank to try another.
+ */
+export declare enum TERMINATION_SOURCES {
+    /** The checkout page's own close control, over the bridge as `checkout.closed` */
+    CHECKOUT_CLOSED = "checkout_closed",
+    /** Android hardware back or the back gesture */
+    DEVICE_BACK_BUTTON = "device_back_button",
+    /** iOS swipe-down on the pageSheet */
+    MODAL_DISMISS = "modal_dismiss"
+}
+/**
+ * The payload for the onPaymentTerminate callback.
+ *
+ * An object rather than a bare enum because every other callback in this SDK takes one, and because
+ * the source alone is not extensible: a later confirmation step would otherwise have to arrive as a
+ * second positional parameter, or silently change what an existing value means.
+ *
+ * The source describes **how** the checkout ended. The **why**, where there is one, already reached
+ * the host through the callback it got first.
+ */
+export interface GlomoTerminationPayload {
+    source: TERMINATION_SOURCES;
+}
 /** Unified checkout statuses - superset of LRS + standard statuses */
 export type CheckoutStatus = "ready" | "detecting_order_type" | "payment_in_progress" | "payment_successful" | "payment_failed" | "payment_cancelled" | "bank_transfer_submitted" | "pay_via_bank_completed";
 /**
@@ -51,10 +94,19 @@ interface GlomoCheckoutBaseProps {
     onPaymentSuccess: (payload: GlomoCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
-    onPaymentTerminate?: () => void;
+    onPaymentTerminate?: (payload: GlomoTerminationPayload) => void;
     onSdkError: (error: Array<SdkError>) => void;
+    /**
+     * Optional callback for asynchronous payment journeys - bank transfers and pay via bank.
+     * Carries the journey type and the transfer details the page reported, not a confirmed payment.
+     *
+     * Accepted here because this component is a union over both flows, but **silently ignored on
+     * LRS orders**: LRS never produces an asynchronous journey, so nothing forwards it. If your
+     * orders are LRS-only you can leave it out entirely - supplying it is not an error, it simply
+     * never fires. Terminal LRS outcomes arrive through onPaymentSuccess and onPaymentFailure.
+     */
     onUserJourneyCompleted?: (payload: GlomoUserJourneyCompletedPayload) => void;
-    onUserRefusedCameraPermissions?: () => void;
+    onUserRefusedDevicePermissions?: () => void;
     devMode?: boolean;
 }
 /**

package/lib/types/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/types/checkout.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,oBAAY,oBAAoB;IAC5B,uBAAuB,4BAA4B;IACnD,sBAAsB,2BAA2B;CACpD;AAED,0DAA0D;AAC1D,MAAM,WAAW,gCAAgC;IAC7C,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,sEAAsE;AACtE,MAAM,MAAM,cAAc,GACpB,OAAO,GACP,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,mBAAmB,GACnB,yBAAyB,GACzB,wBAAwB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,eAAe,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;IACrC,+BAA+B,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,iFAAiF;AACjF,UAAU,sBAAsB;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC1D,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC1D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC7C,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,KAAK,IAAI,CAAC;IAC7E,8BAA8B,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GACnD,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/types/checkout.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,oBAAY,oBAAoB;IAC5B,uBAAuB,4BAA4B;IACnD,sBAAsB,2BAA2B;CACpD;AAED,0DAA0D;AAC1D,MAAM,WAAW,gCAAgC;IAC7C,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,oBAAY,mBAAmB;IAC3B,kFAAkF;IAClF,eAAe,oBAAoB;IAEnC,gDAAgD;IAChD,kBAAkB,uBAAuB;IAEzC,sCAAsC;IACtC,aAAa,kBAAkB;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACpC,MAAM,EAAE,mBAAmB,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,MAAM,cAAc,GACpB,OAAO,GACP,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,mBAAmB,GACnB,yBAAyB,GACzB,wBAAwB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACvC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,eAAe,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;IACrC,+BAA+B,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,iFAAiF;AACjF,UAAU,sBAAsB;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC1D,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC1D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChE,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC7C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,KAAK,IAAI,CAAC;IAC7E,8BAA8B,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GACnD,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC"}

package/lib/types/checkout.js

@@ -1,7 +1,7 @@
 "use strict";
-/** Unified v4 type definitions for GlomoCheckout */
+/** Unified type definitions for GlomoCheckout */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ASYNC_PAYMENT_EVENTS = void 0;
+exports.TERMINATION_SOURCES = exports.ASYNC_PAYMENT_EVENTS = void 0;
 /**
  * Enum of asynchronous payment events that trigger the
  * onUserJourneyCompleted callback. New events will be added
@@ -12,3 +12,25 @@ var ASYNC_PAYMENT_EVENTS;
     ASYNC_PAYMENT_EVENTS["BANK_TRANSFER_SUBMITTED"] = "bank_transfer_submitted";
     ASYNC_PAYMENT_EVENTS["PAY_VIA_BANK_COMPLETED"] = "pay_via_bank_completed";
 })(ASYNC_PAYMENT_EVENTS || (exports.ASYNC_PAYMENT_EVENTS = ASYNC_PAYMENT_EVENTS = {}));
+/**
+ * How a checkout ended, when it ended without a payment outcome.
+ *
+ * **Must stay exhaustive by construction.** Any future call site that terminates a checkout adds a
+ * member here rather than passing `undefined` or a catch-all - the whole value of "the payload
+ * always carries its source" is in the "always", and one lazy call site turns `source` into a field
+ * every merchant has to null-check.
+ *
+ * Deliberately does not include the back chevron over the bank flow. That returns the user to the
+ * main 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 user backed out of one bank to try another.
+ */
+var TERMINATION_SOURCES;
+(function (TERMINATION_SOURCES) {
+    /** The checkout page's own close control, over the bridge as `checkout.closed` */
+    TERMINATION_SOURCES["CHECKOUT_CLOSED"] = "checkout_closed";
+    /** Android hardware back or the back gesture */
+    TERMINATION_SOURCES["DEVICE_BACK_BUTTON"] = "device_back_button";
+    /** iOS swipe-down on the pageSheet */
+    TERMINATION_SOURCES["MODAL_DISMISS"] = "modal_dismiss";
+})(TERMINATION_SOURCES || (exports.TERMINATION_SOURCES = TERMINATION_SOURCES = {}));