@tagadapay/plugin-sdk 2.8.8 → 2.8.10

package/dist/v2/react/hooks/__examples__/FunnelContextExample.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Example: Accessing Funnel Context & Resources
+ *
+ * This example demonstrates how to access data from previous steps
+ * using the funnel context, including order, customer, and other resources.
+ */
+import { useFunnel } from '../useFunnel';
+export function FunnelContextExample() {
+    const { context, isLoading, isInitialized } = useFunnel({
+        autoInitialize: true,
+    });
+    if (isLoading) {
+        return _jsx("div", { children: "Loading funnel session..." });
+    }
+    if (!isInitialized || !context) {
+        return _jsx("div", { children: "Funnel not initialized" });
+    }
+    // Access resources from context
+    const order = context.resources?.order;
+    const customer = context.resources?.customer;
+    const checkout = context.resources?.checkout;
+    const orders = context.resources?.orders || [];
+    return (_jsxs("div", { style: { padding: '20px', fontFamily: 'sans-serif' }, children: [_jsx("h1", { children: "Funnel Context Example" }), _jsxs("section", { style: { marginBottom: '30px' }, children: [_jsx("h2", { children: "Session Info" }), _jsxs("ul", { children: [_jsxs("li", { children: [_jsx("strong", { children: "Session ID:" }), " ", context.sessionId] }), _jsxs("li", { children: [_jsx("strong", { children: "Funnel ID:" }), " ", context.funnelId] }), _jsxs("li", { children: [_jsx("strong", { children: "Current Step:" }), " ", context.currentStepId] }), _jsxs("li", { children: [_jsx("strong", { children: "Previous Step:" }), " ", context.previousStepId || 'None'] }), _jsxs("li", { children: [_jsx("strong", { children: "Furthest Step:" }), " ", context.furthestStepId || 'None'] }), _jsxs("li", { children: [_jsx("strong", { children: "Environment:" }), " ", context.environment || 'Not set'] })] })] }), _jsxs("section", { style: { marginBottom: '30px' }, children: [_jsx("h2", { children: "Resources" }), order && (_jsxs("div", { style: { marginBottom: '20px', padding: '15px', border: '1px solid #ddd', borderRadius: '5px' }, children: [_jsx("h3", { children: "Order (Hot Context)" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '10px', borderRadius: '3px', overflow: 'auto' }, children: JSON.stringify(order, null, 2) })] })), customer && (_jsxs("div", { style: { marginBottom: '20px', padding: '15px', border: '1px solid #ddd', borderRadius: '5px' }, children: [_jsx("h3", { children: "Customer" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '10px', borderRadius: '3px', overflow: 'auto' }, children: JSON.stringify(customer, null, 2) })] })), checkout && (_jsxs("div", { style: { marginBottom: '20px', padding: '15px', border: '1px solid #ddd', borderRadius: '5px' }, children: [_jsx("h3", { children: "Checkout" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '10px', borderRadius: '3px', overflow: 'auto' }, children: JSON.stringify(checkout, null, 2) })] })), orders.length > 0 && (_jsxs("div", { style: { marginBottom: '20px', padding: '15px', border: '1px solid #ddd', borderRadius: '5px' }, children: [_jsxs("h3", { children: ["Orders Collection (", orders.length, " orders)"] }), orders.map((o, index) => (_jsxs("div", { style: { marginBottom: '10px' }, children: [_jsxs("strong", { children: ["Order ", index + 1, ":"] }), _jsx("pre", { style: {
+                                            background: '#f5f5f5',
+                                            padding: '10px',
+                                            borderRadius: '3px',
+                                            marginTop: '5px',
+                                            overflow: 'auto',
+                                        }, children: JSON.stringify(o, null, 2) })] }, o.id || index)))] })), _jsxs("details", { style: { marginTop: '20px' }, children: [_jsx("summary", { style: { cursor: 'pointer', fontWeight: 'bold' }, children: "Show All Resources (Raw)" }), _jsx("pre", { style: {
+                                    background: '#f5f5f5',
+                                    padding: '10px',
+                                    borderRadius: '3px',
+                                    marginTop: '10px',
+                                    overflow: 'auto',
+                                }, children: JSON.stringify(context.resources, null, 2) })] })] }), context.metadata && Object.keys(context.metadata).length > 0 && (_jsxs("section", { style: { marginBottom: '30px' }, children: [_jsx("h2", { children: "Metadata" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '10px', borderRadius: '3px', overflow: 'auto' }, children: JSON.stringify(context.metadata, null, 2) })] })), _jsxs("details", { children: [_jsx("summary", { style: { cursor: 'pointer', fontWeight: 'bold' }, children: "Show Full Context (Debug)" }), _jsx("pre", { style: {
+                            background: '#f5f5f5',
+                            padding: '10px',
+                            borderRadius: '3px',
+                            marginTop: '10px',
+                            overflow: 'auto',
+                        }, children: JSON.stringify(context, null, 2) })] })] }));
+}
+/**
+ * Simple example for documentation
+ * This can now be called with or without options
+ */
+export function SimpleContextExample() {
+    const funnel = useFunnel(); // Works without params!
+    // Access data from previous steps
+    const order = funnel.context?.resources?.order;
+    const customer = funnel.context?.resources?.customer;
+    return (_jsxs("div", { children: [_jsxs("h1", { children: ["Order ", order?.id] }), _jsxs("p", { children: ["Customer: ", customer?.email] }), _jsxs("p", { children: ["Amount: $", ((order?.amount || 0) / 100).toFixed(2)] })] }));
+}

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

