@glomopay/react-native-sdk 2.0.2 → 3.1.0

package/lib/types/checkout.d.ts

@@ -0,0 +1,65 @@
+/** Unified v3 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) */
+export interface GlomoCheckoutPayload {
+    orderId: string;
+    paymentId: string;
+    signature: string;
+}
+/** The payload for a bank transfer submission */
+export interface GlomoBankTransferPayload {
+    orderId: string;
+    senderAccountNumber: string;
+    transactionReference: string;
+}
+/** The payload for a pay via bank - bank connection successful event */
+export interface GlomoPayViaBankConnectionPayload {
+    bankIdentifier: string;
+    cooldownPeriodInMinutes: number;
+    bankName: string;
+    bankImageSrc: string;
+    bankImageAlt: string;
+}
+/** 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";
+/**
+ * Ref handle for the unified checkout component.
+ * start() is async (returns Promise<boolean>) because the unified flow first detects order type
+ * via an API call before delegating to either the LRS or Standard inner component.
+ */
+export interface GlomoCheckoutRef {
+    start: () => Promise<boolean>;
+    getStatus: () => CheckoutStatus;
+}
+/** Shared callback and configuration props for the unified checkout component */
+interface GlomoCheckoutBaseProps {
+    server?: GlomoServer;
+    publicKey: string;
+    onPaymentSuccess: (payload: GlomoCheckoutPayload) => void;
+    onPaymentFailure: (payload: GlomoCheckoutPayload) => void;
+    onConnectionError?: (error: unknown) => void;
+    onPaymentTerminate?: () => void;
+    onSdkError?: (error: Array<SdkError>) => void;
+    onBankTransferSubmitted?: (payload: GlomoBankTransferPayload | null | undefined) => void;
+    onPayViaBankCompleted?: (payload: {
+        status: string;
+    }) => void;
+    onPayViaBankBankConnectionSuccessful?: (payload: GlomoPayViaBankConnectionPayload | null | undefined) => void;
+    onUserRefusedCameraPermissions?: () => void;
+    devMode?: boolean;
+}
+/**
+ * Props for the unified checkout component.
+ * Exactly one of orderId or subscriptionId must be provided.
+ * TypeScript enforces this at compile time; a runtime guard in useGlomoCheckout catches JS consumers.
+ */
+export type GlomoCheckoutProps = GlomoCheckoutBaseProps & ({
+    orderId: string;
+    subscriptionId?: never;
+} | {
+    subscriptionId: string;
+    orderId?: never;
+});
+export {};
+//# sourceMappingURL=checkout.d.ts.map

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

@@ -0,0 +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,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,wEAAwE;AACxE,MAAM,WAAW,gCAAgC;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACxB;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,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,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC9C,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;IACzF,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9D,oCAAoC,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;IAC9G,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

@@ -0,0 +1,3 @@
+"use strict";
+/** Unified v3 type definitions for GlomoCheckout */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/standard-checkout.d.ts

@@ -0,0 +1,40 @@
+/** Type definitions for the Standard Checkout flow */
+import { type GlomoServer } from "../config/base";
+import { type SdkError } from "../utils/analytics";
+import { type GlomoBankTransferPayload, type GlomoPayViaBankConnectionPayload } from "./checkout";
+/** Standard checkout statuses */
+export type StandardCheckoutStatus = "ready" | "payment_in_progress" | "payment_successful" | "payment_failed" | "payment_cancelled" | "bank_transfer_submitted" | "pay_via_bank_completed";
+/** The payload for a successful or failed standard payment */
+export interface GlomoStandardCheckoutPayload {
+    orderId: string;
+    paymentId: string;
+    signature: string;
+}
+/**
+ * Ref handle for the standard checkout component.
+ * start() is synchronous (returns boolean) because the standard flow does not need to detect
+ * order type - unlike the unified GlomoCheckoutRef whose start() is async (returns Promise<boolean>).
+ */
+export interface GlomoStandardCheckoutRef {
+    start: () => boolean;
+    getStatus: () => StandardCheckoutStatus;
+}
+/** Props for the standard checkout component */
+export interface GlomoStandardCheckoutProps {
+    server?: GlomoServer;
+    publicKey: string;
+    orderId: string;
+    onPaymentSuccess: (payload: GlomoStandardCheckoutPayload) => void;
+    onPaymentFailure: (payload: GlomoStandardCheckoutPayload) => void;
+    onConnectionError?: (error: unknown) => void;
+    onPaymentTerminate?: () => void;
+    onSdkError?: (error: Array<SdkError>) => void;
+    onBankTransferSubmitted?: (payload: GlomoBankTransferPayload | null | undefined) => void;
+    onPayViaBankCompleted?: (payload: {
+        status: string;
+    }) => void;
+    onPayViaBankBankConnectionSuccessful?: (payload: GlomoPayViaBankConnectionPayload | null | undefined) => void;
+    onUserRefusedCameraPermissions?: () => void;
+    devMode?: boolean;
+}
+//# sourceMappingURL=standard-checkout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standard-checkout.d.ts","sourceRoot":"","sources":["../../src/types/standard-checkout.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,KAAK,wBAAwB,EAAE,KAAK,gCAAgC,EAAE,MAAM,YAAY,CAAC;AAElG,iCAAiC;AACjC,MAAM,MAAM,sBAAsB,GAC5B,OAAO,GACP,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,mBAAmB,GACnB,yBAAyB,GACzB,wBAAwB,CAAC;AAE/B,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,sBAAsB,CAAC;CAC3C;AAED,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,CAAC,OAAO,EAAE,4BAA4B,KAAK,IAAI,CAAC;IAClE,gBAAgB,EAAE,CAAC,OAAO,EAAE,4BAA4B,KAAK,IAAI,CAAC;IAClE,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC9C,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;IACzF,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9D,oCAAoC,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;IAC9G,8BAA8B,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/lib/types/standard-checkout.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the Standard Checkout flow */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/subscriptions-checkout.d.ts

