@glomopay/react-native-sdk 2.0.2 → 3.1.0

package/src/utils/analytics.ts

@@ -10,8 +10,14 @@
  * Analytics failures never break the SDK.
  */
 
+import { Platform } from "react-native";
 import { getSegmentClient, isSegmentAvailable, getAnonymousId, getSegmentWriteKey } from "../config/segment";
 
+/**
+ * Flow type for checkout
+ */
+export type FlowType = "lrs" | "standard" | "unified" | "subscriptions";
+
 /**
  * Common properties that should be included with every event
  */
@@ -21,7 +27,11 @@ export interface CommonEventProperties {
     mockMode?: boolean;
     orderId?: string;
     publicKey?: string;
-    lrsUrl?: string;
+    checkoutUrl?: string;
+    platform: "react-native";
+    deviceOS: "ios" | "android" | string;
+    deviceOSVersion: string;
+    flowType?: FlowType;
     timestamp?: string;
     [key: string]: unknown;
 }
@@ -30,7 +40,7 @@ export interface CommonEventProperties {
 export interface SdkError {
     type: "validation_error" | "device_forbidden";
     message: string;
-    field?: "publicKey" | "orderId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
+    field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
 }
 
 /**
@@ -42,7 +52,6 @@ export interface SdkError {
 function getSdkVersion(): string {
     try {
         // Using require to dynamically import package.json
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
         const packageJson = require("../../package.json");
         return packageJson.version || "unknown";
     } catch {
@@ -58,7 +67,8 @@ function getSdkVersion(): string {
  * @param publicKey - The public key of the merchant
  * @param devMode - Whether dev mode is enabled
  * @param mockMode - Whether mock mode is enabled
- * @param lrsUrl - The LRS checkout URL
+ * @param checkoutUrl - The checkout URL
+ * @param flowType - The flow type
  * @returns Common properties object
  */
 function buildCommonProperties(
@@ -66,16 +76,21 @@ function buildCommonProperties(
     publicKey?: string,
     devMode: boolean = false,
     mockMode: boolean = false,
-    lrsUrl?: string
+    checkoutUrl?: string,
+    flowType?: FlowType
 ): CommonEventProperties {
     return {
         orderId,
         publicKey,
-        lrsUrl,
+        checkoutUrl,
         devMode,
         mockMode,
+        platform: "react-native",
+        deviceOS: Platform.OS,
+        deviceOSVersion: String(Platform.Version),
         sdkVersion: getSdkVersion(),
         timestamp: new Date().toISOString(),
+        ...(flowType && { flowType }),
     };
 }
 
@@ -97,7 +112,7 @@ async function trackEvent(
     // Returning early if GlomoPay Segment is not available
     if (!isSegmentAvailable()) {
         if (devMode) {
-            console.log(`[GlomoPay RN SDK] Segment not available. Event "${eventName}" not tracked.`, properties);
+            console.log(`[Glomo-RN-SDK] Segment not available. Event "${eventName}" not tracked.`, properties);
         }
         return;
     }
@@ -109,7 +124,7 @@ async function trackEvent(
         // Double-checking if the client exists (TypeScript safety)
         if (!client || !anonymousId) {
             if (devMode) {
-                console.log(`[GlomoPay RN SDK] Segment client is null. Event "${eventName}" not tracked.`);
+                console.log(`[Glomo-RN-SDK] Segment client is null. Event "${eventName}" not tracked.`);
             }
             return;
         }
@@ -139,12 +154,12 @@ async function trackEvent(
         await client.post("/track", payload);
 
         if (devMode) {
-            console.log(`[GlomoPay RN SDK] Tracked event: ${eventName}`, eventProperties);
+            console.log(`[Glomo-RN-SDK] Tracked event: ${eventName}`, eventProperties);
         }
     } catch (error) {
         if (devMode) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            console.error(`[GlomoPay RN SDK] Error tracking event ${eventName}:`, errorMessage);
+            console.error(`[Glomo-RN-SDK] Error tracking event ${eventName}:`, errorMessage);
         }
         // Silently failing - GlomoPay analytics should never break the SDK
     }
@@ -181,7 +196,7 @@ export function trackStartSuccess(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Started", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on start() success:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on start() success:`, error);
         }
     });
 }
@@ -220,7 +235,7 @@ export function trackStartAttempt(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Start Attempted", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on start() attempt:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on start() attempt:`, error);
         }
     });
 }
@@ -259,7 +274,7 @@ export function trackStartFailure(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Start Failed", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on start() failure:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on start() failure:`, error);
         }
     });
 }
@@ -292,7 +307,7 @@ export function trackWindowOpen(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Window Open", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on window.open:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on window.open:`, error);
         }
     });
 }
