@tagadapay/plugin-sdk 2.7.20 → 2.7.21

package/dist/react/components/DebugDrawer.js

@@ -95,13 +95,32 @@ export const DebugDrawer = ({ isOpen, onClose }) => {
         { id: 'session', label: 'Session' },
         { id: 'auth', label: 'Auth' },
     ];
+    // Add funnel tab if funnel is active
+    const funnelTab = context.debugFunnel.isActive ? [{ id: 'funnel', label: 'Funnel' }] : [];
+    // Debug: Log comprehensive debug drawer state
+    if (isOpen) {
+        console.group('🐛 [DebugDrawer] Comprehensive State Check');
+        console.log('1️⃣ Debug Mode:', context.debugMode);
+        console.log('2️⃣ Funnel Debug State:', {
+            isActive: context.debugFunnel.isActive,
+            hasData: !!context.debugFunnel.data,
+            hasError: !!context.debugFunnel.error,
+            isLoading: context.debugFunnel.isLoading,
+            lastUpdated: context.debugFunnel.lastUpdated,
+        });
+        console.log('3️⃣ Funnel Data (if any):', context.debugFunnel.data);
+        console.log('4️⃣ Funnel Error (if any):', context.debugFunnel.error);
+        console.log('5️⃣ Update Function Available:', typeof context.updateFunnelDebugData);
+        console.log('6️⃣ Will show Funnel tab:', funnelTab.length > 0);
+        console.groupEnd();
+    }
     // Add checkout tab if checkout is active
     const checkoutTab = context.debugCheckout.isActive ? [{ id: 'checkout', label: 'Checkout' }] : [];
     // Add items tab if checkout has summary data
     const itemsTab = context.debugCheckout.isActive && context.debugCheckout.data?.checkout?.summary
         ? [{ id: 'items', label: 'Items' }]
         : [];