@@ -23,6 +23,7 @@ export interface UseFunnelResult {
     context: SimpleFunnelContext | null;
     isLoading: boolean;
     isInitialized: boolean;
+    isNavigating: boolean;
     initializeSession: (entryStepId?: string) => Promise<void>;
     endSession: () => Promise<void>;
     retryInitialization: () => Promise<void>;
@@ -37,7 +38,7 @@ export interface UseFunnelResult {
  * Modern funnel navigation using TanStack Query for state management
  * and the v2 ApiClient architecture.
  */
-export declare function useFunnel(options: UseFunnelOptions): UseFunnelResult;
+export declare function useFunnel(options?: UseFunnelOptions): UseFunnelResult;
 /**
  * Simplified funnel hook for basic step tracking (v2)
  */

package/dist/v2/react/hooks/useFunnel.js

@@ -5,7 +5,7 @@
  * and the v2 ApiClient for API calls.
  */
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { FunnelActionType, FunnelResource } from '../../core/resources/funnel';
 import { useTagadaContext } from '../providers/TagadaProvider';
 import { getGlobalApiClient } from './useApiQuery';
@@ -20,19 +20,86 @@ const funnelQueryKeys = {
  * Modern funnel navigation using TanStack Query for state management
  * and the v2 ApiClient architecture.
  */
-export function useFunnel(options) {
-    const { auth, store, debugMode, updateFunnelDebugData } = useTagadaContext();
+export function useFunnel(options = {}) {
+    const { auth, store, debugMode, updateFunnelDebugData, pluginConfig } = useTagadaContext();
     const queryClient = useQueryClient();
     const apiClient = getGlobalApiClient();
     const funnelResource = useMemo(() => new FunnelResource(apiClient), [apiClient]);
+    /**
+     * Helper to merge backend context with local static resources
+     * Allows mocking static resources in local development via resources.static.json
+     */
+    const enrichContext = useCallback((ctx) => {
+        // If we have local static resources (from resources.static.json), merge them
+        // Backend resources take precedence
+        const localStaticResources = pluginConfig?.staticResources || {};
+        if (Object.keys(localStaticResources).length === 0) {
+            return ctx;
+        }
+        console.log('🛠️ Funnel: Merging local static resources:', localStaticResources);
+        const enriched = {
+            ...ctx,
+            static: {
+                ...localStaticResources,
+                ...(ctx.static || {})
+            }
+        };
+        console.log('🛠️ Funnel: Enriched context.static:', enriched.static);
+        return enriched;
+    }, [pluginConfig]);
     // Local state
     const [context, setContext] = useState(null);
     const [initializationAttempted, setInitializationAttempted] = useState(false);
     const [initializationError, setInitializationError] = useState(null);
+    // Track the last processed URL funnelId to avoid re-processing on context changes
+    const lastProcessedUrlFunnelIdRef = useRef(undefined);
+    // ✅ Track if initialization is currently in progress to prevent duplicate calls
+    const isInitializingRef = useRef(false);
+    // Check if we have an existing session in cookies (to avoid unnecessary re-initialization)
+    const hasExistingSessionCookie = useMemo(() => {
+        if (typeof document === 'undefined')
+            return false;
+        const funnelSessionCookie = document.cookie
+            .split('; ')
+            .find(row => row.startsWith('tgd-funnel-session-id='));
+        return !!funnelSessionCookie;
+    }, []); // Only check once on mount
     const currentStepId = options.currentStepId || context?.currentStepId;
-    // Check for URL parameter overrides
-    const urlParams = typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : new URLSearchParams();
-    const urlFunnelId = urlParams.get('funnelId') || undefined;
+    // Check for URL parameter overrides - recalculate on every render to detect URL changes
+    // This is cheap and ensures we always have the latest URL params
+    const [currentUrl, setCurrentUrl] = useState(() => typeof window !== 'undefined' ? window.location.href : '');
+    // Listen for URL changes (navigation)
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const updateUrl = () => {
+            setCurrentUrl(window.location.href);
+        };
+        // Listen for popstate (back/forward buttons) and pushState/replaceState
+        window.addEventListener('popstate', updateUrl);
+        // Also update on any navigation
+        const originalPushState = window.history.pushState;
+        const originalReplaceState = window.history.replaceState;
+        window.history.pushState = function (...args) {
+            originalPushState.apply(window.history, args);
+            updateUrl();
+        };
+        window.history.replaceState = function (...args) {
+            originalReplaceState.apply(window.history, args);
+            updateUrl();
+        };
+        return () => {
+            window.removeEventListener('popstate', updateUrl);
+            window.history.pushState = originalPushState;
+            window.history.replaceState = originalReplaceState;
+        };
+    }, []);
+    const urlFunnelId = useMemo(() => {
+        if (typeof window === 'undefined')
+            return undefined;
+        const params = new URLSearchParams(window.location.search);
+        return params.get('funnelId') || undefined;
+    }, [currentUrl]); // Re-compute when URL changes
     const effectiveFunnelId = urlFunnelId || options.funnelId;
     /**
      * Fetch debug data for the funnel debugger
@@ -63,19 +130,11 @@ export function useFunnel(options) {
         queryKey: funnelQueryKeys.session(context?.sessionId || ''),
         queryFn: async () => {
             if (!context?.sessionId) {
-                console.warn('🍪 Funnel: No session ID available for query');
                 return null;
             }
-            // ✅ Automatically include currentUrl for session sync on page load/refresh
-            const currentUrl = typeof window !== 'undefined' ? window.location.href : undefined;
-            console.log(`🍪 Funnel: Fetching session data for ID: ${context.sessionId}`);
-            if (currentUrl) {
-                console.log(`🍪 Funnel: Including current URL for sync: ${currentUrl}`);
-            }
-            const response = await funnelResource.getSession(context.sessionId, currentUrl);
-            console.log(`🍪 Funnel: Session fetch response:`, response);
+            const response = await funnelResource.getSession(context.sessionId);
             if (response.success && response.context) {
-                return response.context;
+                return enrichContext(response.context);
             }
             throw new Error(response.error || 'Failed to fetch session');
         },
@@ -87,11 +146,23 @@ export function useFunnel(options) {
     // Initialize session mutation
     const initializeMutation = useMutation({
         mutationFn: async (entryStepId) => {
+            // ✅ Prevent duplicate initialization calls
+            if (isInitializingRef.current) {
+                throw new Error('Initialization already in progress');
+            }
+            isInitializingRef.current = true;
             if (!auth.session?.customerId || !store?.id) {
+                isInitializingRef.current = false;
                 throw new Error('Authentication required for funnel session');
             }
+            // Get CURRENT URL params (not cached) to ensure we have latest values
+            const currentUrlParams = typeof window !== 'undefined'
+                ? new URLSearchParams(window.location.search)
+                : new URLSearchParams();
+            const currentUrlFunnelId = currentUrlParams.get('funnelId') || undefined;
+            const currentEffectiveFunnelId = currentUrlFunnelId || options.funnelId;
             // Check for existing session ID in URL parameters
-            let existingSessionId = urlParams.get('funnelSessionId') || undefined;
+            let existingSessionId = currentUrlParams.get('funnelSessionId') || undefined;
             if (existingSessionId) {
                 console.log(`🍪 Funnel: Found session ID in URL params: ${existingSessionId}`);
             }
@@ -102,11 +173,23 @@ export function useFunnel(options) {
                     .find(row => row.startsWith('tgd-funnel-session-id='));
                 existingSessionId = funnelSessionCookie ? funnelSessionCookie.split('=')[1] : undefined;
                 if (existingSessionId) {
-                    console.log(`🍪 Funnel: Found session in cookie: ${existingSessionId}`);
+                    console.log(`🍪 Funnel: Found existing session in cookie: ${existingSessionId}`);
                 }
             }
-            if (!existingSessionId) {
-                console.log(`🍪 Funnel: No existing session found in URL params or cookie`);
+            // Log initialization strategy
+            console.log(`🍪 Funnel: Initialize request:`);
+            console.log(`   - Existing session ID: ${existingSessionId || 'none'}`);
+            console.log(`   - URL funnelId: ${currentUrlFunnelId || 'none'}`);
+            console.log(`   - Hook funnelId: ${options.funnelId || 'none'}`);
+            console.log(`   - Effective funnelId to send: ${currentEffectiveFunnelId || 'none (will use existing or backend default)'}`);
+            if (existingSessionId && !currentEffectiveFunnelId) {
+                console.log(`   → Strategy: REUSE existing session from cookie`);
+            }
+            else if (existingSessionId && currentEffectiveFunnelId) {
+                console.log(`   → Strategy: VALIDATE existing session matches funnelId, or create new`);
+            }
+            else {
+                console.log(`   → Strategy: CREATE new session`);
             }
             // Send minimal CMS session data
             const cmsSessionData = {
@@ -115,40 +198,66 @@ export function useFunnel(options) {
                 sessionId: auth.session.sessionId,
                 accountId: auth.session.accountId
             };
+            // Get current URL for session synchronization
+            const currentUrl = typeof window !== 'undefined' ? window.location.href : undefined;
             // Call API to initialize session - backend will restore existing or create new
             const requestBody = {
                 cmsSession: cmsSessionData,
                 entryStepId, // Optional override
-                existingSessionId // Pass existing session ID from URL or cookie
+                existingSessionId, // Pass existing session ID from URL or cookie
+                currentUrl // Include current URL for step tracking
             };
             // Only include funnelId if it's provided (for backend fallback)
-            if (effectiveFunnelId) {
-                requestBody.funnelId = effectiveFunnelId;
+            if (currentEffectiveFunnelId) {
+                requestBody.funnelId = currentEffectiveFunnelId;
             }
+            console.log(`📤 Funnel: Sending initialize request to backend:`);
+            console.log(`   Request body:`, JSON.stringify({
+                ...requestBody,
+                cmsSession: { ...cmsSessionData, sessionId: `${cmsSessionData.sessionId.substring(0, 20)}...` }
+            }, null, 2));
             const response = await funnelResource.initialize(requestBody);
+            console.log(`📥 Funnel: Received response from backend:`);
+            console.log(`   Success: ${response.success}`);
+            if (response.context) {
+                console.log(`   Returned session ID: ${response.context.sessionId}`);
+                console.log(`   Returned funnel ID: ${response.context.funnelId}`);
+                console.log(`   Is same session? ${response.context.sessionId === existingSessionId ? '✅ YES (reused)' : '❌ NO (new session created)'}`);
+            }
+            if (response.error) {
+                console.log(`   Error: ${response.error}`);
+            }
             if (response.success && response.context) {
-                return response.context;
+                return enrichContext(response.context);
             }
             else {
                 throw new Error(response.error || 'Failed to initialize funnel session');
             }
         },
         onSuccess: (newContext) => {
-            setContext(newContext);
+            // ✅ Reset initialization flag
+            isInitializingRef.current = false;
+            // Context is already enriched by mutationFn return, but safe to ensure
+            const enrichedContext = enrichContext(newContext);
+            setContext(enrichedContext);
             setInitializationError(null);
             // Set session cookie for persistence across page reloads
-            setSessionCookie(newContext.sessionId);
-            console.log(`🍪 Funnel: Initialized session for funnel ${effectiveFunnelId || 'default'}`, newContext);
+            setSessionCookie(enrichedContext.sessionId);
+            console.log(`✅ Funnel: Session initialized/loaded successfully`);
+            console.log(`   - Session ID: ${enrichedContext.sessionId}`);
+            console.log(`   - Funnel ID: ${enrichedContext.funnelId}`);
+            console.log(`   - Current Step: ${enrichedContext.currentStepId}`);
             // Fetch debug data if in debug mode
             if (debugMode) {
-                void fetchFunnelDebugData(newContext.sessionId);
+                void fetchFunnelDebugData(enrichedContext.sessionId);
             }
-            // Invalidate session query to refetch with new session ID
-            void queryClient.invalidateQueries({
-                queryKey: funnelQueryKeys.session(newContext.sessionId)
-            });
+            // Set the session query data directly (no need to refetch since initialize already returns full context)
+            queryClient.setQueryData(funnelQueryKeys.session(enrichedContext.sessionId), enrichedContext);
+            console.log(`✅ Funnel: Session query data populated from initialize response (no additional request needed)`);
         },
         onError: (error) => {
+            // ✅ Reset initialization flag on error
+            isInitializingRef.current = false;
             const errorObj = error instanceof Error ? error : new Error(String(error));
             setInitializationError(errorObj);
             console.error('Error initializing funnel session:', error);
@@ -169,9 +278,7 @@ export function useFunnel(options) {
             // ✅ Automatically include currentUrl for URL-to-Step mapping
             // User can override by providing event.currentUrl explicitly
             const currentUrl = event.currentUrl || (typeof window !== 'undefined' ? window.location.href : undefined);
-            console.log(`🍪 Funnel: Navigating with session ID: ${context.sessionId}`);
             if (currentUrl) {
-                console.log(`🍪 Funnel: Current URL for sync: ${currentUrl}`);
             }
             const requestBody = {
                 sessionId: context.sessionId,
@@ -218,7 +325,8 @@ export function useFunnel(options) {
                     ...(recoveredSessionId ? { recovered: true, oldSessionId: context.sessionId } : {})
                 }
             };
-            setContext(newContext);
+            const enrichedContext = enrichContext(newContext);
+            setContext(enrichedContext);
             // Update cookie with new session ID if recovered
             if (recoveredSessionId) {
                 document.cookie = `funnelSessionId=${recoveredSessionId}; path=/; max-age=86400; SameSite=Lax`;
@@ -231,7 +339,7 @@ export function useFunnel(options) {
                     type: 'redirect', // Default action type
                     url: result.url
                 },
-                context: newContext,
+                context: enrichedContext,
                 tracking: result.tracking
             };
             // Handle navigation callback with override capability
@@ -245,19 +353,25 @@ export function useFunnel(options) {
             // Perform default navigation if not overridden
             if (shouldPerformDefaultNavigation && navigationResult.action.url) {
                 // Add URL parameters for cross-domain session continuity
-                const urlWithParams = addSessionParams(navigationResult.action.url, newContext.sessionId, effectiveFunnelId || options.funnelId);
+                const urlWithParams = addSessionParams(navigationResult.action.url, enrichedContext.sessionId, effectiveFunnelId || options.funnelId);
                 const updatedAction = { ...navigationResult.action, url: urlWithParams };
                 performNavigation(updatedAction);
             }
-            console.log(`🍪 Funnel: Navigated from ${context.currentStepId} to ${result.stepId}`);
-            // Fetch debug data if in debug mode
-            if (debugMode) {
-                void fetchFunnelDebugData(newContext.sessionId);
+            // Skip background refreshes if we are navigating away (full page reload)
+            // This prevents "lingering" requests from the old page context
+            const isFullNavigation = shouldPerformDefaultNavigation &&
+                navigationResult.action.url &&
+                (navigationResult.action.type === 'redirect' || navigationResult.action.type === 'replace');
+            if (!isFullNavigation) {
+                // Fetch debug data if in debug mode
+                if (debugMode) {
+                    void fetchFunnelDebugData(enrichedContext.sessionId);
+                }
+                // Invalidate and refetch session data
+                void queryClient.invalidateQueries({
+                    queryKey: funnelQueryKeys.session(enrichedContext.sessionId)
+                });
             }
-            // Invalidate and refetch session data
-            void queryClient.invalidateQueries({
-                queryKey: funnelQueryKeys.session(newContext.sessionId)
-            });
         },
         onError: (error) => {
             console.error('Funnel navigation error:', error);
@@ -291,7 +405,8 @@ export function useFunnel(options) {
                 ...updates,
                 lastActivityAt: Date.now()
             };
-            setContext(updatedContext);
+            const enrichedContext = enrichContext(updatedContext);
+            setContext(enrichedContext);
             console.log(`🍪 Funnel: Updated context for step ${context.currentStepId}`);
             // Invalidate session query
             void queryClient.invalidateQueries({
@@ -317,6 +432,8 @@ export function useFunnel(options) {
                 return;
             console.log(`🍪 Funnel: Ended session ${context.sessionId}`);
             setContext(null);
+            // Reset the processed URL funnelId ref to allow re-initialization
+            lastProcessedUrlFunnelIdRef.current = undefined;
             // Clear queries
             queryClient.removeQueries({
                 queryKey: funnelQueryKeys.session(context.sessionId)
@@ -342,14 +459,15 @@ export function useFunnel(options) {
      */
     const addSessionParams = useCallback((url, sessionId, funnelId) => {
         try {
-            const urlObj = new URL(url);
+            // Handle relative URLs by using current origin
+            const urlObj = url.startsWith('http')
+                ? new URL(url)
+                : new URL(url, window.location.origin);
             urlObj.searchParams.set('funnelSessionId', sessionId);
             if (funnelId) {
                 urlObj.searchParams.set('funnelId', funnelId);
             }
-            const urlWithParams = urlObj.toString();
-            console.log(`🍪 Funnel: Added session params to URL: ${url} → ${urlWithParams}`);
-            return urlWithParams;
+            return urlObj.toString();
         }
         catch (error) {
             console.warn('Failed to add session params to URL:', error);
@@ -370,33 +488,34 @@ export function useFunnel(options) {
         }
         switch (action.type) {
             case 'redirect':
-                console.log(`🍪 Funnel: Redirecting to ${targetUrl}`);
                 window.location.href = targetUrl;
                 break;
             case 'replace':
-                console.log(`🍪 Funnel: Replacing current page with ${targetUrl}`);
                 window.location.replace(targetUrl);
                 break;
             case 'push':
-                console.log(`🍪 Funnel: Pushing to history: ${targetUrl}`);
                 window.history.pushState({}, '', targetUrl);
                 // Trigger a popstate event to update React Router
                 window.dispatchEvent(new PopStateEvent('popstate'));
                 break;
             case 'external':
-                console.log(`🍪 Funnel: Opening external URL: ${targetUrl}`);
                 window.open(targetUrl, '_blank');
                 break;
             case 'none':
-                console.log(`🍪 Funnel: No navigation action required`);
+                // No navigation needed
                 break;
             default:
-                console.warn(`🍪 Funnel: Unknown navigation action type: ${action.type}`);
+                console.warn(`Unknown navigation action type: ${action.type}`);
                 break;
         }
     }, []);
     // Public API methods
     const initializeSession = useCallback(async (entryStepId) => {
+        // ✅ Check ref before even starting (prevents React StrictMode double-invocation)
+        if (isInitializingRef.current) {
+            console.log('⏭️  Funnel: initializeSession called but already initializing');
+            return;
+        }
         setInitializationAttempted(true);
         await initializeMutation.mutateAsync(entryStepId);
     }, [initializeMutation]);
@@ -421,29 +540,84 @@ export function useFunnel(options) {
         setInitializationError(null);
         await initializeSession();
     }, [initializeSession]);
-    // Auto-initialize if requested and not already initialized
+    /**
+     * Auto-initialization effect
+     *
+     * Handles funnel session initialization with the following logic:
+     * 1. If no session exists => Initialize with URL funnelId or hook funnelId or backend default
+     * 2. If session exists + explicit funnelId provided that differs => Reset and create new
+     * 3. If session exists + no funnelId provided => Keep existing session
+     *
+     * IMPORTANT: Only resets session if an EXPLICIT funnelId is provided that differs
+     * from the current session. If no funnelId is provided, keeps the existing session.
+     *
+     * Priority: URL funnelId > Hook funnelId > Existing session funnelId > Backend default
+     */
     useEffect(() => {
-        if (options.autoInitialize &&
-            !context &&
-            !initializationAttempted &&
-            !initializationError &&
-            auth.session?.customerId &&
-            store?.id &&
-            !initializeMutation.isPending) {
-            console.log('🍪 Funnel: Auto-initializing session...');
+        // Skip if auto-initialize is disabled
+        const autoInit = options.autoInitialize ?? true; // Default to true
+        if (!autoInit) {
+            return;
+        }
+        // Skip if required dependencies are not available
+        if (!auth.session?.customerId || !store?.id) {
+            return;
+        }
+        // Skip if already initializing (check both mutation state and ref)
+        if (initializeMutation.isPending || isInitializingRef.current) {
+            return;
+        }
+        // Determine if we have an explicit funnelId request (URL has priority)
+        const explicitFunnelId = urlFunnelId || options.funnelId;
+        // Case 1: No session exists yet - need to initialize
+        if (!context) {
+            // Check if we've already attempted initialization
+            if (!initializationAttempted) {
+                setInitializationAttempted(true);
+                initializeSession().catch(error => {
+                    console.error('❌ Funnel: Auto-initialization failed:', error);
+                });
+            }
+            return;
+        }
+        // Case 2: Session exists - check if we need to reset it
+        // ONLY reset if an explicit funnelId is provided AND it differs from current session
+        if (explicitFunnelId && context.funnelId && explicitFunnelId !== context.funnelId) {
+            // Check if we've already processed this funnelId to prevent loops
+            if (lastProcessedUrlFunnelIdRef.current === explicitFunnelId) {
+                return;
+            }
+            console.log(`🔄 Funnel: Switching from funnel ${context.funnelId} to ${explicitFunnelId}`);
+            // Mark this funnelId as processed
+            lastProcessedUrlFunnelIdRef.current = explicitFunnelId;
+            // Clear existing session
+            setContext(null);
+            setInitializationAttempted(false);
+            setInitializationError(null);
+            // Clear session cookie
+            document.cookie = 'tgd-funnel-session-id=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=Lax';
+            // Clear queries for old session
+            queryClient.removeQueries({
+                queryKey: funnelQueryKeys.session(context.sessionId)
+            });
+            // Initialize new session with correct funnelId
             initializeSession().catch(error => {
-                console.error('Auto-initialization failed - will not retry:', error);
+                console.error('❌ Funnel: Failed to reset session:', error);
             });
         }
     }, [
         options.autoInitialize,
-        context,
+        options.funnelId,
+        urlFunnelId,
+        context?.funnelId,
+        context?.sessionId,
         initializationAttempted,
-        initializationError,
         auth.session?.customerId,
         store?.id,
         initializeMutation.isPending,
-        initializeSession
+        initializeSession,
+        hasExistingSessionCookie,
+        queryClient
     ]);
     // Sync session data from query to local state
     useEffect(() => {
@@ -453,6 +627,7 @@ export function useFunnel(options) {
     }, [sessionData, context]);
     const isLoading = initializeMutation.isPending || navigateMutation.isPending || updateContextMutation.isPending;
     const isInitialized = !!context;
+    const isNavigating = navigateMutation.isPending; // Explicit navigation state
     return {
         next,
         goToStep,
@@ -463,6 +638,7 @@ export function useFunnel(options) {
         context,
         isLoading,
         isInitialized,
+        isNavigating, // Expose isNavigating
         initializeSession,
         endSession,
         retryInitialization,

package/dist/v2/react/hooks/useGoogleAutocomplete.js

@@ -15,6 +15,7 @@ export function useGoogleAutocomplete(options) {
     const autocompleteServiceRef = useRef(null);
     const placesServiceRef = useRef(null);
     const scriptLoadedRef = useRef(false);
+    const debounceTimeoutRef = useRef(null);
     // Inject Google Maps script
     useEffect(() => {
         if (!apiKey) {
@@ -97,25 +98,32 @@ export function useGoogleAutocomplete(options) {
             setPredictions([]);
             return;
         }
-        setIsLoading(true);
-        const request = {
-            input,
-            ...(countryRestriction && {
-                componentRestrictions: { country: countryRestriction.toLowerCase() },
-            }),
-        };
-        autocompleteServiceRef.current.getPlacePredictions(request, (results, status) => {
-            setIsLoading(false);
-            if (status === window.google.maps.places.PlacesServiceStatus.OK && results) {
-                setPredictions(results);
-            }
-            else {
-                setPredictions([]);
-                if (status !== window.google.maps.places.PlacesServiceStatus.ZERO_RESULTS) {
-                    // Prediction failed but not zero results
+        // Clear existing timeout
+        if (debounceTimeoutRef.current) {
+            clearTimeout(debounceTimeoutRef.current);
+        }
+        // Set new timeout
+        debounceTimeoutRef.current = setTimeout(() => {
+            setIsLoading(true);
+            const request = {
+                input,
+                ...(countryRestriction && {
+                    componentRestrictions: { country: countryRestriction.toLowerCase() },
+                }),
+            };
+            autocompleteServiceRef.current.getPlacePredictions(request, (results, status) => {
+                setIsLoading(false);
+                if (status === window.google.maps.places.PlacesServiceStatus.OK && results) {
+                    setPredictions(results);
                 }
-            }
-        });
+                else {
+                    setPredictions([]);
+                    if (status !== window.google.maps.places.PlacesServiceStatus.ZERO_RESULTS) {
+                        // Prediction failed but not zero results
+                    }
+                }
+            });
+        }, 300); // 300ms debounce
     }, [initializeServices, isScriptLoaded]);
     // Get detailed place information
     const getPlaceDetails = useCallback((placeId) => {