@@ -322,7 +337,7 @@ export function trackWindowClose(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Window Close", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on window.close:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on window.close:`, error);
         }
     });
 }
@@ -377,7 +392,7 @@ export function trackInvalidMessageReceived(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Invalid Message Received", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error for invalid message received event:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error for invalid message received event:`, error);
         }
     });
 }
@@ -407,7 +422,7 @@ export function trackPaymentSuccess(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Success", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on payment success callback:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on payment success callback:`, error);
         }
     });
 }
@@ -437,7 +452,7 @@ export function trackPaymentFailure(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Failure", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on payment failure callback:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on payment failure callback:`, error);
         }
     });
 }
@@ -467,7 +482,7 @@ export function trackPaymentTerminate(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Terminated", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on payment terminate callback:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on payment terminate callback:`, error);
         }
     });
 }
@@ -497,7 +512,7 @@ export function trackConnectionError(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Connection Error", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on connection error callback:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on connection error callback:`, error);
         }
     });
 }
@@ -526,7 +541,36 @@ export function trackEducationStepsShown(
     };
     trackEvent("LRS Has Education Steps", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on education steps shown event:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on education steps shown event:`, error);
+        }
+    });
+}
+
+/**
+ * Tracks when the education carousel URL is invalid and the carousel cannot be shown
+ *
+ * @param orderId - The order ID
+ * @param publicKey - The public key of the merchant
+ * @param devMode - Whether dev mode is enabled
+ * @param mockMode - Whether mock mode is enabled
+ * @param lrsUrl - The LRS checkout URL
+ * @param reason - Why the carousel failed to show
+ */
+export function trackEducationStepsFailedToShow(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    lrsUrl?: string,
+    reason?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
+        ...(reason && { reason }),
+    };
+    trackEvent("LRS Education Steps Failed To Show", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error(`[Glomo-RN-SDK] Event tracking error on education steps failed to show event:`, error);
         }
     });
 }
@@ -557,28 +601,858 @@ export function trackSdkError(
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS SDK Error", properties, devMode).catch((error) => {
         if (devMode) {
-            console.error(`[GlomoPay RN SDK] Event tracking error on SDK error callback:`, error);
+            console.error(`[Glomo-RN-SDK] Event tracking error on SDK error callback:`, error);
         }
     });
 }
 
+// ---------------------------------------------------------------------------
+// Standard Checkout Trackers
+// ---------------------------------------------------------------------------
+
 /**
- * Helper to check if analytics is enabled and log accordingly
- * To be used for debugging merchant integration issues
- *
- * @param devMode - Console logs will be enabled for dev mode
- * @returns true if GlomoPay Segment is available, false otherwise
+ * Tracks when the standard checkout start() method has been called successfully
  */
-export function checkAnalyticsStatus(devMode: boolean = false): boolean {
-    const available = isSegmentAvailable();
+export function trackStandardStartSuccess(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Standard Checkout Started", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard start:", error);
+        }
+    });
+}
 
-    if (devMode) {
-        if (available) {
-            console.log("[GlomoPay RN SDK] Analytics: ENABLED");
+/**
+ * Tracks when the standard checkout start() method is called (attempted)
+ */
+export function trackStandardStartAttempt(
+    status: string,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        status,
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Standard Checkout Start Attempted", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard start attempt:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when the standard checkout start() method fails
+ */
+export function trackStandardStartFailure(
+    reason: "device_forbidden" | "validation_error" | "payment_successful" | "invalid_status" | "invalid_url",
+    orderId?: string,
+    publicKey?: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        failureReason: reason,
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Standard Checkout Start Failed", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard start failure:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when window.open is intercepted from the standard checkout WebView
+ */
+export function trackStandardWindowOpen(
+    source: "main" | "flow",
+    url: string,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        source,
+        url,
+    };
+    trackEvent("Standard Checkout Window Open", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard window open:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when window.close is intercepted from the standard checkout WebView
+ */
+export function trackStandardWindowClose(
+    source: "main" | "flow",
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        source,
+    };
+    trackEvent("Standard Checkout Window Close", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard window close:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when invalid message data is received from a standard checkout WebView
+ */
+export function trackStandardInvalidMessageReceived(
+    webviewType: "main" | "flow",
+    data: unknown,
+    url: string | undefined,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    let dataString: string;
+    try {
+        if (data === null) {
+            dataString = "null";
+        } else if (data === undefined) {
+            dataString = "undefined";
+        } else if (typeof data === "string") {
+            dataString = data;
+        } else if (typeof data === "object") {
+            dataString = JSON.stringify(data);
         } else {
-            console.log("[GlomoPay RN SDK] Analytics: DISABLED");
+            dataString = String(data);
         }
+    } catch {
+        dataString = "[unable to stringify]";
     }
 
-    return available;
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        webviewType,
+        data: dataString,
+        dataType: data === null ? "null" : typeof data,
+        ...(url && { url }),
+    };
+    trackEvent("Standard Checkout Invalid Message Received", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard invalid message:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when standard checkout onPaymentSuccess callback is invoked
+ */
+export function trackStandardPaymentSuccess(
+    orderId: string,
+    paymentId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        paymentId,
+    };
+    trackEvent("Standard Payment Success", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard payment success:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when standard checkout onPaymentFailure callback is invoked
+ */
+export function trackStandardPaymentFailure(
+    orderId: string,
+    paymentId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        paymentId,
+    };
+    trackEvent("Standard Payment Failure", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard payment failure:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when standard checkout onPaymentTerminate callback is invoked
+ */
+export function trackStandardPaymentTerminate(
+    orderId: string,
+    source: "user_dismiss" | "back_button" | "checkout_closed",
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        terminationSource: source,
+    };
+    trackEvent("Standard Payment Terminated", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard payment terminate:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when standard checkout onConnectionError callback is invoked
+ */
+export function trackStandardConnectionError(
+    orderId: string,
+    errorCode: number | undefined,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        ...(errorCode !== undefined && { errorCode }),
+    };
+    trackEvent("Standard Connection Error", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard connection error:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when standard checkout onSdkError callback is invoked
+ */
+export function trackStandardSdkError(
+    errors: Array<SdkError>,
+    orderId?: string,
+    publicKey?: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        errors,
+        errorCount: errors.length,
+    };
+    trackEvent("Standard SDK Error", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard SDK error:", error);
+        }
+    });
 }
+
+export function trackStandardBankTransferSubmitted(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+    };
+    trackEvent("Standard Bank Transfer Submitted", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard bank transfer submitted:", error);
+        }
+    });
+}
+
+export function trackStandardPayViaBankCompleted(
+    orderId: string,
+    publicKey: string,
+    status: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        payViaBankStatus: status,
+    };
+    trackEvent("Standard Pay Via Bank Completed", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard pay via bank completed:", error);
+        }
+    });
+}
+
+export function trackStandardPayViaBankBankConnectionSuccessful(
+    orderId: string,
+    publicKey: string,
+    bankIdentifier: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    standardUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        bankIdentifier,
+    };
+    trackEvent("Standard Pay Via Bank Bank Connection Successful", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on standard pay via bank connection:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Order Type Detection Trackers (Unified Flow)
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks when order type detection starts
+ *
+ * @param orderId - The order ID
+ * @param publicKey - The public key of the merchant
+ * @param devMode - Whether dev mode is enabled
+ */
+export function trackOrderTypeDetectionStarted(orderId: string, publicKey: string, devMode: boolean = false): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, false, undefined, "unified"),
+    };
+    trackEvent("Order Type Detection Started", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error(`[Glomo-RN-SDK] Event tracking error on order type detection started:`, error);
+        }
+    });
+}
+
+/**
+ * Tracks when order type detection resolves successfully
+ *
+ * @param orderId - The order ID
+ * @param publicKey - The public key of the merchant
+ * @param resolvedType - The resolved order type ("lrs" or "standard")
+ * @param devMode - Whether dev mode is enabled
+ */
+export function trackOrderTypeDetectionResolved(
+    orderId: string,
+    publicKey: string,
+    resolvedType: "lrs" | "standard",
+    devMode: boolean = false
+): void {
+    const eventName = resolvedType === "lrs" ? "Order Type Resolved LRS" : "Order Type Resolved Standard";
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, false, undefined, "unified"),
+    };
+    trackEvent(eventName, properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error(`[Glomo-RN-SDK] Event tracking error on order type detection resolved:`, error);
+        }
+    });
+}
+
+/**
+ * Tracks when order type detection fails
+ *
+ * @param orderId - The order ID
+ * @param publicKey - The public key of the merchant
+ * @param error - The error message
+ * @param devMode - Whether dev mode is enabled
+ */
+export function trackOrderTypeDetectionFailed(
+    orderId: string,
+    publicKey: string,
+    error: string,
+    devMode: boolean = false
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, false, undefined, "unified"),
+        error,
+    };
+    trackEvent("Order Type Detection Failed", properties, devMode).catch((trackError) => {
+        if (devMode) {
+            console.error(`[Glomo-RN-SDK] Event tracking error on order type detection failed:`, trackError);
+        }
+    });
+}
+
+/**
+ * Helper to check if analytics is enabled and log accordingly
+ * To be used for debugging merchant integration issues
+ *
+ * @param devMode - Console logs will be enabled for dev mode
+ * @returns true if GlomoPay Segment is available, false otherwise
+ */
+export function checkAnalyticsStatus(devMode: boolean = false): boolean {
+    const available = isSegmentAvailable();
+
+    if (devMode) {
+        if (available) {
+            console.log("[Glomo-RN-SDK] Analytics: ENABLED");
+        } else {
+            console.log("[Glomo-RN-SDK] Analytics: DISABLED");
+        }
+    }
+
+    return available;
+}
+
+// ---------------------------------------------------------------------------
+// Subscription Checkout Trackers
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks when the subscription checkout start() method is called (attempted)
+ */
+export function trackSubscriptionStartAttempt(
+    status: string,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        status,
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Subscription Checkout Start Attempted", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription start attempt:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when the subscription checkout start() method has been called successfully
+ */
+export function trackSubscriptionStartSuccess(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Subscription Checkout Started", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription start:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when the subscription checkout start() method fails
+ */
+export function trackSubscriptionStartFailure(
+    reason: "device_forbidden" | "validation_error" | "payment_successful" | "invalid_status" | "invalid_url",
+    orderId?: string,
+    publicKey?: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string,
+    jailbreakDetectionInfo?: {
+        jailbreakDetectionLibraryInstalled: boolean;
+        jailbreakDetected: boolean | null;
+    }
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        failureReason: reason,
+        ...(jailbreakDetectionInfo && {
+            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
+            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
+        }),
+    };
+    trackEvent("Subscription Checkout Start Failed", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription start failure:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when window.open is intercepted from the subscription checkout WebView
+ */
+export function trackSubscriptionWindowOpen(
+    source: "main" | "flow",
+    url: string,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        source,
+        url,
+    };
+    trackEvent("Subscription Checkout Window Open", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription window open:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when window.close is intercepted from the subscription checkout WebView
+ */
+export function trackSubscriptionWindowClose(
+    source: "main" | "flow",
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        source,
+    };
+    trackEvent("Subscription Checkout Window Close", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription window close:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when invalid message data is received from a subscription checkout WebView
+ */
+export function trackSubscriptionInvalidMessageReceived(
+    webviewType: "main" | "flow",
+    data: unknown,
+    url: string | undefined,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    let dataString: string;
+    try {
+        if (data === null) {
+            dataString = "null";
+        } else if (data === undefined) {
+            dataString = "undefined";
+        } else if (typeof data === "string") {
+            dataString = data;
+        } else if (typeof data === "object") {
+            dataString = JSON.stringify(data);
+        } else {
+            dataString = String(data);
+        }
+    } catch {
+        dataString = "[unable to stringify]";
+    }
+
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        webviewType,
+        data: dataString,
+        dataType: data === null ? "null" : typeof data,
+        ...(url && { url }),
+    };
+    trackEvent("Subscription Checkout Invalid Message Received", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription invalid message:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when subscription checkout onPaymentSuccess callback is invoked
+ */
+export function trackSubscriptionPaymentSuccess(
+    orderId: string,
+    paymentId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        paymentId,
+    };
+    trackEvent("Subscription Payment Success", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription payment success:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when subscription checkout onPaymentFailure callback is invoked
+ */
+export function trackSubscriptionPaymentFailure(
+    orderId: string,
+    paymentId: string,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        paymentId,
+    };
+    trackEvent("Subscription Payment Failure", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription payment failure:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when subscription checkout onPaymentTerminate callback is invoked
+ */
+export function trackSubscriptionPaymentTerminate(
+    orderId: string,
+    source: "user_dismiss" | "back_button" | "checkout_closed",
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        terminationSource: source,
+    };
+    trackEvent("Subscription Payment Terminated", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription payment terminate:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when subscription checkout onConnectionError callback is invoked
+ */
+export function trackSubscriptionConnectionError(
+    orderId: string,
+    errorCode: number | undefined,
+    publicKey: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        ...(errorCode !== undefined && { errorCode }),
+    };
+    trackEvent("Subscription Connection Error", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription connection error:", error);
+        }
+    });
+}
+
+/**
+ * Tracks when subscription checkout onSdkError callback is invoked
+ */
+export function trackSubscriptionSdkError(
+    errors: Array<SdkError>,
+    orderId?: string,
+    publicKey?: string,
+    devMode: boolean = false,
+    mockMode: boolean = false,
+    checkoutUrl?: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: orderId,
+        errors,
+        errorCount: errors.length,
+    };
+    trackEvent("Subscription SDK Error", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on subscription SDK error:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Unsupported Functionality Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal telemetry - fires when a merchant uses functionality that is
+ * unsupported in the current context or deprecated.
+ * Fires at most once per detection site (callers use a ref guard).
+ */
+export function trackUseOfUnsupportedFunctionality(
+    name: string,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl),
+        name,
+    };
+    trackEvent("Use of Unsupported Functionality", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on unsupported functionality:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Checkout Analytics Tracker Map
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal tracker map interface.
+ * Each flow (standard, subscription) provides its own implementation.
+ * useStandardCheckout calls through this map at every analytics call site.
+ * Not exported to merchants via index.ts.
+ */
+export interface CheckoutAnalyticsTrackers {
+    trackStartAttempt: typeof trackStandardStartAttempt;
+    trackStartSuccess: typeof trackStandardStartSuccess;
+    trackStartFailure: typeof trackStandardStartFailure;
+    trackWindowOpen: typeof trackStandardWindowOpen;
+    trackWindowClose: typeof trackStandardWindowClose;
+    trackInvalidMessageReceived: typeof trackStandardInvalidMessageReceived;
+    trackPaymentSuccess: typeof trackStandardPaymentSuccess;
+    trackPaymentFailure: typeof trackStandardPaymentFailure;
+    trackPaymentTerminate: typeof trackStandardPaymentTerminate;
+    trackConnectionError: typeof trackStandardConnectionError;
+    trackSdkError: typeof trackStandardSdkError;
+    trackBankTransferSubmitted: typeof trackStandardBankTransferSubmitted;
+    trackPayViaBankCompleted: typeof trackStandardPayViaBankCompleted;
+    trackPayViaBankBankConnectionSuccessful: typeof trackStandardPayViaBankBankConnectionSuccessful;
+}
+
+/** Standard checkout tracker map - delegates to trackStandard* functions */
+export const standardCheckoutTrackers: CheckoutAnalyticsTrackers = {
+    trackStartAttempt: trackStandardStartAttempt,
+    trackStartSuccess: trackStandardStartSuccess,
+    trackStartFailure: trackStandardStartFailure,
+    trackWindowOpen: trackStandardWindowOpen,
+    trackWindowClose: trackStandardWindowClose,
+    trackInvalidMessageReceived: trackStandardInvalidMessageReceived,
+    trackPaymentSuccess: trackStandardPaymentSuccess,
+    trackPaymentFailure: trackStandardPaymentFailure,
+    trackPaymentTerminate: trackStandardPaymentTerminate,
+    trackConnectionError: trackStandardConnectionError,
+    trackSdkError: trackStandardSdkError,
+    trackBankTransferSubmitted: trackStandardBankTransferSubmitted,
+    trackPayViaBankCompleted: trackStandardPayViaBankCompleted,
+    trackPayViaBankBankConnectionSuccessful: trackStandardPayViaBankBankConnectionSuccessful,
+};
+
+/** Subscription checkout tracker map - delegates to trackSubscription* functions, no-ops for bank transfer */
+export const subscriptionCheckoutTrackers: CheckoutAnalyticsTrackers = {
+    trackStartAttempt: trackSubscriptionStartAttempt,
+    trackStartSuccess: trackSubscriptionStartSuccess,
+    trackStartFailure: trackSubscriptionStartFailure,
+    trackWindowOpen: trackSubscriptionWindowOpen,
+    trackWindowClose: trackSubscriptionWindowClose,
+    trackInvalidMessageReceived: trackSubscriptionInvalidMessageReceived,
+    trackPaymentSuccess: trackSubscriptionPaymentSuccess,
+    trackPaymentFailure: trackSubscriptionPaymentFailure,
+    trackPaymentTerminate: trackSubscriptionPaymentTerminate,
+    trackConnectionError: trackSubscriptionConnectionError,
+    trackSdkError: trackSubscriptionSdkError,
+    trackBankTransferSubmitted: (...args) => {
+        const devMode = args[2];
+        if (devMode) {
+            console.warn("[Glomo-RN-SDK] Unexpected bank transfer event in subscription flow");
+        }
+    },
+    trackPayViaBankCompleted: (...args) => {
+        const devMode = args[3];
+        if (devMode) {
+            console.warn("[Glomo-RN-SDK] Unexpected pay via bank completed event in subscription flow");
+        }
+    },
+    trackPayViaBankBankConnectionSuccessful: (...args) => {
+        const devMode = args[3];
+        if (devMode) {
+            console.warn("[Glomo-RN-SDK] Unexpected pay via bank connection event in subscription flow");
+        }
+    },
+};