@@ -0,0 +1,29 @@
+/** Type definitions for the Subscriptions Checkout flow */
+import { type GlomoServer } from "../config/base";
+import { type SdkError } from "../utils/analytics";
+import { type GlomoCheckoutPayload, type GlomoPayViaBankConnectionPayload } from "./checkout";
+import { type StandardCheckoutStatus } from "./standard-checkout";
+/** Props for the subscriptions checkout component */
+export interface GlomoSubscriptionsCheckoutProps {
+    server?: GlomoServer;
+    publicKey: string;
+    subscriptionId: string;
+    onPaymentSuccess: (payload: GlomoCheckoutPayload) => void;
+    onPaymentFailure: (payload: GlomoCheckoutPayload) => void;
+    onConnectionError?: (error: unknown) => void;
+    onPaymentTerminate?: () => void;
+    onSdkError?: (error: Array<SdkError>) => void;
+    onPayViaBankBankConnectionSuccessful?: (payload: GlomoPayViaBankConnectionPayload | null | undefined) => void;
+    onUserRefusedCameraPermissions?: () => void;
+    devMode?: boolean;
+}
+/**
+ * Ref handle for the subscriptions checkout component.
+ * Same type as GlomoStandardCheckoutRef - start() is async at the unified level
+ * but delegates to the synchronous standard checkout start() internally.
+ */
+export interface GlomoSubscriptionsCheckoutRef {
+    start: () => boolean;
+    getStatus: () => StandardCheckoutStatus;
+}
+//# sourceMappingURL=subscriptions-checkout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions-checkout.d.ts","sourceRoot":"","sources":["../../src/types/subscriptions-checkout.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAE3D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,gCAAgC,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,qDAAqD;AACrD,MAAM,WAAW,+BAA+B;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,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,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC9C,oCAAoC,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC;IAC9G,8BAA8B,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC1C,KAAK,EAAE,MAAM,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,sBAAsB,CAAC;CAC3C"}