-    const tabs = [...baseTabs, ...checkoutTab, ...itemsTab, { id: 'raw', label: 'Raw Data' }];
+    const tabs = [...baseTabs, ...funnelTab, ...checkoutTab, ...itemsTab, { id: 'raw', label: 'Raw Data' }];
     return (_jsxs(_Fragment, { children: [_jsx("div", { style: {
                     position: 'fixed',
                     top: 0,
@@ -169,7 +188,66 @@ export const DebugDrawer = ({ isOpen, onClose }) => {
                                             border: '1px solid #374151',
                                             borderRadius: '6px',
                                             marginTop: '16px',
-                                        }, children: [_jsx("h4", { style: { margin: '0 0 8px 0', color: '#f59e0b', fontSize: '14px' }, children: "Development Mode" }), _jsxs("p", { style: { margin: '0', fontSize: '12px', color: '#9ca3af', lineHeight: '1.4' }, children: ["Configuration is loaded from ", _jsx("code", { style: { color: '#60a5fa' }, children: "/.local.json" }), " and", ' ', _jsxs("code", { style: { color: '#60a5fa' }, children: ["/config/", pluginConfig.config?.configName || 'default', ".tgd.json"] })] }), _jsxs("p", { style: { margin: '8px 0 0 0', fontSize: '12px', color: '#9ca3af', lineHeight: '1.4' }, children: ["Local config variant:", ' ', _jsx("code", { style: { color: '#f59e0b' }, children: pluginConfig.config?.configName || 'default' })] })] }))] })), activeTab === 'store' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Store Configuration" }), context.store ? (_jsx(TreeView, { data: context.store, name: "store" })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No store data available" }))] })), activeTab === 'session' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Session Data" }), context.session ? (_jsx(TreeView, { data: context.session, name: "session" })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No session data available" }))] })), activeTab === 'auth' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Authentication State" }), _jsx(TreeView, { data: context.auth, name: "auth" }), context.customer && (_jsxs(_Fragment, { children: [_jsx("h4", { style: { margin: '24px 0 12px 0', color: '#60a5fa' }, children: "Customer Data" }), _jsx(TreeView, { data: context.customer, name: "customer" })] }))] })), activeTab === 'items' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Items & Discounts" }), context.debugCheckout.data?.checkout?.summary ? (_jsxs("div", { children: [_jsxs("div", { style: { marginBottom: '24px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Summary" }), _jsxs("div", { style: { display: 'grid', gap: '8px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Currency:" }), _jsx("span", { style: { color: '#f59e0b' }, children: context.debugCheckout.data.checkout.summary.currency })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Subtotal:" }), _jsx("span", { style: { color: '#9ca3af' }, children: (() => {
+                                        }, children: [_jsx("h4", { style: { margin: '0 0 8px 0', color: '#f59e0b', fontSize: '14px' }, children: "Development Mode" }), _jsxs("p", { style: { margin: '0', fontSize: '12px', color: '#9ca3af', lineHeight: '1.4' }, children: ["Configuration is loaded from ", _jsx("code", { style: { color: '#60a5fa' }, children: "/.local.json" }), " and", ' ', _jsxs("code", { style: { color: '#60a5fa' }, children: ["/config/", pluginConfig.config?.configName || 'default', ".tgd.json"] })] }), _jsxs("p", { style: { margin: '8px 0 0 0', fontSize: '12px', color: '#9ca3af', lineHeight: '1.4' }, children: ["Local config variant:", ' ', _jsx("code", { style: { color: '#f59e0b' }, children: pluginConfig.config?.configName || 'default' })] })] }))] })), activeTab === 'store' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Store Configuration" }), context.store ? (_jsx(TreeView, { data: context.store, name: "store" })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No store data available" }))] })), activeTab === 'session' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Session Data" }), context.session ? (_jsx(TreeView, { data: context.session, name: "session" })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No session data available" }))] })), activeTab === 'auth' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Authentication State" }), _jsx(TreeView, { data: context.auth, name: "auth" }), context.customer && (_jsxs(_Fragment, { children: [_jsx("h4", { style: { margin: '24px 0 12px 0', color: '#60a5fa' }, children: "Customer Data" }), _jsx(TreeView, { data: context.customer, name: "customer" })] }))] })), activeTab === 'funnel' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Funnel Navigation" }), context.debugFunnel.isActive && context.debugFunnel.data ? (_jsxs("div", { children: [_jsxs("div", { style: { marginBottom: '24px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Current Funnel" }), _jsxs("div", { style: { display: 'grid', gap: '8px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Funnel Name:" }), _jsx("span", { style: { color: '#10b981', fontWeight: 'bold' }, children: context.debugFunnel.data.funnel?.name || 'Unknown' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Funnel ID:" }), _jsx("span", { style: { color: '#60a5fa', fontSize: '12px' }, children: context.debugFunnel.data.funnel?.id || 'N/A' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Total Steps:" }), _jsx("span", { style: { color: '#f59e0b' }, children: context.debugFunnel.data.funnel?.steps?.length || 0 })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Visited Steps:" }), _jsx("span", { style: { color: '#8b5cf6' }, children: context.debugFunnel.data.session?.totalStepsVisited || 0 })] }), context.debugFunnel.data.session?.cycleDetected && (_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Cycle Detected:" }), _jsx("span", { style: { color: '#ef4444', fontWeight: 'bold' }, children: "\u26A0\uFE0F Yes" })] }))] })] }), context.debugFunnel.data.funnel?.steps && (_jsxs("div", { style: { marginBottom: '24px' }, children: [_jsxs("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: ["Funnel Steps (", context.debugFunnel.data.funnel.steps.length, ")"] }), _jsx("div", { style: { display: 'grid', gap: '12px' }, children: context.debugFunnel.data.funnel.steps.map((step, index) => {
+                                                            // Get current step ID from debug funnel data
+                                                            const currentStepId = context.debugFunnel.data.session?.currentStepId;
+                                                            // Determine if this is the current step
+                                                            const isCurrent = step.id === currentStepId;
+                                                            // Determine if this step was visited
+                                                            const wasVisited = context.debugFunnel.data.session?.visitedSteps?.includes(step.id);
+                                                            return (_jsxs("div", { style: {
+                                                                    border: isCurrent ? '2px solid #10b981' : '1px solid #374151',
+                                                                    borderRadius: '8px',
+                                                                    padding: '12px',
+                                                                    backgroundColor: isCurrent ? '#064e3b' : '#111827',
+                                                                    position: 'relative',
+                                                                }, children: [isCurrent && (_jsx("div", { style: {
+                                                                            position: 'absolute',
+                                                                            top: '8px',
+                                                                            right: '8px',
+                                                                            backgroundColor: '#10b981',
+                                                                            color: '#000',
+                                                                            padding: '2px 8px',
+                                                                            borderRadius: '4px',
+                                                                            fontSize: '10px',
+                                                                            fontWeight: 'bold',
+                                                                        }, children: "CURRENT" })), wasVisited && !isCurrent && (_jsx("div", { style: {
+                                                                            position: 'absolute',
+                                                                            top: '8px',
+                                                                            right: '8px',
+                                                                            backgroundColor: '#8b5cf6',
+                                                                            color: '#fff',
+                                                                            padding: '2px 8px',
+                                                                            borderRadius: '4px',
+                                                                            fontSize: '10px',
+                                                                            fontWeight: 'bold',
+                                                                        }, children: "VISITED" })), _jsxs("div", { style: {
+                                                                            marginBottom: '8px',
+                                                                            marginRight: wasVisited || isCurrent ? '80px' : '0',
+                                                                        }, children: [_jsxs("div", { style: {
+                                                                                    color: isCurrent ? '#6ee7b7' : '#f9fafb',
+                                                                                    fontWeight: 'bold',
+                                                                                    marginBottom: '4px',
+                                                                                    fontSize: '14px',
+                                                                                }, children: [step.name || `Step ${index + 1}`, step.isEntry && (_jsx("span", { style: {
+                                                                                            marginLeft: '8px',
+                                                                                            fontSize: '10px',
+                                                                                            backgroundColor: '#3b82f6',
+                                                                                            color: '#fff',
+                                                                                            padding: '2px 6px',
+                                                                                            borderRadius: '4px',
+                                                                                        }, children: "ENTRY" }))] }), _jsxs("div", { style: { fontSize: '11px', color: '#9ca3af' }, children: ["Type: ", step.type, " \u2022 Index: ", step.index, step.row !== undefined && ` • Row: ${step.row}`] }), step.url && (_jsxs("div", { style: { fontSize: '11px', color: '#60a5fa', marginTop: '4px' }, children: ["URL: ", step.url] }))] }), step.conditions && (_jsxs("div", { style: {
+                                                                            backgroundColor: '#1f2937',
+                                                                            padding: '8px',
+                                                                            borderRadius: '4px',
+                                                                            marginTop: '8px',
+                                                                        }, children: [_jsx("div", { style: {
+                                                                                    fontSize: '10px',
+                                                                                    color: '#60a5fa',
+                                                                                    fontWeight: 'bold',
+                                                                                    marginBottom: '4px',
+                                                                                }, children: "Conditions:" }), _jsx(TreeView, { data: step.conditions, name: "conditions", maxLevel: 2 })] })), _jsxs("div", { style: { fontSize: '9px', color: '#6b7280', marginTop: '8px' }, children: ["ID: ", step.id] })] }, step.id || index));
+                                                        }) })] })), _jsxs("div", { children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Full Funnel Data" }), _jsx(TreeView, { data: context.debugFunnel.data, name: "funnelDebugData", maxLevel: 3 })] })] })) : (_jsxs("p", { style: { color: '#6b7280' }, children: ["No funnel data available. Use the ", _jsx("code", { children: "useFunnel" }), " hook to activate funnel tracking."] }))] })), activeTab === 'items' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Items & Discounts" }), context.debugCheckout.data?.checkout?.summary ? (_jsxs("div", { children: [_jsxs("div", { style: { marginBottom: '24px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Summary" }), _jsxs("div", { style: { display: 'grid', gap: '8px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Currency:" }), _jsx("span", { style: { color: '#f59e0b' }, children: context.debugCheckout.data.checkout.summary.currency })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Subtotal:" }), _jsx("span", { style: { color: '#9ca3af' }, children: (() => {
                                                                             try {
                                                                                 return context.money.formatMoney(Number(context.debugCheckout.data.checkout.summary.subtotalAmount) || 0, String(context.debugCheckout.data.checkout.summary.currency) || 'USD', context.locale.locale);
                                                                             }

package/dist/react/hooks/useFunnel.d.ts

@@ -1,8 +1,91 @@
-export interface FunnelEvent {
-    type: string;
-    data?: any;
+/**
+ * Funnel event types enum
+ *
+ * Special types:
+ * - DIRECT_NAVIGATION: Bypasses step conditions, navigates directly to targetStepId
+ * - BACK_NAVIGATION: Similar to direct_navigation, used for backward navigation
+ *
+ * Common types (for logging/tracking):
+ * - Any string value is accepted, but these are commonly used examples
+ */
+export declare enum FunnelEventType {
+    DIRECT_NAVIGATION = "direct_navigation",
+    BACK_NAVIGATION = "back_navigation",
+    PAYMENT_SUCCESS = "payment_success",
+    CUSTOM = "custom"
+}
+/**
+ * Data structures for specific event types
+ */
+export type NextEvent<T> = T & {
+    [key: string]: any;
+};
+export interface DirectNavigationEventData {
+    targetStepId: string;
+}
+export interface BackNavigationEventData {
+    targetStepId: string;
+}
+export interface QuizCompletedEventData {
+    quiz: {
+        score: number;
+        [key: string]: any;
+    };
+}
+export interface OfferAcceptedEventData {
+    offer: {
+        accepted: boolean;
+        offerId?: string;
+        [key: string]: any;
+    };
+}
+export interface FormSubmitEventData {
+    [key: string]: any;
+}
+export interface PaymentSuccessEventData {
+    payment?: {
+        status: 'success';
+        amount: number;
+        currency: string;
+        orderId?: string;
+        transactionId?: string;
+        timestamp?: string;
+        [key: string]: any;
+    };
+    order?: {
+        id: string;
+        amount: number;
+        currency: string;
+        [key: string]: any;
+    };
+    paymentId?: string;
+    [key: string]: any;
+}
+/**
+ * Base properties shared by all FunnelEvent types
+ */
+interface BaseFunnelEvent {
+    /**
+     * Event timestamp
+     */
     timestamp?: Date;
 }
+/**
+ * Discriminated union for FunnelEvent based on event type
+ */
+export type FunnelEvent = BaseFunnelEvent & (({
+    type: FunnelEventType.DIRECT_NAVIGATION;
+    data: NextEvent<DirectNavigationEventData>;
+}) | ({
+    type: FunnelEventType.BACK_NAVIGATION;
+    data: NextEvent<BackNavigationEventData>;
+}) | ({
+    type: FunnelEventType.PAYMENT_SUCCESS;
+    data?: NextEvent<PaymentSuccessEventData>;
+}) | ({
+    type: FunnelEventType.CUSTOM;
+    data?: NextEvent<any>;
+}));
 export interface FunnelNavigationAction {
     type: 'redirect' | 'replace' | 'push' | 'external' | 'none';
     url?: string;
@@ -68,3 +151,4 @@ export declare function useSimpleFunnel(funnelId: string, initialStepId?: string
     goToStep: (stepId: string) => Promise<any>;
     isLoading: boolean;
 };
+export {};

package/dist/react/hooks/useFunnel.js

@@ -1,5 +1,23 @@
-import { useState, useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useTagadaContext } from '../providers/TagadaProvider';
+/**
+ * Funnel event types enum
+ *
+ * Special types:
+ * - DIRECT_NAVIGATION: Bypasses step conditions, navigates directly to targetStepId
+ * - BACK_NAVIGATION: Similar to direct_navigation, used for backward navigation
+ *
+ * Common types (for logging/tracking):
+ * - Any string value is accepted, but these are commonly used examples
+ */
+export var FunnelEventType;
+(function (FunnelEventType) {
+    // Special navigation types
+    FunnelEventType["DIRECT_NAVIGATION"] = "direct_navigation";
+    FunnelEventType["BACK_NAVIGATION"] = "back_navigation";
+    FunnelEventType["PAYMENT_SUCCESS"] = "payment_success";
+    FunnelEventType["CUSTOM"] = "custom";
+})(FunnelEventType || (FunnelEventType = {}));
 /**
  * React Hook for Funnel Navigation (Plugin SDK Version)
  *
@@ -7,7 +25,7 @@ import { useTagadaContext } from '../providers/TagadaProvider';
  * Integrates with TagadaPay authentication and plugin routing.
  */
 export function useFunnel(options) {
-    const { auth, apiService, store } = useTagadaContext();
+    const { auth, apiService, store, updateFunnelDebugData, debugMode } = useTagadaContext();
     const [isLoading, setIsLoading] = useState(false);
     const [isInitialized, setIsInitialized] = useState(false);
     const [context, setContext] = useState(null);
@@ -19,6 +37,35 @@ export function useFunnel(options) {
     const urlFunnelId = urlParams.get('funnelId') || undefined;
     const effectiveFunnelId = urlFunnelId || options.funnelId;
     // Removed checkExistingSession - now handled in single initialize call
+    /**
+     * Fetch funnel session with debug data (debug mode only)
+     */
+    const fetchFunnelDebugData = useCallback(async (sessionId) => {
+        if (!debugMode) {
+            console.log('🐛 [useFunnel] Debug mode is OFF, skipping debug data fetch');
+            return;
+        }
+        console.log('🐛 [useFunnel] Fetching debug data for session:', sessionId);
+        try {
+            const response = await apiService.fetch(`/api/v1/funnel/session/${sessionId}`, {
+                method: 'GET',
+                params: {
+                    includeDebugData: 'true',
+                },
+            });
+            console.log('🐛 [useFunnel] Debug data response:', response);
+            if (response.success && response.debugData) {
+                updateFunnelDebugData(response.debugData, null, false);
+                console.log('🐛 [useFunnel] Debug data updated successfully:', response.debugData);
+            }
+            else {
+                console.warn('🐛 [useFunnel] No debug data in response');
+            }
+        }
+        catch (error) {
+            console.error('🐛 [useFunnel] Failed to fetch funnel debug data:', error);
+        }
+    }, [apiService, debugMode, updateFunnelDebugData]);
     /**
      * Set funnel session cookie
      */
@@ -91,6 +138,19 @@ export function useFunnel(options) {
                 // Set session cookie for persistence across page reloads
                 setSessionCookie(response.context.sessionId);
                 console.log(`🍪 Funnel: Initialized new session for funnel ${effectiveFunnelId || 'default'}`, response.context);
+                // Fetch debug data if in debug mode
+                console.log('🐛 [useFunnel INIT] Checking debug mode:', {
+                    debugMode,
+                    sessionId: response.context.sessionId,
+                    hasUpdateFunction: typeof updateFunnelDebugData,
+                });
+                if (debugMode) {
+                    console.log('🐛 [useFunnel INIT] Debug mode is ON, calling fetchFunnelDebugData...');
+                    void fetchFunnelDebugData(response.context.sessionId);
+                }
+                else {
+                    console.warn('🐛 [useFunnel INIT] Debug mode is OFF, will not fetch debug data');
+                }
             }
             else {
                 throw new Error(response.error || 'Failed to initialize funnel session');
@@ -108,7 +168,7 @@ export function useFunnel(options) {
         finally {
             setIsLoading(false);
         }
-    }, [auth.session?.customerId, store?.id, effectiveFunnelId, apiService, options.onError]);
+    }, [auth.session?.customerId, store?.id, effectiveFunnelId, apiService, options.onError, debugMode, fetchFunnelDebugData]);
     /**
      * Navigate to next step based on event
      */
@@ -177,6 +237,18 @@ export function useFunnel(options) {
                     performNavigation(updatedAction);
                 }
                 console.log(`🍪 Funnel: Navigated from ${context.currentStepId} to ${result.stepId}`);
+                // Fetch debug data if in debug mode
+                console.log('🐛 [useFunnel NAV] After navigation, checking debug mode:', {
+                    debugMode,
+                    sessionId: newContext.sessionId,
+                });
+                if (debugMode && newContext.sessionId) {
+                    console.log('🐛 [useFunnel NAV] Fetching debug data after navigation...');
+                    void fetchFunnelDebugData(newContext.sessionId);
+                }
+                else {
+                    console.warn('🐛 [useFunnel NAV] Not fetching debug data:', { debugMode, hasSessionId: !!newContext.sessionId });
+                }
                 return result;
             }
             else {
@@ -193,13 +265,13 @@ export function useFunnel(options) {
         finally {
             setIsLoading(false);
         }
-    }, [context, apiService, options.onNavigate, options.onError]);
+    }, [context, apiService, options.onNavigate, options.onError, debugMode, fetchFunnelDebugData]);
     /**
      * Go directly to a specific step (bypass conditions)
      */
     const goToStep = useCallback(async (stepId) => {
         return next({
-            type: 'direct_navigation',
+            type: FunnelEventType.DIRECT_NAVIGATION,
             data: { targetStepId: stepId },
             timestamp: new Date()
         });

package/dist/react/providers/TagadaProvider.d.ts

@@ -29,6 +29,14 @@ interface TagadaContextValue {
         lastUpdated: Date | null;
     };
     updateCheckoutDebugData: (data: any, error?: Error | null, isLoading?: boolean) => void;
+    debugFunnel: {
+        isActive: boolean;
+        data: any;
+        error: Error | null;
+        isLoading: boolean;
+        lastUpdated: Date | null;
+    };
+    updateFunnelDebugData: (data: any, error?: Error | null, isLoading?: boolean) => void;
     refreshCoordinator: {
         registerCheckoutRefresh: (refreshFn: () => Promise<void>) => void;
         registerOrderBumpRefresh: (refreshFn: () => Promise<void>) => void;

package/dist/react/providers/TagadaProvider.js

@@ -198,6 +198,14 @@ rawPluginConfig, }) {
         isLoading: false,
         lastUpdated: null,
     });
+    // Initialize debug funnel state
+    const [debugFunnel, setDebugFunnel] = useState({
+        isActive: false,
+        data: null,
+        error: null,
+        isLoading: false,
+        lastUpdated: null,
+    });
     // Initialize auth state
     const [auth, setAuth] = useState({
         isAuthenticated: false,
@@ -518,6 +526,16 @@ rawPluginConfig, }) {
                 lastUpdated: new Date(),
             });
         },
+        debugFunnel,
+        updateFunnelDebugData: (data, error, isLoading) => {
+            setDebugFunnel({
+                isActive: true,
+                data,
+                error: error ?? null,
+                isLoading: isLoading ?? false,
+                lastUpdated: new Date(),
+            });
+        },
         refreshCoordinator,
         money: {
             formatMoney,
@@ -544,6 +562,7 @@ rawPluginConfig, }) {
         pluginConfig,
         configLoading,
         debugCheckout,
+        debugFunnel,
         refreshCoordinator,
     ]);
     // Determine if we should show loading

package/dist/v2/core/resources/funnel.d.ts

@@ -2,9 +2,57 @@
  * Funnel Resource - API client for funnel navigation and session management
  */
 import { ApiClient } from './apiClient';
-export interface FunnelEvent {
-    type: string;
-    data?: any;
+/**
+ * Funnel event types enum
+ *
+ * Special types:
+ * - DIRECT_NAVIGATION: Bypasses step conditions, navigates directly to targetStepId
+ * - BACK_NAVIGATION: Similar to direct_navigation, used for backward navigation
+ *
+ * Common types (for logging/tracking):
+ * - Any string value is accepted, but these are commonly used examples
+ */
+export declare enum FunnelEventType {
+    DIRECT_NAVIGATION = "direct_navigation",
+    BACK_NAVIGATION = "back_navigation",
+    PAYMENT_SUCCESS = "payment_success",
+    CUSTOM = "custom"
+}
+/**
+ * Data structures for specific event types
+ */
+export type NextEvent<T> = T & {
+    [key: string]: any;
+};
+export interface DirectNavigationEventData {
+    targetStepId: string;
+}
+export interface BackNavigationEventData {
+    targetStepId: string;
+}
+export interface PaymentSuccessEventData {
+    payment: {
+        id: string;
+        status: string;
+        transactionId?: string;
+        timestamp?: string;
+        [key: string]: any;
+    };
+    order: {
+        id: string;
+        amount: number;
+        currency: string;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+/**
+ * Base properties shared by all FunnelEvent types
+ */
+interface BaseFunnelEvent {
+    /**
+     * Event timestamp (ISO string format)
+     */
     timestamp?: string;
     /**
      * Current URL for session synchronization (browser back/forward handling)
@@ -13,6 +61,22 @@ export interface FunnelEvent {
      */
     currentUrl?: string;
 }
+/**
+ * Discriminated union for FunnelEvent based on event type
+ */
+export type FunnelAction = BaseFunnelEvent & (({
+    type: FunnelEventType.DIRECT_NAVIGATION;
+    data: NextEvent<DirectNavigationEventData>;
+}) | ({
+    type: FunnelEventType.BACK_NAVIGATION;
+    data: NextEvent<BackNavigationEventData>;
+}) | ({
+    type: FunnelEventType.PAYMENT_SUCCESS;
+    data: NextEvent<PaymentSuccessEventData>;
+}) | ({
+    type: FunnelEventType.CUSTOM;
+    data?: NextEvent<any>;
+}));
 export interface FunnelNavigationAction {
     type: 'redirect' | 'replace' | 'push' | 'external' | 'none';
     url?: string;
@@ -63,7 +127,7 @@ export interface FunnelInitializeResponse {
 }
 export interface FunnelNavigateRequest {
     sessionId: string;
-    event: FunnelEvent;
+    event: FunnelAction;
     contextUpdates?: Partial<SimpleFunnelContext>;
     /**
      * Current URL for URL-to-Step mapping (browser back/forward sync)
@@ -129,9 +193,11 @@ export declare class FunnelResource {
      * @param sessionId - The session ID to fetch
      * @param currentUrl - Optional current URL for session synchronization on page load
      */
-    getSession(sessionId: string, currentUrl?: string): Promise<{
+    getSession(sessionId: string, currentUrl?: string, includeDebugData?: boolean): Promise<{
         success: boolean;
         context?: SimpleFunnelContext;
+        debugData?: any;
         error?: string;
     }>;
 }
+export {};

package/dist/v2/core/resources/funnel.js

@@ -1,6 +1,24 @@
 /**
  * Funnel Resource - API client for funnel navigation and session management
  */
+/**
+ * Funnel event types enum
+ *
+ * Special types:
+ * - DIRECT_NAVIGATION: Bypasses step conditions, navigates directly to targetStepId
+ * - BACK_NAVIGATION: Similar to direct_navigation, used for backward navigation
+ *
+ * Common types (for logging/tracking):
+ * - Any string value is accepted, but these are commonly used examples
+ */
+export var FunnelEventType;
+(function (FunnelEventType) {
+    // Special navigation types
+    FunnelEventType["DIRECT_NAVIGATION"] = "direct_navigation";
+    FunnelEventType["BACK_NAVIGATION"] = "back_navigation";
+    FunnelEventType["PAYMENT_SUCCESS"] = "payment_success";
+    FunnelEventType["CUSTOM"] = "custom";
+})(FunnelEventType || (FunnelEventType = {}));
 export class FunnelResource {
     constructor(apiClient) {
         this.apiClient = apiClient;
@@ -34,9 +52,15 @@ export class FunnelResource {
      * @param sessionId - The session ID to fetch
      * @param currentUrl - Optional current URL for session synchronization on page load
      */
-    async getSession(sessionId, currentUrl) {
-        const params = currentUrl ? new URLSearchParams({ currentUrl }) : undefined;
-        const url = `/api/v1/funnel/session/${sessionId}${params ? `?${params}` : ''}`;
+    async getSession(sessionId, currentUrl, includeDebugData) {
+        const params = new URLSearchParams();
+        if (currentUrl) {
+            params.append('currentUrl', currentUrl);
+        }
+        if (includeDebugData) {
+            params.append('includeDebugData', 'true');
+        }
+        const url = `/api/v1/funnel/session/${sessionId}${params.toString() ? `?${params}` : ''}`;
         return this.apiClient.get(url);
     }
 }

package/dist/v2/index.d.ts

@@ -21,8 +21,9 @@ export type { ShippingRate, ShippingRatesResponse } from './core/resources/shipp
 export type { ApplyDiscountResponse, Discount, DiscountCodeValidation, RemoveDiscountResponse } from './core/resources/discounts';
 export type { ToggleOrderBumpResponse, VipOffer, VipPreviewResponse } from './core/resources/vipOffers';
 export type { StoreConfig } from './core/resources/storeConfig';
-export type { FunnelContextUpdateRequest, FunnelContextUpdateResponse, FunnelEvent, FunnelInitializeRequest, FunnelInitializeResponse, FunnelNavigateRequest, FunnelNavigateResponse, FunnelNavigationAction, FunnelNavigationResult, SimpleFunnelContext } from './core/resources/funnel';
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { FunnelEventType } from './core/resources/funnel';
+export type { BackNavigationEventData, DirectNavigationEventData, FunnelContextUpdateRequest, FunnelContextUpdateResponse, FunnelAction as FunnelEvent, FunnelInitializeRequest, FunnelInitializeResponse, FunnelNavigateRequest, FunnelNavigateResponse, FunnelNavigationAction, FunnelNavigationResult, NextEvent, PaymentSuccessEventData, SimpleFunnelContext } from './core/resources/funnel';
+export { ApplePayButton, ExpressPaymentMethodsProvider, GooglePayButton, TagadaProvider, formatMoney, getAvailableLanguages, queryKeys, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useISOData, useInvalidateQuery, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
 export type { TranslateFunction, TranslationText, UseTranslationOptions, UseTranslationResult } from './react/hooks/useTranslation';
 export type { ClubOffer, ClubOfferItem, ClubOfferLineItem, ClubOfferSummary, UseClubOffersOptions, UseClubOffersResult } from './react/hooks/useClubOffers';
 export type { UseLoginOptions, UseLoginResult } from './react/hooks/useLogin';

package/dist/v2/index.js

@@ -13,5 +13,6 @@ export * from './core/utils/pluginConfig';
 export * from './core/utils/products';
 // Path remapping helpers (framework-agnostic)
 export * from './core/pathRemapping';
+export { FunnelEventType } from './core/resources/funnel';
 // React exports (hooks and components only, types are exported above)
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { ApplePayButton, ExpressPaymentMethodsProvider, GooglePayButton, TagadaProvider, formatMoney, getAvailableLanguages, queryKeys, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useISOData, useInvalidateQuery, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';