@tagadapay/plugin-sdk 2.6.11 → 2.6.13

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

@@ -0,0 +1,432 @@
+/**
+ * useFunnel Hook (v2) - TanStack Query-based funnel navigation
+ *
+ * Modern implementation using TanStack Query for state management
+ * and the v2 ApiClient for API calls.
+ */
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useTagadaContext } from '../providers/TagadaProvider';
+import { FunnelResource } from '../../core/resources/funnel';
+import { getGlobalApiClient } from './useApiQuery';
+// Query keys for funnel operations
+const funnelQueryKeys = {
+    session: (sessionId) => ['funnel', 'session', sessionId],
+    context: (sessionId) => ['funnel', 'context', sessionId],
+};
+/**
+ * React Hook for Funnel Navigation (Plugin SDK v2)
+ *
+ * Modern funnel navigation using TanStack Query for state management
+ * and the v2 ApiClient architecture.
+ */
+export function useFunnel(options) {
+    const { auth, store } = useTagadaContext();
+    const queryClient = useQueryClient();
+    const apiClient = getGlobalApiClient();
+    const funnelResource = useMemo(() => new FunnelResource(apiClient), [apiClient]);
+    // Local state
+    const [context, setContext] = useState(null);
+    const [initializationAttempted, setInitializationAttempted] = useState(false);
+    const [initializationError, setInitializationError] = useState(null);
+    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;
+    const effectiveFunnelId = urlFunnelId || options.funnelId;
+    // Session query - only enabled when we have a session ID
+    const { data: sessionData, isLoading: isSessionLoading, error: sessionError, refetch: refetchSession } = useQuery({
+        queryKey: funnelQueryKeys.session(context?.sessionId || ''),
+        queryFn: async () => {
+            if (!context?.sessionId) {
+                console.warn('🍪 Funnel: No session ID available for query');
+                return null;
+            }
+            console.log(`🍪 Funnel: Fetching session data for ID: ${context.sessionId}`);
+            const response = await funnelResource.getSession(context.sessionId);
+            console.log(`🍪 Funnel: Session fetch response:`, response);
+            if (response.success && response.context) {
+                return response.context;
+            }
+            throw new Error(response.error || 'Failed to fetch session');
+        },
+        enabled: !!context?.sessionId && (options.enabled !== false),
+        staleTime: 30000, // 30 seconds
+        gcTime: 5 * 60 * 1000, // 5 minutes
+        refetchOnWindowFocus: false,
+    });
+    // Initialize session mutation
+    const initializeMutation = useMutation({
+        mutationFn: async (entryStepId) => {
+            if (!auth.session?.customerId || !store?.id) {
+                throw new Error('Authentication required for funnel session');
+            }
+            // Check for existing session ID in URL parameters
+            let existingSessionId = urlParams.get('funnelSessionId') || undefined;
+            if (existingSessionId) {
+                console.log(`🍪 Funnel: Found session ID in URL params: ${existingSessionId}`);
+            }
+            else {
+                // Fallback to cookie for same-domain scenarios
+                const funnelSessionCookie = document.cookie
+                    .split('; ')
+                    .find(row => row.startsWith('tgd-funnel-session-id='));
+                existingSessionId = funnelSessionCookie ? funnelSessionCookie.split('=')[1] : undefined;
+                if (existingSessionId) {
+                    console.log(`🍪 Funnel: Found session in cookie: ${existingSessionId}`);
+                }
+            }
+            if (!existingSessionId) {
+                console.log(`🍪 Funnel: No existing session found in URL params or cookie`);
+            }
+            // Send minimal CMS session data
+            const cmsSessionData = {
+                customerId: auth.session.customerId,
+                storeId: store.id,
+                sessionId: auth.session.sessionId,
+                accountId: auth.session.accountId
+            };
+            // 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
+            };
+            // Only include funnelId if it's provided (for backend fallback)
+            if (effectiveFunnelId) {
+                requestBody.funnelId = effectiveFunnelId;
+            }
+            const response = await funnelResource.initialize(requestBody);
+            if (response.success && response.context) {
+                return response.context;
+            }
+            else {
+                throw new Error(response.error || 'Failed to initialize funnel session');
+            }
+        },
+        onSuccess: (newContext) => {
+            setContext(newContext);
+            setInitializationError(null);
+            // Set session cookie for persistence across page reloads
+            setSessionCookie(newContext.sessionId);
+            console.log(`🍪 Funnel: Initialized session for funnel ${effectiveFunnelId || 'default'}`, newContext);
+            // Invalidate session query to refetch with new session ID
+            void queryClient.invalidateQueries({
+                queryKey: funnelQueryKeys.session(newContext.sessionId)
+            });
+        },
+        onError: (error) => {
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            setInitializationError(errorObj);
+            console.error('Error initializing funnel session:', error);
+            if (options.onError) {
+                options.onError(errorObj);
+            }
+        }
+    });
+    // Navigate mutation
+    const navigateMutation = useMutation({
+        mutationFn: async (event) => {
+            if (!context) {
+                throw new Error('Funnel session not initialized');
+            }
+            if (!context.sessionId) {
+                throw new Error('Funnel session ID missing - session may be corrupted');
+            }
+            console.log(`🍪 Funnel: Navigating with session ID: ${context.sessionId}`);
+            const requestBody = {
+                sessionId: context.sessionId,
+                event: {
+                    type: event.type,
+                    data: event.data,
+                    timestamp: event.timestamp || new Date().toISOString()
+                },
+                contextUpdates: {
+                    lastActivityAt: Date.now()
+                }
+            };
+            const response = await funnelResource.navigate(requestBody);
+            if (response.success && response.result) {
+                return response.result;
+            }
+            else {
+                throw new Error(response.error || 'Navigation failed');
+            }
+        },
+        onSuccess: (result) => {
+            if (!context)
+                return;
+            // Update local context
+            const newContext = {
+                ...context,
+                currentStepId: result.stepId,
+                previousStepId: context.currentStepId,
+                lastActivityAt: Date.now(),
+                metadata: {
+                    ...context.metadata,
+                    lastEvent: 'navigation',
+                    lastTransition: new Date().toISOString()
+                }
+            };
+            setContext(newContext);
+            // Create typed navigation result
+            const navigationResult = {
+                stepId: result.stepId,
+                action: {
+                    type: 'redirect', // Default action type
+                    url: result.url
+                },
+                context: newContext,
+                tracking: result.tracking
+            };
+            // Handle navigation callback with override capability
+            let shouldPerformDefaultNavigation = true;
+            if (options.onNavigate) {
+                const callbackResult = options.onNavigate(navigationResult);
+                if (callbackResult === false) {
+                    shouldPerformDefaultNavigation = false;
+                }
+            }
+            // 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 updatedAction = { ...navigationResult.action, url: urlWithParams };
+                performNavigation(updatedAction);
+            }
+            console.log(`🍪 Funnel: Navigated from ${context.currentStepId} to ${result.stepId}`);
+            // Invalidate and refetch session data
+            void queryClient.invalidateQueries({
+                queryKey: funnelQueryKeys.session(newContext.sessionId)
+            });
+        },
+        onError: (error) => {
+            console.error('Funnel navigation error:', error);
+            if (options.onError) {
+                options.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    });
+    // Update context mutation
+    const updateContextMutation = useMutation({
+        mutationFn: async (updates) => {
+            if (!context) {
+                throw new Error('Funnel session not initialized');
+            }
+            const requestBody = {
+                contextUpdates: updates
+            };
+            const response = await funnelResource.updateContext(context.sessionId, requestBody);
+            if (response.success) {
+                return updates;
+            }
+            else {
+                throw new Error(response.error || 'Context update failed');
+            }
+        },
+        onSuccess: (updates) => {
+            if (!context)
+                return;
+            const updatedContext = {
+                ...context,
+                ...updates,
+                lastActivityAt: Date.now()
+            };
+            setContext(updatedContext);
+            console.log(`🍪 Funnel: Updated context for step ${context.currentStepId}`);
+            // Invalidate session query
+            void queryClient.invalidateQueries({
+                queryKey: funnelQueryKeys.session(context.sessionId)
+            });
+        },
+        onError: (error) => {
+            console.error('Error updating funnel context:', error);
+            if (options.onError) {
+                options.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    });
+    // End session mutation
+    const endSessionMutation = useMutation({
+        mutationFn: async () => {
+            if (!context)
+                return;
+            await funnelResource.endSession(context.sessionId);
+        },
+        onSuccess: () => {
+            if (!context)
+                return;
+            console.log(`🍪 Funnel: Ended session ${context.sessionId}`);
+            setContext(null);
+            // Clear queries
+            queryClient.removeQueries({
+                queryKey: funnelQueryKeys.session(context.sessionId)
+            });
+        },
+        onError: (error) => {
+            console.error('Error ending funnel session:', error);
+            // Don't throw here - session ending is best effort
+        }
+    });
+    /**
+     * Set funnel session cookie
+     */
+    const setSessionCookie = useCallback((sessionId) => {
+        const maxAge = 24 * 60 * 60; // 24 hours
+        const expires = new Date(Date.now() + maxAge * 1000).toUTCString();
+        // Set cookie for same-domain scenarios
+        document.cookie = `tgd-funnel-session-id=${sessionId}; path=/; expires=${expires}; SameSite=Lax`;
+        console.log(`🍪 Funnel: Set session cookie: ${sessionId}`);
+    }, []);
+    /**
+     * Add session parameters to URL for cross-domain continuity
+     */
+    const addSessionParams = useCallback((url, sessionId, funnelId) => {
+        try {
+            const urlObj = new URL(url);
+            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;
+        }
+        catch (error) {
+            console.warn('Failed to add session params to URL:', error);
+            return url; // Return original URL if parsing fails
+        }
+    }, []);
+    /**
+     * Perform navigation based on action type
+     */
+    const performNavigation = useCallback((action) => {
+        if (!action.url)
+            return;
+        // Handle relative URLs by making them absolute
+        let targetUrl = action.url;
+        if (targetUrl.startsWith('/') && !targetUrl.startsWith('//')) {
+            // Relative URL - use current origin
+            targetUrl = window.location.origin + targetUrl;
+        }
+        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`);
+                break;
+            default:
+                console.warn(`🍪 Funnel: Unknown navigation action type: ${action.type}`);
+                break;
+        }
+    }, []);
+    // Public API methods
+    const initializeSession = useCallback(async (entryStepId) => {
+        setInitializationAttempted(true);
+        await initializeMutation.mutateAsync(entryStepId);
+    }, [initializeMutation]);
+    const next = useCallback(async (event) => {
+        return navigateMutation.mutateAsync(event);
+    }, [navigateMutation]);
+    const goToStep = useCallback(async (stepId) => {
+        return next({
+            type: 'direct_navigation',
+            data: { targetStepId: stepId },
+            timestamp: new Date().toISOString()
+        });
+    }, [next]);
+    const updateContext = useCallback(async (updates) => {
+        await updateContextMutation.mutateAsync(updates);
+    }, [updateContextMutation]);
+    const endSession = useCallback(async () => {
+        await endSessionMutation.mutateAsync();
+    }, [endSessionMutation]);
+    const retryInitialization = useCallback(async () => {
+        setInitializationAttempted(false);
+        setInitializationError(null);
+        await initializeSession();
+    }, [initializeSession]);
+    // Auto-initialize if requested and not already initialized
+    useEffect(() => {
+        if (options.autoInitialize &&
+            !context &&
+            !initializationAttempted &&
+            !initializationError &&
+            auth.session?.customerId &&
+            store?.id &&
+            !initializeMutation.isPending) {
+            console.log('🍪 Funnel: Auto-initializing session...');
+            initializeSession().catch(error => {
+                console.error('Auto-initialization failed - will not retry:', error);
+            });
+        }
+    }, [
+        options.autoInitialize,
+        context,
+        initializationAttempted,
+        initializationError,
+        auth.session?.customerId,
+        store?.id,
+        initializeMutation.isPending,
+        initializeSession
+    ]);
+    // Sync session data from query to local state
+    useEffect(() => {
+        if (sessionData && sessionData !== context) {
+            setContext(sessionData);
+        }
+    }, [sessionData, context]);
+    const isLoading = initializeMutation.isPending || navigateMutation.isPending || updateContextMutation.isPending;
+    const isInitialized = !!context;
+    return {
+        next,
+        goToStep,
+        updateContext,
+        currentStep: {
+            id: currentStepId || 'unknown'
+        },
+        context,
+        isLoading,
+        isInitialized,
+        initializeSession,
+        endSession,
+        retryInitialization,
+        initializationError,
+        isSessionLoading,
+        sessionError,
+        refetch: () => void refetchSession()
+    };
+}
+/**
+ * Simplified funnel hook for basic step tracking (v2)
+ */
+export function useSimpleFunnel(funnelId, initialStepId) {
+    const funnel = useFunnel({
+        funnelId,
+        currentStepId: initialStepId,
+        autoInitialize: true
+    });
+    return {
+        currentStepId: funnel.currentStep.id,
+        next: funnel.next,
+        goToStep: funnel.goToStep,
+        isLoading: funnel.isLoading,
+        context: funnel.context
+    };
+}

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

@@ -2,8 +2,8 @@
  * Order Hook using TanStack Query
  * Handles order creation and management with automatic caching
  */
+import { useMutation, useQuery } from '@tanstack/react-query';
 import { useMemo } from 'react';
-import { useQuery, useMutation } from '@tanstack/react-query';
 import { OrdersResource } from '../../core/resources/orders';
 import { getGlobalApiClient } from './useApiQuery';
 export function useOrderQuery(options = {}) {

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

@@ -2,7 +2,7 @@
  * Post Purchases Hook using TanStack Query
  * Handles post-purchase offers with automatic caching
  */
-import { PostPurchaseOffer, PostPurchaseOfferItem, PostPurchaseOfferSummary, CheckoutSessionState, OrderSummary, CurrencyOptions } from '../../core/resources/postPurchases';
+import { CheckoutSessionState, CurrencyOptions, OrderSummary, PostPurchaseOffer, PostPurchaseOfferItem, PostPurchaseOfferSummary } from '../../core/resources/postPurchases';
 export interface UsePostPurchasesQueryOptions {
     orderId: string;
     enabled?: boolean;

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

@@ -2,8 +2,8 @@
  * Post Purchases Hook using TanStack Query
  * Handles post-purchase offers with automatic caching
  */
-import { useMemo, useEffect, useState, useCallback } from 'react';
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { PostPurchasesResource } from '../../core/resources/postPurchases';
 import { useTagadaContext } from '../providers/TagadaProvider';
 import { getGlobalApiClient } from './useApiQuery';

package/dist/v2/react/index.d.ts

@@ -28,6 +28,7 @@ export { useStoreConfigQuery as useStoreConfig } from './hooks/useStoreConfigQue
 export { useThreeds } from './hooks/useThreeds';
 export { useThreedsModal } from './hooks/useThreedsModal';
 export { useVipOffersQuery as useVipOffers } from './hooks/useVipOffersQuery';
+export { useFunnel, useSimpleFunnel } from './hooks/useFunnel';
 export type { UseCheckoutTokenOptions, UseCheckoutTokenResult } from './hooks/useCheckoutToken';
 export type { ExpressPaymentMethodsContextType, ExpressPaymentMethodsProviderProps } from './hooks/useExpressPaymentMethods';
 export type { ApplePayButtonProps } from './components/ApplePayButton';
@@ -49,5 +50,6 @@ export type { UseShippingRatesQueryOptions as UseShippingRatesOptions, UseShippi
 export type { UseStoreConfigQueryOptions as UseStoreConfigOptions, UseStoreConfigQueryResult as UseStoreConfigResult } from './hooks/useStoreConfigQuery';
 export type { PaymentInstrument, ThreedsChallenge, ThreedsHook, ThreedsOptions, ThreedsProvider, ThreedsSession } from './hooks/useThreeds';
 export type { UseVipOffersQueryOptions as UseVipOffersOptions, UseVipOffersQueryResult as UseVipOffersResult } from './hooks/useVipOffersQuery';
+export type { UseFunnelOptions, UseFunnelResult, FunnelEvent, FunnelNavigationAction, FunnelNavigationResult, SimpleFunnelContext } from './hooks/useFunnel';
 export { formatMoney } from '../../react/utils/money';
 export type OrderItem = import('../core/utils/order').OrderLineItem;

package/dist/v2/react/index.js

@@ -32,5 +32,7 @@ export { useStoreConfigQuery as useStoreConfig } from './hooks/useStoreConfigQue
 export { useThreeds } from './hooks/useThreeds';
 export { useThreedsModal } from './hooks/useThreedsModal';
 export { useVipOffersQuery as useVipOffers } from './hooks/useVipOffersQuery';
+// Funnel hooks
+export { useFunnel, useSimpleFunnel } from './hooks/useFunnel';
 // Re-export utilities from main react
 export { formatMoney } from '../../react/utils/money';

package/dist/v2/react/providers/TagadaProvider.js

@@ -41,11 +41,11 @@ const InitializationLoader = () => (_jsxs("div", { style: {
                 borderTop: '1.5px solid #9ca3af',
                 borderRadius: '50%',
                 animation: 'tagada-spin 1s linear infinite',
-            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
-        @keyframes tagada-spin {
-          0% { transform: rotate(0deg); }
-          100% { transform: rotate(360deg); }
-        }
+            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
+        @keyframes tagada-spin {
+          0% { transform: rotate(0deg); }
+          100% { transform: rotate(360deg); }
+        }
       ` })] }));
 const TagadaContext = createContext(null);
 // Global instance tracking for TagadaProvider