@glomopay/react-native-sdk 3.0.1 → 3.1.0

package/src/glomo-standard-checkout.tsx

@@ -6,8 +6,19 @@ import { WebView, type WebViewMessageEvent, type WebViewProps } from "react-nati
 
 import { useStandardCheckout } from "./use-standard-checkout";
 import { type GlomoStandardCheckoutRef, type GlomoStandardCheckoutProps } from "./types/standard-checkout";
+import { type CheckoutAnalyticsTrackers } from "./utils/analytics";
 import { isValidUrl } from "./utils/validation";
 
+/**
+ * Internal-only props for GlomoStandardCheckout.
+ * Used by GlomoSubscriptionsCheckout to inject subscription analytics trackers.
+ * Not exported to merchants via index.ts.
+ */
+export interface GlomoStandardCheckoutInternalProps extends GlomoStandardCheckoutProps {
+    _analyticsTrackers?: CheckoutAnalyticsTrackers;
+    _skipOrderIdValidation?: boolean;
+}
+
 /**
  * The Main GlomoPay Standard Checkout Component
  *
@@ -40,7 +51,9 @@ function GlomoStandardCheckoutComponent(
         onPayViaBankBankConnectionSuccessful,
         onUserRefusedCameraPermissions,
         devMode = false,
-    }: GlomoStandardCheckoutProps,
+        _analyticsTrackers,
+        _skipOrderIdValidation,
+    }: GlomoStandardCheckoutInternalProps,
     ref: React.ForwardedRef<GlomoStandardCheckoutRef>
 ) {
     // Computing mockMode based on the publicKey prefix
@@ -89,7 +102,8 @@ function GlomoStandardCheckoutComponent(
             onUserRefusedCameraPermissions,
             devMode,
         },
-        mockMode
+        mockMode,
+        { analyticsTrackers: _analyticsTrackers, _skipOrderIdValidation }
     );
 
     // Exposing the start() and getStatus() methods via the ref
@@ -262,11 +276,26 @@ function GlomoStandardCheckoutComponent(
     );
 }
 
-export const GlomoStandardCheckout = forwardRef<GlomoStandardCheckoutRef, GlomoStandardCheckoutProps>(
+/**
+ * Widening the internal type to GlomoStandardCheckoutInternalProps for internal SDK use,
+ * then narrowing the public export to GlomoStandardCheckoutProps so merchants cannot
+ * pass internal-only props like _analyticsTrackers.
+ */
+export const GlomoStandardCheckout = forwardRef(GlomoStandardCheckoutComponent) as React.ForwardRefExoticComponent<
+    GlomoStandardCheckoutProps & React.RefAttributes<GlomoStandardCheckoutRef>
+>;
+
+GlomoStandardCheckout.displayName = "GlomoStandardCheckout";
+
+/**
+ * Internal reference - accepts GlomoStandardCheckoutInternalProps.
+ * Not re-exported from index.ts.
+ */
+export const GlomoStandardCheckoutInternal = forwardRef<GlomoStandardCheckoutRef, GlomoStandardCheckoutInternalProps>(
     GlomoStandardCheckoutComponent
 );
 