package/lib/types/subscriptions-checkout.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the Subscriptions Checkout flow */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/use-glomo-checkout.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Unified wrapper hook - detects order type (LRS vs Standard) via the order API
+ * and delegates to the appropriate inner checkout hook once resolved.
+ */
+import { type GlomoCheckoutProps, type CheckoutStatus } from "./types/checkout";
+import { type GlomoLrsCheckoutRef } from "./glomo-lrs-checkout";
+import { type GlomoStandardCheckoutRef } from "./types/standard-checkout";
+import { type GlomoSubscriptionsCheckoutRef } from "./types/subscriptions-checkout";
+import { type OrderType } from "./services/order-type-fetcher";
+/** Extended order type including subscriptions */
+type ExtendedOrderType = OrderType | "subscriptions";
+/**
+ * Public return type for useGlomoCheckout.
+ * Exposes only start() and getStatus() - no internal refs or state.
+ */
+export interface UseGlomoCheckoutReturn {
+    start: () => Promise<boolean>;
+    getStatus: () => CheckoutStatus;
+}
+/**
+ * Internal return type - used by GlomoCheckout component.
+ * Not exported from the public API.
+ */
+export interface UseGlomoCheckoutInternalReturn {
+    orderType: ExtendedOrderType | null;
+    detecting: boolean;
+    start: () => Promise<boolean>;
+    getStatus: () => CheckoutStatus;
+    innerLrsRef: React.RefObject<GlomoLrsCheckoutRef>;
+    innerStandardRef: React.RefObject<GlomoStandardCheckoutRef>;
+    innerSubscriptionsRef: React.RefObject<GlomoSubscriptionsCheckoutRef>;
+    props: GlomoCheckoutProps;
+}
+/**
+ * @deprecated Legacy hook - will be removed in a future major version.
+ *
+ * This hook does not provide reactive state. `getStatus()` returns a
+ * point-in-time snapshot and does not trigger re-renders on status changes.
+ * `start()` returns a promise identical to `GlomoCheckoutRef.start()`.
+ *
+ * Use the `GlomoCheckout` component with a ref instead:
+ *
+ * ```tsx
+ * const ref = useRef<GlomoCheckoutRef>(null);
+ * const started = await ref.current?.start();
+ * const status = ref.current?.getStatus();
+ * ```
+ */
+export declare function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutReturn;
+export declare function useGlomoCheckout(props: GlomoCheckoutProps, internalOptions: {
+    _suppressDeprecationWarning: true;
+}): UseGlomoCheckoutInternalReturn;
+export {};
+//# sourceMappingURL=use-glomo-checkout.d.ts.map

package/lib/use-glomo-checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-glomo-checkout.d.ts","sourceRoot":"","sources":["../src/use-glomo-checkout.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,KAAK,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EAAE,KAAK,SAAS,EAAkB,MAAM,+BAA+B,CAAC;AAU/E,kDAAkD;AAClD,KAAK,iBAAiB,GAAG,SAAS,GAAG,eAAe,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,cAAc,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC3C,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,cAAc,CAAC;IAChC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAClD,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAC5D,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAAC,6BAA6B,CAAC,CAAC;IACtE,KAAK,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,sBAAsB,CAAC;AACpF,wBAAgB,gBAAgB,CAC5B,KAAK,EAAE,kBAAkB,EACzB,eAAe,EAAE;IAAE,2BAA2B,EAAE,IAAI,CAAA;CAAE,GACvD,8BAA8B,CAAC"}

