@glomopay/react-native-sdk 4.1.0 → 5.0.0

package/src/services/file-saver.ts

@@ -0,0 +1,497 @@
+/**
+ * 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 { loadBlobUtil, loadDocumentPicker } from "../capabilities/file-save";
+import { SIZE_UNAVAILABLE, extensionOf, mimeTypeFor } from "../utils/file-metadata";
+import { type SdkError } from "../utils/analytics";
+
+/** 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.
+ */
+export 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 const 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 = 30_000;
+
+/**
+ * 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 = 30_000;
+
+/** Distinguishes a cancel this code asked for from a transport failure, which look identical. */
+interface CancelReason {
+    outcome: FILE_SAVE_OUTCOMES;
+    failureType?: string;
+    size?: number;
+}
+
+/** 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.
+ */
+export function isFileSaveFailure(result: FileSaveResult): boolean {
+    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. */
+export function toFileSaveEventData(result: FileSaveResult): Record<string, unknown> {
+    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.
+ */
+export function toFileSaveSdkError(result: FileSaveResult): SdkError {
+    return {
+        type: "validation_error",
+        message:
+            result.outcome === FILE_SAVE_OUTCOMES.TOO_LARGE
+                ? `Downloads above ${Math.floor(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: string, devMode: boolean): boolean {
+    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 = match[2].split("@").pop()?.split(":")[0]?.toLowerCase() ?? "";
+
+    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?: string | null): string | null {
+    if (!name) {
+        return null;
+    }
+
+    const base = name.split("/").pop()?.split("\\").pop()?.trim() ?? "";
+    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: string | undefined, url: string): string {
+    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.
+ */
+export async function saveDocumentToDevice({
+    url,
+    filename,
+    devMode = false,
+}: SaveDocumentOptions): Promise<FileSaveResult> {
+    /**
+     * 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 = extensionOf(safeName);
+    const failed = (outcome: FILE_SAVE_OUTCOMES, failureType?: string, fileSize = 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 = loadBlobUtil();
+    const picker = 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: CancelReason | null = null;
+    let stallTimer: ReturnType<typeof setTimeout> | undefined;
+
+    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: CancelReason) => {
+            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 : SIZE_UNAVAILABLE;
+            if (advertised > FILE_SAVE_MAX_BYTES || received > 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 = cancelReason;
+            return failed(reason.outcome, reason.failureType, reason.size ?? 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: 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 = cancelReason;
+            return failed(reason.outcome, reason.failureType, reason.size ?? 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: NonNullable<ReturnType<typeof loadBlobUtil>>, path: string): Promise<number> {
+    try {
+        const stat = await blobUtil.fs.stat(path);
+        const size = Number(stat.size);
+        return Number.isFinite(size) ? size : SIZE_UNAVAILABLE;
+    } catch {
+        return 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: unknown): string {
+    if (error && typeof error === "object") {
+        const candidate = error as { code?: unknown; name?: unknown };
+        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/src/types/checkout.ts

@@ -1,13 +1,22 @@
-/** 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;
 }
 
 /**
@@ -29,6 +38,44 @@ export interface GlomoUserJourneyCompletedPayload {
     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 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"
@@ -67,10 +114,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/src/types/standard-checkout.ts

@@ -2,7 +2,7 @@
 
 import { type GlomoServer } from "../config/base";
 import { type SdkError } from "../utils/analytics";
-import { type GlomoUserJourneyCompletedPayload } from "./checkout";
+import { type GlomoTerminationPayload, type GlomoUserJourneyCompletedPayload } from "./checkout";
 
 /** Standard checkout statuses */
 export type StandardCheckoutStatus =
@@ -14,11 +14,11 @@ export type StandardCheckoutStatus =
     | "bank_transfer_submitted"
     | "pay_via_bank_completed";
 
-/** The payload for a successful or failed standard payment */
+/** The payload for a successful or failed standard payment. See GlomoCheckoutPayload on the optional fields. */
 export interface GlomoStandardCheckoutPayload {
     orderId: string;
-    paymentId: string;
-    signature: string;
+    paymentId?: string;
+    signature?: string;
 }
 
 /**
@@ -39,9 +39,9 @@ export interface GlomoStandardCheckoutProps {
     onPaymentSuccess: (payload: GlomoStandardCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoStandardCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
-    onPaymentTerminate?: () => void;
+    onPaymentTerminate?: (payload: GlomoTerminationPayload) => void;
     onSdkError: (error: Array<SdkError>) => void;
     onUserJourneyCompleted?: (payload: GlomoUserJourneyCompletedPayload) => void;
-    onUserRefusedCameraPermissions?: () => void;
+    onUserRefusedDevicePermissions?: () => void;
     devMode?: boolean;
 }

package/src/types/subscriptions-checkout.ts

@@ -2,7 +2,11 @@
 
 import { type GlomoServer } from "../config/base";
 import { type SdkError } from "../utils/analytics";
-import { type GlomoCheckoutPayload, type GlomoUserJourneyCompletedPayload } from "./checkout";
+import {
+    type GlomoCheckoutPayload,
+    type GlomoTerminationPayload,
+    type GlomoUserJourneyCompletedPayload,
+} from "./checkout";
 import { type StandardCheckoutStatus } from "./standard-checkout";
 
 /** Props for the subscriptions checkout component */
@@ -13,10 +17,10 @@ export interface GlomoSubscriptionsCheckoutProps {
     onPaymentSuccess: (payload: GlomoCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
-    onPaymentTerminate?: () => void;
+    onPaymentTerminate?: (payload: GlomoTerminationPayload) => void;
     onSdkError: (error: Array<SdkError>) => void;
     onUserJourneyCompleted?: (payload: GlomoUserJourneyCompletedPayload) => void;
-    onUserRefusedCameraPermissions?: () => void;
+    onUserRefusedDevicePermissions?: () => void;
     devMode?: boolean;
     /** Internal prop for automated tests - forwarded to GlomoStandardCheckoutInternal via rest spread */
     _testInjectionScript?: string;

package/src/use-glomo-checkout.tsx

@@ -10,7 +10,7 @@ import { type GlomoLrsCheckoutRef } from "./glomo-lrs-checkout";
 import { type GlomoStandardCheckoutRef } from "./types/standard-checkout";
 import { type GlomoSubscriptionsCheckoutRef } from "./types/subscriptions-checkout";
 import { type OrderType, fetchOrderType } from "./services/order-type-fetcher";
-import { isValidPublicKey, isValidOrderId, safeCallback } from "./utils/validation";
+import { isValidPublicKey, isValidOrderId, isMockModeKey, safeCallback } from "./utils/validation";
 import {
     type SdkError,
     trackOrderTypeDetectionStarted,
@@ -85,7 +85,7 @@ export function useGlomoCheckout(
 
     // One-time deprecation warning for direct merchant usage
     const suppressWarning = internalOptions?._suppressDeprecationWarning ?? false;
-    const mockMode = publicKey?.toLowerCase().startsWith("test_") ?? false;
+    const mockMode = isMockModeKey(publicKey);
     const hasWarnedRef = useRef(false);
     useEffect(() => {
         if (!hasWarnedRef.current && !suppressWarning) {