@tagadapay/plugin-sdk 2.8.7 → 2.8.9

package/dist/v2/index.d.ts

@@ -23,9 +23,10 @@ export type { ToggleOrderBumpResponse, VipOffer, VipPreviewResponse } from './co
 export type { StoreConfig } from './core/resources/storeConfig';
 export { FunnelActionType } from './core/resources/funnel';
 export type { BackNavigationActionData, CartUpdatedActionData, DirectNavigationActionData, FormSubmitActionData, FunnelContextUpdateRequest, FunnelContextUpdateResponse, FunnelAction as FunnelEvent, FunnelInitializeRequest, FunnelInitializeResponse, FunnelNavigateRequest, FunnelNavigateResponse, FunnelNavigationAction, FunnelNavigationResult, NextAction, OfferAcceptedActionData, OfferDeclinedActionData, PaymentFailedActionData, PaymentSuccessActionData, 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 { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCredits, 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 type { TranslateFunction, TranslationText, UseTranslationOptions, UseTranslationResult } from './react/hooks/useTranslation';
 export type { ClubOffer, ClubOfferItem, ClubOfferLineItem, ClubOfferSummary, UseClubOffersOptions, UseClubOffersResult } from './react/hooks/useClubOffers';
+export type { UseCreditsOptions, UseCreditsResult } from './react/hooks/useCredits';
 export type { UseLoginOptions, UseLoginResult } from './react/hooks/useLogin';
 export type { CustomerAddress, CustomerInfos, CustomerOrderSummary, OrderWithRelations, Subscription, SubscriptionsResponse } from './core/resources/customer';
 export type { UseCustomerResult } from './react/hooks/useCustomer';

package/dist/v2/index.js

@@ -15,4 +15,4 @@ export * from './core/utils/products';
 export * from './core/pathRemapping';
 export { FunnelActionType } 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, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCredits, 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';

package/dist/v2/react/components/DebugDrawer.js

@@ -582,7 +582,96 @@ export const DebugDrawer = ({ isOpen, onClose }) => {
                                                                                     color: isCurrent ? '#d1fae5' : '#9ca3af',
                                                                                     marginLeft: '8px',
                                                                                 }, children: ["\u2022 ", cond.type, " \u2192 ", cond.nextStepId] }, condIdx)))] }))] }, step.id));