package/lib/use-glomo-checkout.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Unified wrapper hook - detects order type (LRS vs Standard) via the order API
+ * and delegates to the appropriate inner checkout hook once resolved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGlomoCheckout = useGlomoCheckout;
+const react_1 = require("react");
+const order_type_fetcher_1 = require("./services/order-type-fetcher");
+const validation_1 = require("./utils/validation");
+const analytics_1 = require("./utils/analytics");
+function useGlomoCheckout(props, internalOptions) {
+    var _a, _b;
+    const { server, publicKey, orderId, subscriptionId, onSdkError, devMode = false } = props;
+    // Order type resolved from the API - null until detection completes
+    const [orderType, setOrderType] = (0, react_1.useState)(null);
+    // Whether order type detection is in progress
+    const [detecting, setDetecting] = (0, react_1.useState)(false);
+    // Whether the props have a mutual exclusion error
+    const [propsError, setPropsError] = (0, react_1.useState)(false);
+    // Stabilizing onSdkError ref to avoid re-running effects on inline callback changes
+    const onSdkErrorRef = (0, react_1.useRef)(onSdkError);
+    onSdkErrorRef.current = onSdkError;
+    // One-time deprecation warning for direct merchant usage
+    const suppressWarning = (_a = internalOptions === null || internalOptions === void 0 ? void 0 : internalOptions._suppressDeprecationWarning) !== null && _a !== void 0 ? _a : false;
+    const mockMode = (_b = publicKey === null || publicKey === void 0 ? void 0 : publicKey.toLowerCase().startsWith("test_")) !== null && _b !== void 0 ? _b : false;
+    const hasWarnedRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (!hasWarnedRef.current && !suppressWarning) {
+            hasWarnedRef.current = true;
+            console.warn("[Glomo-RN-SDK] useGlomoCheckout is deprecated and will be removed in a future major version. " +
+                "Use the GlomoCheckout component with a ref instead. " +
+                "This hook does not provide reactive state - getStatus() is a point-in-time snapshot, not a reactive value.");
+            (0, analytics_1.trackUseOfUnsupportedFunctionality)("useGlomoCheckout", orderId !== null && orderId !== void 0 ? orderId : subscriptionId, publicKey, devMode, mockMode, "");
+        }
+    }, [suppressWarning, orderId, subscriptionId, publicKey, devMode, mockMode]);
+    // Refs for the inner LRS, Standard, and Subscriptions checkout components
+    const innerLrsRef = (0, react_1.useRef)(null);
+    const innerStandardRef = (0, react_1.useRef)(null);
+    const innerSubscriptionsRef = (0, react_1.useRef)(null);
+    /** Mutual exclusion guard - firing onSdkError if both or neither id is provided */
+    (0, react_1.useEffect)(() => {
+        const hasBoth = Boolean(orderId) && Boolean(subscriptionId);
+        const hasNeither = !orderId && !subscriptionId;
+        if (hasBoth) {
+            setPropsError(true);
+            (0, validation_1.safeCallback)(onSdkErrorRef.current, [[{ type: "validation_error", message: "Provide either orderId or subscriptionId, not both" }]], "onSdkError", devMode);
+        }
+        else if (hasNeither) {
+            setPropsError(true);
+            (0, validation_1.safeCallback)(onSdkErrorRef.current, [[{ type: "validation_error", message: "Provide orderId or subscriptionId" }]], "onSdkError", devMode);
+        }
+        else {
+            setPropsError(false);
+        }
+    }, [orderId, subscriptionId, devMode]);
+    /**
+     * Tracking whether start() has been called and the inner component needs to be auto-started.
+     * This bridges the gap between order type resolution (async) and inner component mount (next render).
+     */
+    const pendingStartRef = (0, react_1.useRef)(false);
+    /**
+     * Generation counter for stale fetch detection.
+     * Incremented on every start() call and on orderId/publicKey changes. After fetchOrderType
+     * resolves, the result is discarded if the generation has moved on (props changed mid-flight).
+     */
+    const fetchGenerationRef = (0, react_1.useRef)(0);
+    /**
+     * Holds the resolve function for the pending start() promise.
+     * This allows the useEffect that auto-starts the inner component to resolve the merchant's
+     * awaited promise with the actual result of the inner start().
+     */
+    const pendingStartResolveRef = (0, react_1.useRef)(null);
+    // Deriving the unified checkout status from the inner component's status
+    const getStatus = (0, react_1.useCallback)(() => {
+        if (detecting) {
+            return "detecting_order_type";
+        }
+        // Delegating to the inner component's getStatus() once order type is resolved
+        if (orderType === "lrs" && innerLrsRef.current) {
+            return innerLrsRef.current.getStatus();
+        }
+        if (orderType === "standard" && innerStandardRef.current) {
+            return innerStandardRef.current.getStatus();
+        }
+        if (orderType === "subscriptions" && innerSubscriptionsRef.current) {
+            return innerSubscriptionsRef.current.getStatus();
+        }
+        return "ready";
+    }, [detecting, orderType]);
+    /**
+     * Initiator for the unified checkout flow.
+     * Validates inputs, calls the order type detection API, and marks the inner component for auto-start.
+     */
+    const start = (0, react_1.useCallback)(async () => {
+        // If a previous start() call is still pending, resolve it as false before proceeding
+        if (pendingStartResolveRef.current) {
+            pendingStartResolveRef.current(false);
+            pendingStartResolveRef.current = null;
+        }
+        if (devMode) {
+            console.log("[Glomo-RN-SDK] start() called");
+        }
+        // Aborting if mutual exclusion guard detected a props error
+        if (propsError) {
+            if (devMode) {
+                console.error("[Glomo-RN-SDK] start() aborted: invalid orderId/subscriptionId combination");
+            }
+            return false;
+        }
+        // Validating inputs before making the API call
+        const errors = [];
+        if (!(0, validation_1.isValidPublicKey)(publicKey)) {
+            errors.push({
+                type: "validation_error",
+                message: "Invalid publicKey: must start with 'live_', 'mock_', or 'test_' and be a valid string",
+                field: "publicKey",
+            });
+        }
+        /**
+         * For subscriptions flow, skipping orderId validation entirely - GlomoSubscriptionsCheckout
+         * owns subscriptionId validation (trim, empty, prefix). For order flow, validating orderId.
+         */
+        if (!subscriptionId && !(0, validation_1.isValidOrderId)(orderId)) {
+            errors.push({
+                type: "validation_error",
+                message: "Invalid orderId: must start with 'order_' and be a valid string",
+                field: "orderId",
+            });
+        }
+        // Reporting validation errors and aborting if any
+        if (errors.length > 0) {
+            if (devMode) {
+                console.error("[Glomo-RN-SDK] Validation failed.");
+            }
+            (0, validation_1.safeCallback)(onSdkError, [errors], "onSdkError", devMode);
+            return false;
+        }
+        /**
+         * For subscriptions, orderType is already "subscriptions" and the inner component is mounted.
+         * Calling start() directly - no promise/effect bridge needed since no async detection occurs.
+         */
+        if (subscriptionId) {
+            if (innerSubscriptionsRef.current) {
+                const started = innerSubscriptionsRef.current.start();
+                if (devMode) {
+                    console.log(`[Glomo-RN-SDK] Subscriptions inner start() returned: ${started}`);
+                }
+                return started;
+            }
+            if (devMode) {
+                console.error("[Glomo-RN-SDK] Subscriptions component not mounted");
+            }
+            return false;
+        }
+        // Detecting order type via the API
+        setDetecting(true);
+        const thisGeneration = ++fetchGenerationRef.current;
+        if (devMode) {
+            console.log("[Glomo-RN-SDK] Detecting order type...");
+        }
+        (0, analytics_1.trackOrderTypeDetectionStarted)(orderId, publicKey, devMode);
+        const result = await (0, order_type_fetcher_1.fetchOrderType)({ orderId: orderId, publicKey, server, devMode });
+        // Discarding stale result if props changed while the fetch was in flight
+        if (thisGeneration !== fetchGenerationRef.current) {
+            if (devMode) {
+                console.log("[Glomo-RN-SDK] Discarding stale order type result (props changed mid-flight)");
+            }
+            return false;
+        }
+        setDetecting(false);
+        // Handling detection failure
+        if (!result.success) {
+            if (devMode) {
+                console.error(`[Glomo-RN-SDK] Order type detection failed: ${result.error}`);
+            }
+            (0, analytics_1.trackOrderTypeDetectionFailed)(orderId, publicKey, result.error, devMode);
+            (0, validation_1.safeCallback)(onSdkError, [[{ type: "validation_error", message: result.error }]], "onSdkError", devMode);
+            return false;
+        }
+        if (devMode) {
+            console.log(`[Glomo-RN-SDK] Order type resolved: ${result.orderType}`);
+        }
+        (0, analytics_1.trackOrderTypeDetectionResolved)(orderId, publicKey, result.orderType, devMode);
+        // Setting the resolved order type - this triggers a re-render that mounts the inner component
+        setOrderType(result.orderType);
+        // Returning a promise that resolves only when the inner component's start() completes
+        return new Promise((resolve) => {
+            pendingStartResolveRef.current = resolve;
+            pendingStartRef.current = true;
+        });
+    }, [devMode, publicKey, orderId, subscriptionId, server, onSdkError, propsError]);
+    /**
+     * Auto-starting the inner component after order type is resolved and the component has rendered.
+     * The pendingStartRef bridges the async gap: start() sets it, and this effect fires after
+     * the inner component mounts in the next render cycle.
+     */
+    (0, react_1.useEffect)(() => {
+        if (!pendingStartRef.current || !orderType) {
+            return;
+        }
+        // Forwarding start() to the appropriate inner component
+        let started = false;
+        if (orderType === "lrs" && innerLrsRef.current) {
+            pendingStartRef.current = false;
+            started = innerLrsRef.current.start();
+            if (devMode) {
+                console.log(`[Glomo-RN-SDK] LRS inner start() returned: ${started}`);
+            }
+        }
+        else if (orderType === "standard" && innerStandardRef.current) {
+            pendingStartRef.current = false;
+            started = innerStandardRef.current.start();
+            if (devMode) {
+                console.log(`[Glomo-RN-SDK] Standard inner start() returned: ${started}`);
+            }
+        }
+        else if (orderType === "subscriptions") {
+            // No-op: subscription start() calls the inner component directly (not via this effect bridge).
+            // If we reach here, pendingStartRef was set unexpectedly - resolve false defensively.
+            pendingStartRef.current = false;
+        }
+        // Resolving the merchant's awaited start() promise with the inner component's result
+        if (pendingStartResolveRef.current) {
+            pendingStartResolveRef.current(started);
+            pendingStartResolveRef.current = null;
+        }
+    }, [orderType, devMode]);
+    /**
+     * Resetting order type state when orderId, subscriptionId, or publicKey changes.
+     * For subscriptions, setting orderType to "subscriptions" directly (no API call needed).
+     * For orders, resetting to null to force re-detection on next start().
+     * Single effect owns all orderType transitions to avoid race conditions.
+     */
+    (0, react_1.useEffect)(() => {
+        // Invalidating any in-flight fetchOrderType call so its stale result is discarded
+        fetchGenerationRef.current++;
+        if (pendingStartResolveRef.current) {
+            pendingStartResolveRef.current(false);
+            pendingStartResolveRef.current = null;
+        }
+        setDetecting(false);
+        pendingStartRef.current = false;
+        if (subscriptionId && !orderId) {
+            setOrderType("subscriptions");
+        }
+        else {
+            setOrderType(null);
+        }
+    }, [orderId, subscriptionId, publicKey]);
+    return {
+        orderType,
+        detecting,
+        start,
+        getStatus,
+        innerLrsRef,
+        innerStandardRef,
+        innerSubscriptionsRef,
+        props,
+    };
+}

