@glomopay/react-native-sdk 2.0.2 → 3.1.0

package/src/use-glomo-checkout.tsx

@@ -0,0 +1,369 @@
+/**
+ * Unified wrapper hook - detects order type (LRS vs Standard) via the order API
+ * and delegates to the appropriate inner checkout hook once resolved.
+ */
+
+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 {
+    type SdkError,
+    trackOrderTypeDetectionStarted,
+    trackOrderTypeDetectionResolved,
+    trackOrderTypeDetectionFailed,
+    trackUseOfUnsupportedFunctionality,
+} from "./utils/analytics";
+
+/** 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 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<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);
+
+    // 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.
+     * This bridges the gap between order type resolution (async) and inner component mount (next render).
+     */
+    const pendingStartRef = 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 = 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 = useRef<((value: boolean) => void) | null>(null);
+
+    // Deriving the unified checkout status from the inner component's status
+    const getStatus = useCallback((): CheckoutStatus => {
+        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 = useCallback(async (): Promise<boolean> => {
+        // 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: SdkError[] = [];
+
+        if (!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 && !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.");
+            }
+            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...");
+        }
+
+        trackOrderTypeDetectionStarted(orderId!, publicKey, 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) {
+            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}`);
+            }
+            trackOrderTypeDetectionFailed(orderId!, publicKey, result.error, devMode);
+            safeCallback(onSdkError, [[{ type: "validation_error", message: result.error }]], "onSdkError", devMode);
+            return false;
+        }
+
+        if (devMode) {
+            console.log(`[Glomo-RN-SDK] Order type resolved: ${result.orderType}`);
+        }
+
+        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<boolean>((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.
+     */
+    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.
+     */
+    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,
+    };
+}