-                                                        }) })] })), _jsxs("div", { style: { marginTop: '12px' }, children: [_jsx("h4", { style: { margin: '0 0 8px 0', color: '#60a5fa', fontSize: '13px' }, children: "\uD83D\uDD0D Raw Data" }), _jsx("div", { style: { fontSize: '11px' }, children: _jsx(TreeView, { data: context.debugFunnel.data, name: "funnelData" }) })] })] })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No funnel hook active" }))] })), activeTab === 'checkout' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Checkout Debug" }), context.debugCheckout.isActive ? (_jsxs("div", { children: [_jsxs("div", { style: { marginBottom: '20px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Status" }), _jsxs("div", { style: { display: 'grid', gap: '8px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Hook Active:" }), _jsx("span", { style: { color: '#10b981' }, children: "\u2705 Yes" })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Loading:" }), _jsx("span", { style: { color: context.debugCheckout.isLoading ? '#f59e0b' : '#10b981' }, children: context.debugCheckout.isLoading ? '⏳ Yes' : '✅ No' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Has Error:" }), _jsx("span", { style: { color: context.debugCheckout.error ? '#ef4444' : '#10b981' }, children: context.debugCheckout.error ? '❌ Yes' : '✅ No' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Last Updated:" }), _jsx("span", { style: { color: '#9ca3af', fontSize: '12px' }, children: context.debugCheckout.lastUpdated?.toLocaleTimeString() || 'Never' })] })] })] }), context.debugCheckout.error && (_jsxs("div", { style: { marginBottom: '20px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#ef4444' }, children: "Error Details" }), _jsxs("div", { style: {
+                                                        }) })] })), context.debugFunnel.data?.session && (_jsxs("div", { style: { marginBottom: '16px' }, children: [_jsx("h4", { style: { margin: '0 0 8px 0', color: '#60a5fa', fontSize: '13px' }, children: "\uD83D\uDCE6 Resources & Context" }), context.debugFunnel.data.session.resources &&
+                                                        Object.keys(context.debugFunnel.data.session.resources).length > 0 && (_jsxs("div", { style: { marginBottom: '12px' }, children: [_jsxs("div", { style: {
+                                                                    fontSize: '11px',
+                                                                    color: '#10b981',
+                                                                    fontWeight: 'bold',
+                                                                    marginBottom: '6px',
+                                                                }, children: ["\uD83C\uDFAF Available Resources (", Object.keys(context.debugFunnel.data.session.resources).length, ")"] }), _jsx("div", { style: { display: 'grid', gap: '8px' }, children: Object.entries(context.debugFunnel.data.session.resources).map(([key, value]) => {
+                                                                    // Skip undefined/null resources
+                                                                    if (value === undefined || value === null)
+                                                                        return null;
+                                                                    // Check if it's an array or single resource
+                                                                    const isArray = Array.isArray(value);
+                                                                    const resourceCount = isArray ? value.length : 1;
+                                                                    return (_jsxs("div", { style: {
+                                                                            border: '1px solid #374151',
+                                                                            borderRadius: '6px',
+                                                                            padding: '10px',
+                                                                            backgroundColor: '#111827',
+                                                                        }, children: [_jsxs("div", { style: {
+                                                                                    display: 'flex',
+                                                                                    justifyContent: 'space-between',
+                                                                                    alignItems: 'center',
+                                                                                    marginBottom: '8px',
+                                                                                }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '6px' }, children: [_jsx("span", { style: { color: '#10b981', fontSize: '14px' }, children: key === 'order' || key === 'mainOrder'
+                                                                                                    ? '🛒'
+                                                                                                    : key === 'customer'
+                                                                                                        ? '👤'
+                                                                                                        : key === 'checkout'
+                                                                                                            ? '💳'
+                                                                                                            : key === 'offer'
+                                                                                                                ? '🎁'
+                                                                                                                : key === 'subscription'
+                                                                                                                    ? '🔄'
+                                                                                                                    : '📄' }), _jsx("span", { style: {
+                                                                                                    color: '#f9fafb',
+                                                                                                    fontWeight: 'bold',
+                                                                                                    fontSize: '12px',
+                                                                                                }, children: key }), isArray && (_jsxs("span", { style: {
+                                                                                                    fontSize: '10px',
+                                                                                                    backgroundColor: '#3b82f6',
+                                                                                                    color: '#fff',
+                                                                                                    padding: '2px 6px',
+                                                                                                    borderRadius: '3px',
+                                                                                                }, children: [resourceCount, " items"] }))] }), !isArray && value && typeof value === 'object' && (_jsx("div", { style: { fontSize: '10px', color: '#9ca3af' }, children: value.id && (_jsx("span", { style: { fontFamily: 'monospace' }, children: value.id })) }))] }), !isArray && value && typeof value === 'object' && (_jsxs("div", { style: {
+                                                                                    display: 'grid',
+                                                                                    gridTemplateColumns: '1fr 1fr',
+                                                                                    gap: '6px',
+                                                                                    fontSize: '11px',
+                                                                                    marginBottom: '8px',
+                                                                                }, children: [value.amount !== undefined && (_jsxs("div", { children: [_jsx("span", { style: { color: '#6b7280' }, children: "Amount: " }), _jsx("span", { style: { color: '#10b981', fontWeight: 'bold' }, children: (() => {
+                                                                                                    try {
+                                                                                                        return context.money.formatMoney(Number(value.amount) || 0, String(value.currency) || 'USD', context.locale.locale);
+                                                                                                    }
+                                                                                                    catch {
+                                                                                                        return `${value.amount} ${value.currency || ''}`;
+                                                                                                    }
+                                                                                                })() })] })), value.email !== undefined && (_jsxs("div", { children: [_jsx("span", { style: { color: '#6b7280' }, children: "Email: " }), _jsx("span", { style: { color: '#60a5fa' }, children: value.email })] })), value.status !== undefined && (_jsxs("div", { children: [_jsx("span", { style: { color: '#6b7280' }, children: "Status: " }), _jsx("span", { style: { color: '#f59e0b' }, children: value.status })] })), value.currency !== undefined && (_jsxs("div", { children: [_jsx("span", { style: { color: '#6b7280' }, children: "Currency: " }), _jsx("span", { style: { color: '#8b5cf6' }, children: value.currency })] }))] })), _jsxs("details", { style: { marginTop: '6px' }, children: [_jsx("summary", { style: {
+                                                                                            cursor: 'pointer',
+                                                                                            fontSize: '10px',
+                                                                                            color: '#60a5fa',
+                                                                                            fontWeight: 'bold',
+                                                                                        }, children: "Show Full Data" }), _jsx("div", { style: { marginTop: '6px', fontSize: '10px' }, children: _jsx(TreeView, { data: value, name: key, maxLevel: 3 }) })] })] }, key));
+                                                                }) })] })), context.debugFunnel.data.session.metadata &&
+                                                        Object.keys(context.debugFunnel.data.session.metadata).length > 0 && (_jsxs("div", { style: { marginBottom: '12px' }, children: [_jsxs("div", { style: {
+                                                                    fontSize: '11px',
+                                                                    color: '#8b5cf6',
+                                                                    fontWeight: 'bold',
+                                                                    marginBottom: '6px',
+                                                                }, children: ["\uD83D\uDCDD Session Metadata (", Object.keys(context.debugFunnel.data.session.metadata).length, ")"] }), _jsx("div", { style: {
+                                                                    border: '1px solid #374151',
+                                                                    borderRadius: '6px',
+                                                                    padding: '10px',
+                                                                    backgroundColor: '#111827',
+                                                                }, children: _jsx(TreeView, { data: context.debugFunnel.data.session.metadata, name: "metadata", maxLevel: 2 }) })] })), _jsxs("div", { style: { marginBottom: '12px' }, children: [_jsx("div", { style: {
+                                                                    fontSize: '11px',
+                                                                    color: '#f59e0b',
+                                                                    fontWeight: 'bold',
+                                                                    marginBottom: '6px',
+                                                                }, children: "\u2139\uFE0F Session Context" }), _jsx("div", { style: {
+                                                                    border: '1px solid #374151',
+                                                                    borderRadius: '6px',
+                                                                    padding: '10px',
+                                                                    backgroundColor: '#111827',
+                                                                }, children: _jsxs("div", { style: { display: 'grid', gap: '6px', fontSize: '11px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { style: { color: '#6b7280' }, children: "Customer ID:" }), _jsx("span", { style: { color: '#60a5fa', fontFamily: 'monospace', fontSize: '10px' }, children: context.debugFunnel.data.session.customerId })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { style: { color: '#6b7280' }, children: "Store ID:" }), _jsx("span", { style: { color: '#60a5fa', fontFamily: 'monospace', fontSize: '10px' }, children: context.debugFunnel.data.session.storeId })] }), context.debugFunnel.data.session.environment && (_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { style: { color: '#6b7280' }, children: "Environment:" }), _jsx("span", { style: { color: '#10b981' }, children: context.debugFunnel.data.session.environment })] })), context.debugFunnel.data.session.startedAt && (_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { style: { color: '#6b7280' }, children: "Started At:" }), _jsx("span", { style: { color: '#9ca3af', fontSize: '10px' }, children: new Date(context.debugFunnel.data.session.startedAt).toLocaleString() })] })), context.debugFunnel.data.session.lastActivityAt && (_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { style: { color: '#6b7280' }, children: "Last Activity:" }), _jsx("span", { style: { color: '#9ca3af', fontSize: '10px' }, children: new Date(context.debugFunnel.data.session.lastActivityAt).toLocaleString() })] }))] }) })] })] })), _jsxs("details", { style: { marginTop: '12px' }, children: [_jsx("summary", { style: {
+                                                            cursor: 'pointer',
+                                                            fontWeight: 'bold',
+                                                            fontSize: '13px',
+                                                            color: '#60a5fa',
+                                                            marginBottom: '8px',
+                                                        }, children: "\uD83D\uDD0D Raw Funnel Data (Debug)" }), _jsx("div", { style: { fontSize: '11px', marginTop: '8px' }, children: _jsx(TreeView, { data: context.debugFunnel.data, name: "funnelData", maxLevel: 4 }) })] })] })) : (_jsx("p", { style: { color: '#6b7280' }, children: "No funnel hook active" }))] })), activeTab === 'checkout' && (_jsxs("div", { children: [_jsx("h3", { style: { margin: '0 0 16px 0', color: '#60a5fa' }, children: "Checkout Debug" }), context.debugCheckout.isActive ? (_jsxs("div", { children: [_jsxs("div", { style: { marginBottom: '20px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#60a5fa' }, children: "Status" }), _jsxs("div", { style: { display: 'grid', gap: '8px' }, children: [_jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Hook Active:" }), _jsx("span", { style: { color: '#10b981' }, children: "\u2705 Yes" })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Loading:" }), _jsx("span", { style: { color: context.debugCheckout.isLoading ? '#f59e0b' : '#10b981' }, children: context.debugCheckout.isLoading ? '⏳ Yes' : '✅ No' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Has Error:" }), _jsx("span", { style: { color: context.debugCheckout.error ? '#ef4444' : '#10b981' }, children: context.debugCheckout.error ? '❌ Yes' : '✅ No' })] }), _jsxs("div", { style: { display: 'flex', justifyContent: 'space-between' }, children: [_jsx("span", { children: "Last Updated:" }), _jsx("span", { style: { color: '#9ca3af', fontSize: '12px' }, children: context.debugCheckout.lastUpdated?.toLocaleTimeString() || 'Never' })] })] })] }), context.debugCheckout.error && (_jsxs("div", { style: { marginBottom: '20px' }, children: [_jsx("h4", { style: { margin: '0 0 12px 0', color: '#ef4444' }, children: "Error Details" }), _jsxs("div", { style: {
                                                             backgroundColor: '#372c2c',
                                                             padding: '12px',
                                                             borderRadius: '4px',

package/dist/v2/react/hooks/__examples__/FunnelContextExample.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export declare function FunnelContextExample(): import("react/jsx-runtime").JSX.Element;
+/**
+ * Simple example for documentation
+ * This can now be called with or without options
+ */
+export declare function SimpleContextExample(): import("react/jsx-runtime").JSX.Element;

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

@@ -37,7 +37,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)
  */
@@ -46,6 +46,6 @@ export declare function useSimpleFunnel(funnelId: string, initialStepId?: string
     next: (event: FunnelAction) => Promise<any>;
     goToStep: (stepId: string) => Promise<any>;
     isLoading: boolean;
-    context: SimpleFunnelContext | null;
+    context: SimpleFunnelContext<{}> | null;
 };
 export type { FunnelAction as FunnelEvent, FunnelNavigationAction, FunnelNavigationResult, SimpleFunnelContext } from '../../core/resources/funnel';

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,7 +20,7 @@ const funnelQueryKeys = {
  * Modern funnel navigation using TanStack Query for state management
  * and the v2 ApiClient architecture.
  */
-export function useFunnel(options) {
+export function useFunnel(options = {}) {
     const { auth, store, debugMode, updateFunnelDebugData } = useTagadaContext();
     const queryClient = useQueryClient();
     const apiClient = getGlobalApiClient();
@@ -29,10 +29,53 @@ export function useFunnel(options) {
     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);
+    // 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
@@ -66,13 +109,8 @@ export function useFunnel(options) {
                 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);
+            const response = await funnelResource.getSession(context.sessionId);
             console.log(`🍪 Funnel: Session fetch response:`, response);
             if (response.success && response.context) {
                 return response.context;
@@ -90,8 +128,14 @@ export function useFunnel(options) {
             if (!auth.session?.customerId || !store?.id) {
                 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 +146,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,17 +171,35 @@ 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;
             }
@@ -138,7 +212,10 @@ export function useFunnel(options) {
             setInitializationError(null);
             // Set session cookie for persistence across page reloads
             setSessionCookie(newContext.sessionId);
-            console.log(`🍪 Funnel: Initialized session for funnel ${effectiveFunnelId || 'default'}`, newContext);
+            console.log(`✅ Funnel: Session initialized/loaded successfully`);
+            console.log(`   - Session ID: ${newContext.sessionId}`);
+            console.log(`   - Funnel ID: ${newContext.funnelId}`);
+            console.log(`   - Current Step: ${newContext.currentStepId}`);
             // Fetch debug data if in debug mode
             if (debugMode) {
                 void fetchFunnelDebugData(newContext.sessionId);
@@ -317,6 +394,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)
@@ -421,29 +500,127 @@ 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...');
+        console.log('🔍 Funnel: Auto-init effect triggered');
+        console.log(`   - autoInitialize: ${options.autoInitialize ?? true}`);
+        console.log(`   - hasAuth: ${!!auth.session?.customerId}`);
+        console.log(`   - hasStore: ${!!store?.id}`);
+        console.log(`   - isPending: ${initializeMutation.isPending}`);
+        console.log(`   - hasContext: ${!!context}`);
+        console.log(`   - context.sessionId: ${context?.sessionId || 'none'}`);
+        console.log(`   - context.funnelId: ${context?.funnelId || 'none'}`);
+        console.log(`   - urlFunnelId: ${urlFunnelId || 'none'}`);
+        console.log(`   - options.funnelId: ${options.funnelId || 'none'}`);
+        console.log(`   - initializationAttempted: ${initializationAttempted}`);
+        console.log(`   - hasExistingSessionCookie: ${hasExistingSessionCookie}`);
+        // Skip if auto-initialize is disabled
+        const autoInit = options.autoInitialize ?? true; // Default to true
+        if (!autoInit) {
+            console.log('⏭️  Funnel: Skipping - auto-initialize disabled');
+            return;
+        }
+        // Skip if required dependencies are not available
+        if (!auth.session?.customerId || !store?.id) {
+            console.log('⏭️  Funnel: Skipping - missing auth or store');
+            return;
+        }
+        // Skip if already initializing
+        if (initializeMutation.isPending) {
+            console.log('⏭️  Funnel: Skipping - already initializing');
+            return;
+        }
+        // Determine if we have an explicit funnelId request (URL has priority)
+        const explicitFunnelId = urlFunnelId || options.funnelId;
+        console.log(`   - explicitFunnelId: ${explicitFunnelId || 'none'}`);
+        // Case 1: No session exists yet - need to initialize
+        if (!context) {
+            console.log('📍 Funnel: Case 1 - No context exists');
+            // Check if we've already attempted initialization
+            if (!initializationAttempted) {
+                if (hasExistingSessionCookie) {
+                    console.log('🍪 Funnel: Loading existing session from cookie...');
+                }
+                else {
+                    console.log('🍪 Funnel: No session found - creating new session...');
+                }
+                if (explicitFunnelId) {
+                    console.log(`   with funnelId: ${explicitFunnelId}`);
+                }
+                setInitializationAttempted(true);
+                initializeSession().catch(error => {
+                    console.error('❌ Funnel: Auto-initialization failed:', error);
+                });
+            }
+            else {
+                console.log('⏭️  Funnel: Skipping - already attempted initialization');
+            }
+            return;
+        }
+        console.log('📍 Funnel: Case 2 - Context exists, checking for reset needs');
+        // 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) {
+            console.log(`🔍 Funnel: Mismatch check - explicitFunnelId: ${explicitFunnelId}, context.funnelId: ${context.funnelId}`);
+            // Check if we've already processed this funnelId to prevent loops
+            if (lastProcessedUrlFunnelIdRef.current === explicitFunnelId) {
+                console.log('⏭️  Funnel: Skipping - already processed this funnelId');
+                return;
+            }
+            console.log(`🔄 Funnel: Explicit funnelId mismatch detected!`);
+            console.log(`   Current session funnelId: ${context.funnelId}`);
+            console.log(`   Requested funnelId: ${explicitFunnelId}`);
+            console.log(`   Resetting session...`);
+            // 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
+            console.log(`🍪 Funnel: Creating new session with funnelId: ${explicitFunnelId}`);
             initializeSession().catch(error => {
-                console.error('Auto-initialization failed - will not retry:', error);
+                console.error('❌ Funnel: Failed to reset session:', error);
             });
         }
+        else {
+            // Case 3: Session exists and no conflicting funnelId - keep using it
+            console.log('✅ Funnel: Case 3 - Keeping existing session (no reset needed)');
+            console.log(`   - explicitFunnelId: ${explicitFunnelId || 'none (will keep existing)'}`);
+            console.log(`   - context.funnelId: ${context.funnelId}`);
+            console.log(`   - Match or no explicit request: keeping session ${context.sessionId}`);
+        }
     }, [
         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(() => {