package/lib/use-lrs-checkout.d.ts

@@ -1,11 +1,16 @@
 /** Main SDK hook for the GlomoPay LRS Checkout flow */
 import React from "react";
 import { type NativeSyntheticEvent } from "react-native";
-import { WebViewNavigation, WebViewMessageEvent, type WebView } from "react-native-webview";
-import { type GlomoLrsServer } from "./config/base";
+import { type WebViewNavigation, type WebViewMessageEvent, type WebView } from "react-native-webview";
+import { type GlomoServer } from "./config/base";
 import { type SdkError } from "./utils/analytics";
 /** LRS checkout statuses */
-export type LrsCheckoutStatus = "ready" | "payment_in_progress" | "payment_successful" | "payment_failed" | "payment_cancelled";
+export type LrsCheckoutStatus = "ready" | "payment_in_progress" | "payment_successful" | "payment_failed" | "payment_cancelled"
+/**
+ * These are not currently emitted by LRS flows, but I'm intentionally including them so that the SDK is forwards compatible.
+ * The SDK would also then effectively handle these events without a patch if LRS gains bank transfer / pay-via-bank support in the future.
+ */
+ | "bank_transfer_submitted" | "pay_via_bank_completed";
 /**
  * Tracks whether the education carousel WebView has signalled that it has content to show.
  * - "pending": waiting for the carousel to report its state (default/reset value)
@@ -20,7 +25,7 @@ export interface GlomoLrsCheckoutPayload {
 }
 /** The options for the useLrsCheckout hook */
 export interface UseLrsCheckoutOptions {
-    server?: GlomoLrsServer;
+    server?: GlomoServer;
     publicKey: string;
     orderId: string;
     onPaymentSuccess: (payload: GlomoLrsCheckoutPayload) => void;

package/lib/use-lrs-checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-lrs-checkout.d.ts","sourceRoot":"","sources":["../src/use-lrs-checkout.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-lrs-checkout.d.ts","sourceRoot":"","sources":["../src/use-lrs-checkout.tsx"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,EAAY,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAItG,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAGtE,OAAO,EAcH,KAAK,QAAQ,EAChB,MAAM,mBAAmB,CAAC;AAE3B,4BAA4B;AAC5B,MAAM,MAAM,iBAAiB,GAEvB,OAAO,GAGP,qBAAqB,GAGrB,oBAAoB,GAGpB,gBAAgB,GAGhB,mBAAmB;AAErB;;;GAGG;GACD,yBAAyB,GACzB,wBAAwB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,YAAY,CAAC;AAE9D,qDAAqD;AACrD,MAAM,WAAW,uBAAuB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC7D,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC7D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACjC,KAAK,EAAE,MAAM,OAAO,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sBAAsB,EAAE,sBAAsB,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzC,cAAc,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzC,2BAA2B,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACtD,wBAAwB,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC/D,wBAAwB,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC/D,qCAAqC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC5E,WAAW,EAAE,CACT,cAAc,EAAE,oBAAoB,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,KAC7F,IAAI,CAAC;IACV,eAAe,EAAE,CAAC,cAAc,EAAE,oBAAoB,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;IAC9G,2BAA2B,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnE,qBAAqB,EAAE,MAAM,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAC1B,EACI,MAAM,EACN,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,OAAe,GAClB,EAAE,qBAAqB,EACxB,QAAQ,EAAE,OAAO,GAClB,oBAAoB,CA02BtB"}