-GlomoStandardCheckout.displayName = "GlomoStandardCheckout";
+GlomoStandardCheckoutInternal.displayName = "GlomoStandardCheckoutInternal";
 
 const styles = StyleSheet.create({
     modalContainer: {

package/src/glomo-subscriptions-checkout.tsx

@@ -0,0 +1,83 @@
+/**
+ * GlomoSubscriptionsCheckout - thin wrapper around GlomoStandardCheckout
+ * that accepts a subscriptionId (sub_*) instead of an orderId (order_*).
+ */
+
+import React, { useRef, useImperativeHandle, forwardRef, useEffect } from "react";
+
+import { GlomoStandardCheckoutInternal } from "./glomo-standard-checkout";
+import { type GlomoStandardCheckoutRef } from "./types/standard-checkout";
+import {
+    type GlomoSubscriptionsCheckoutProps,
+    type GlomoSubscriptionsCheckoutRef,
+} from "./types/subscriptions-checkout";
+import { subscriptionCheckoutTrackers } from "./utils/analytics";
+import { safeCallback } from "./utils/validation";
+
+function GlomoSubscriptionsCheckoutComponent(
+    props: GlomoSubscriptionsCheckoutProps,
+    ref: React.ForwardedRef<GlomoSubscriptionsCheckoutRef>
+) {
+    const { subscriptionId: rawSubscriptionId, onSdkError, devMode = false, ...rest } = props;
+    const innerRef = useRef<GlomoStandardCheckoutRef>(null);
+    const onSdkErrorRef = useRef(onSdkError);
+    onSdkErrorRef.current = onSdkError;
+
+    const subscriptionId = rawSubscriptionId.trim();
+
+    /** Validating subscriptionId - firing onSdkError via useEffect to avoid side effects during render */
+    const validationError = (() => {
+        if (subscriptionId.length === 0) {
+            return "subscriptionId must not be empty";
+        }
+        if (!subscriptionId.startsWith("sub_")) {
+            return "subscriptionId must start with 'sub_'";
+        }
+        return null;
+    })();
+
+    useEffect(() => {
+        if (validationError) {
+            safeCallback(
+                onSdkErrorRef.current,
+                [[{ type: "validation_error", message: validationError }]],
+                "onSdkError",
+                devMode
+            );
+        }
+    }, [validationError, devMode]);
+
+    useImperativeHandle(ref, () => ({
+        start: () => {
+            if (validationError) {
+                return false;
+            }
+            return innerRef.current?.start() ?? false;
+        },
+        getStatus: () => {
+            return innerRef.current?.getStatus() ?? "ready";
+        },
+    }));
+
+    if (validationError) {
+        return null;
+    }
+
+    return (
+        <GlomoStandardCheckoutInternal
+            ref={innerRef}
+            {...rest}
+            orderId={subscriptionId}
+            onSdkError={onSdkError}
+            devMode={devMode}
+            _analyticsTrackers={subscriptionCheckoutTrackers}
+            _skipOrderIdValidation={true}
+        />
+    );
+}
+
+export const GlomoSubscriptionsCheckout = forwardRef<GlomoSubscriptionsCheckoutRef, GlomoSubscriptionsCheckoutProps>(
+    GlomoSubscriptionsCheckoutComponent
+);
+
+GlomoSubscriptionsCheckout.displayName = "GlomoSubscriptionsCheckout";

package/src/index.ts

@@ -12,4 +12,4 @@ export {
 } from "./types/checkout";
 export { type GlomoServer } from "./config/base";
 export { type SdkError } from "./utils/analytics";
-export { useGlomoCheckout } from "./use-glomo-checkout";
+export { useGlomoCheckout, type UseGlomoCheckoutReturn } from "./use-glomo-checkout";

package/src/types/checkout.ts

@@ -47,11 +47,10 @@ export interface GlomoCheckoutRef {
     getStatus: () => CheckoutStatus;
 }
 
-/** Props for the unified checkout component */
-export interface GlomoCheckoutProps {
+/** Shared callback and configuration props for the unified checkout component */
+interface GlomoCheckoutBaseProps {
     server?: GlomoServer;
     publicKey: string;
-    orderId: string;
     onPaymentSuccess: (payload: GlomoCheckoutPayload) => void;
     onPaymentFailure: (payload: GlomoCheckoutPayload) => void;
     onConnectionError?: (error: unknown) => void;
@@ -63,3 +62,11 @@ export interface GlomoCheckoutProps {
     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 });

package/src/types/subscriptions-checkout.ts

@@ -0,0 +1,31 @@
+/** 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;
+}

package/src/use-glomo-checkout.tsx

@@ -8,6 +8,7 @@ import { useState, useRef, useCallback, useEffect } from "react";
 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, fetchOrderType } from "./services/order-type-fetcher";
 import { isValidPublicKey, isValidOrderId, safeCallback } from "./utils/validation";
 import {
@@ -15,34 +16,126 @@ import {
     trackOrderTypeDetectionStarted,
     trackOrderTypeDetectionResolved,
     trackOrderTypeDetectionFailed,
+    trackUseOfUnsupportedFunctionality,
 } from "./utils/analytics";
 
-/** The return values for the useGlomoCheckout hook */
+/** 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 {
-    orderType: OrderType | null;
+    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;
 }
 
 /**
- * The main unified checkout hook.
- * Validates inputs, detects order type via API, then auto-starts the resolved inner component.
+ * @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 function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutReturn {
-    const { server, publicKey, orderId, onSdkError, devMode = false } = props;
+export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutReturn;
+export function useGlomoCheckout(
+    props: GlomoCheckoutProps,
+    internalOptions: { _suppressDeprecationWarning: true }
+): UseGlomoCheckoutInternalReturn;
+export function useGlomoCheckout(
+    props: GlomoCheckoutProps,
+    internalOptions?: { _suppressDeprecationWarning?: boolean }
+): UseGlomoCheckoutInternalReturn {
+    const { server, publicKey, orderId, subscriptionId, onSdkError, devMode = false } = props;
 
     // Order type resolved from the API - null until detection completes
-    const [orderType, setOrderType] = useState<OrderType | null>(null);
+    const [orderType, setOrderType] = useState<ExtendedOrderType | null>(null);
     // Whether order type detection is in progress
     const [detecting, setDetecting] = useState(false);
+    // Whether the props have a mutual exclusion error
+    const [propsError, setPropsError] = useState(false);
 
-    // Refs for the inner LRS and Standard checkout components
+    // Stabilizing onSdkError ref to avoid re-running effects on inline callback changes
+    const onSdkErrorRef = useRef(onSdkError);
+    onSdkErrorRef.current = onSdkError;
+
+    // One-time deprecation warning for direct merchant usage
+    const suppressWarning = internalOptions?._suppressDeprecationWarning ?? false;
+    const mockMode = publicKey?.toLowerCase().startsWith("test_") ?? false;
+    const hasWarnedRef = useRef(false);
+    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."
+            );
+            trackUseOfUnsupportedFunctionality(
+                "useGlomoCheckout",
+                orderId ?? subscriptionId,
+                publicKey,
+                devMode,
+                mockMode,
+                ""
+            );
+        }
+    }, [suppressWarning, orderId, subscriptionId, publicKey, devMode, mockMode]);
+
+    // Refs for the inner LRS, Standard, and Subscriptions checkout components
     const innerLrsRef = useRef<GlomoLrsCheckoutRef>(null);
     const innerStandardRef = useRef<GlomoStandardCheckoutRef>(null);
+    const innerSubscriptionsRef = useRef<GlomoSubscriptionsCheckoutRef>(null);
+
+    /** Mutual exclusion guard - firing onSdkError if both or neither id is provided */
+    useEffect(() => {
+        const hasBoth = Boolean(orderId) && Boolean(subscriptionId);
+        const hasNeither = !orderId && !subscriptionId;
+
+        if (hasBoth) {
+            setPropsError(true);
+            safeCallback(
+                onSdkErrorRef.current,
+                [[{ type: "validation_error", message: "Provide either orderId or subscriptionId, not both" }]],
+                "onSdkError",
+                devMode
+            );
+        } else if (hasNeither) {
+            setPropsError(true);
+            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.
@@ -76,6 +169,9 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
         if (orderType === "standard" && innerStandardRef.current) {
             return innerStandardRef.current.getStatus();
         }
+        if (orderType === "subscriptions" && innerSubscriptionsRef.current) {
+            return innerSubscriptionsRef.current.getStatus();
+        }
         return "ready";
     }, [detecting, orderType]);
 
@@ -94,6 +190,14 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             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: SdkError[] = [];
 
@@ -105,7 +209,11 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             });
         }
 
-        if (!isValidOrderId(orderId)) {
+        /**
+         * For subscriptions flow, skipping orderId validation entirely - GlomoSubscriptionsCheckout
+         * owns subscriptionId validation (trim, empty, prefix). For order flow, validating orderId.
+         */
+        if (!subscriptionId && !isValidOrderId(orderId!)) {
             errors.push({
                 type: "validation_error",
                 message: "Invalid orderId: must start with 'order_' and be a valid string",
@@ -122,6 +230,24 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             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;
@@ -130,9 +256,9 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             console.log("[Glomo-RN-SDK] Detecting order type...");
         }
 
-        trackOrderTypeDetectionStarted(orderId, publicKey, devMode);
+        trackOrderTypeDetectionStarted(orderId!, publicKey, devMode);
 
-        const result = await fetchOrderType({ orderId, publicKey, server, devMode });
+        const result = await fetchOrderType({ orderId: orderId!, publicKey, server, devMode });
 
         // Discarding stale result if props changed while the fetch was in flight
         if (thisGeneration !== fetchGenerationRef.current) {
@@ -149,7 +275,7 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             if (devMode) {
                 console.error(`[Glomo-RN-SDK] Order type detection failed: ${result.error}`);
             }
-            trackOrderTypeDetectionFailed(orderId, publicKey, result.error, devMode);
+            trackOrderTypeDetectionFailed(orderId!, publicKey, result.error, devMode);
             safeCallback(onSdkError, [[{ type: "validation_error", message: result.error }]], "onSdkError", devMode);
             return false;
         }
@@ -158,7 +284,7 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             console.log(`[Glomo-RN-SDK] Order type resolved: ${result.orderType}`);
         }
 
-        trackOrderTypeDetectionResolved(orderId, publicKey, result.orderType, devMode);
+        trackOrderTypeDetectionResolved(orderId!, publicKey, result.orderType, devMode);
 
         // Setting the resolved order type - this triggers a re-render that mounts the inner component
         setOrderType(result.orderType);
@@ -168,7 +294,7 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             pendingStartResolveRef.current = resolve;
             pendingStartRef.current = true;
         });
-    }, [devMode, publicKey, orderId, server, onSdkError]);
+    }, [devMode, publicKey, orderId, subscriptionId, server, onSdkError, propsError]);
 
     /**
      * Auto-starting the inner component after order type is resolved and the component has rendered.
@@ -194,6 +320,10 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             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
@@ -203,7 +333,12 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
         }
     }, [orderType, devMode]);
 
-    // Resetting order type state when orderId or publicKey changes to force re-detection
+    /**
+     * 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.
+     */
     useEffect(() => {
         // Invalidating any in-flight fetchOrderType call so its stale result is discarded
         fetchGenerationRef.current++;
@@ -211,10 +346,15 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
             pendingStartResolveRef.current(false);
             pendingStartResolveRef.current = null;
         }
-        setOrderType(null);
         setDetecting(false);
         pendingStartRef.current = false;
-    }, [orderId, publicKey]);
+
+        if (subscriptionId && !orderId) {
+            setOrderType("subscriptions");
+        } else {
+            setOrderType(null);
+        }
+    }, [orderId, subscriptionId, publicKey]);
 
     return {
         orderType,
@@ -223,6 +363,7 @@ export function useGlomoCheckout(props: GlomoCheckoutProps): UseGlomoCheckoutRet
         getStatus,
         innerLrsRef,
         innerStandardRef,
+        innerSubscriptionsRef,
         props,
     };
 }