@tagadapay/plugin-sdk 2.8.9 → 2.8.10

package/dist/v2/core/client.d.ts

@@ -33,6 +33,10 @@ export declare class TagadaClient {
     private boundHandleStorageChange;
     private readonly config;
     private instanceId;
+    private isInitializingSession;
+    private lastSessionInitError;
+    private sessionInitRetryCount;
+    private readonly MAX_SESSION_INIT_RETRIES;
     constructor(config?: TagadaClientConfig);
     /**
      * Cleanup client resources

package/dist/v2/core/client.js

@@ -10,6 +10,11 @@ export class TagadaClient {
         this.eventDispatcher = new EventDispatcher();
         this.tokenPromise = null;
         this.tokenResolver = null;
+        // Track initialization state to prevent infinite loops
+        this.isInitializingSession = false;
+        this.lastSessionInitError = null;
+        this.sessionInitRetryCount = 0;
+        this.MAX_SESSION_INIT_RETRIES = 3;
         this.config = config;
         this.instanceId = Math.random().toString(36).substr(2, 9);
         this.boundHandleStorageChange = this.handleStorageChange.bind(this);
@@ -86,6 +91,20 @@ export class TagadaClient {
             }
             return;
         }
+        // Prevent infinite loop: Don't re-initialize if we're currently initializing
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization in progress, skipping storage change`);
+            }
+            return;
+        }
+        // Prevent infinite loop: Don't retry if we've hit max retries
+        if (this.sessionInitRetryCount >= this.MAX_SESSION_INIT_RETRIES && this.lastSessionInitError) {
+            if (this.state.debugMode) {
+                console.error(`[TagadaClient ${this.instanceId}] Max session init retries reached, giving up`, this.lastSessionInitError);
+            }
+            return;
+        }
         // Re-run initialization when token may have changed
         if (this.state.debugMode) {
             console.log(`[TagadaClient ${this.instanceId}] Storage changed, re-initializing token...`);
@@ -259,6 +278,13 @@ export class TagadaClient {
      * Create anonymous token
      */
     async createAnonymousToken(storeId) {
+        // Prevent concurrent anonymous token creation
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization in progress, skipping anonymous token creation`);
+            }
+            return;
+        }
         try {
             if (this.state.debugMode)
                 console.log('[TagadaClient] Creating anonymous token for store:', storeId);
@@ -282,6 +308,14 @@ export class TagadaClient {
      * Initialize session
      */
     async initializeSession(sessionData) {
+        // Prevent concurrent initialization attempts
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization already in progress, skipping`);
+            }
+            return;
+        }
+        this.isInitializingSession = true;
         try {
             if (this.state.debugMode) {
                 console.log(`[TagadaClient ${this.instanceId}] Initializing session...`, { sessionId: sessionData.sessionId });
@@ -311,6 +345,9 @@ export class TagadaClient {
                 timeZone: deviceInfo.timeZone,
             };
             const response = await this.apiClient.post('/api/v1/cms/session/init', sessionInitData);
+            // Success - reset error tracking
+            this.lastSessionInitError = null;
+            this.sessionInitRetryCount = 0;
             // Update state with session data
             this.updateSessionState(response, sessionData);
             this.updateState({
@@ -322,12 +359,19 @@ export class TagadaClient {
                 console.log('[TagadaClient] Session initialized successfully');
         }
         catch (error) {
-            console.error('[TagadaClient] Error initializing session:', error);
+            // Track error and increment retry count
+            this.lastSessionInitError = error;
+            this.sessionInitRetryCount++;
+            console.error(`[TagadaClient] Error initializing session (attempt ${this.sessionInitRetryCount}/${this.MAX_SESSION_INIT_RETRIES}):`, error);
             this.updateState({
                 isInitialized: true,
                 isLoading: false,
             });
         }
+        finally {
+            // Always release the lock
+            this.isInitializingSession = false;
+        }
     }
     updateSessionState(response, sessionData) {
         // Update Store

package/dist/v2/core/config/environment.d.ts

@@ -1,4 +1,17 @@
 import { ApiConfig, Environment, EnvironmentConfig } from '../types';
+/**
+ * ⚠️ IMPORTANT: Runtime Environment Detection
+ *
+ * This SDK uses RUNTIME hostname detection, NOT build-time environment variables.
+ * This ensures the SDK always connects to the correct API based on where it's deployed.
+ *
+ * - Production domains → production API
+ * - Dev/staging domains → development API
+ * - Localhost/local IPs → local API (with optional override via window.__TAGADA_ENV__)
+ *
+ * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
+ * to prevent incorrect API connections when plugins are deployed to different environments.
+ */
 /**
  * Environment configurations for different deployment environments
  */
@@ -16,7 +29,8 @@ export declare function buildApiUrl(config: EnvironmentConfig, endpointPath: str
  */
 export declare function getEndpointUrl(config: EnvironmentConfig, category: keyof ApiConfig['endpoints'], endpoint: string): string;
 /**
- * Auto-detect environment based on hostname, URL patterns, and deployment context
- * Works with any build tool or deployment system
+ * Auto-detect environment based on hostname and URL patterns at RUNTIME
+ * ⚠️ IMPORTANT: Ignores build-time .env variables to ensure correct detection in all environments
+ * .env variables are ONLY used for local development via window.__TAGADA_ENV__
  */
 export declare function detectEnvironment(): Environment;

package/dist/v2/core/config/environment.js

@@ -1,4 +1,16 @@
-import { resolveEnvValue } from '../utils/env';
+/**
+ * ⚠️ IMPORTANT: Runtime Environment Detection
+ *
+ * This SDK uses RUNTIME hostname detection, NOT build-time environment variables.
+ * This ensures the SDK always connects to the correct API based on where it's deployed.
+ *
+ * - Production domains → production API
+ * - Dev/staging domains → development API
+ * - Localhost/local IPs → local API (with optional override via window.__TAGADA_ENV__)
+ *
+ * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
+ * to prevent incorrect API connections when plugins are deployed to different environments.
+ */
 /**
  * Environment configurations for different deployment environments
  */
@@ -87,33 +99,45 @@ export function getEndpointUrl(config, category, endpoint) {
     return buildApiUrl(config, endpointPath);
 }
 /**
- * Auto-detect environment based on hostname, URL patterns, and deployment context
- * Works with any build tool or deployment system
+ * Auto-detect environment based on hostname and URL patterns at RUNTIME
+ * ⚠️ IMPORTANT: Ignores build-time .env variables to ensure correct detection in all environments
+ * .env variables are ONLY used for local development via window.__TAGADA_ENV__
  */
 export function detectEnvironment() {
-    // 1. Check environment variables first
-    const envVar = resolveEnvValue('TAGADA_ENVIRONMENT') || resolveEnvValue('TAGADA_ENV');
-    if (envVar) {
-        const normalized = envVar.toLowerCase();
-        if (normalized === 'production' || normalized === 'development' || normalized === 'local') {
-            return normalized;
-        }
-    }
     // Check if we're in browser
     if (typeof window === 'undefined') {
         return 'local'; // SSR fallback
     }
     const hostname = window.location.hostname;
     const href = window.location.href;
-    // Production: deployed to production domains
+    // 1. Check for LOCAL environment first (highest priority for dev)
+    // Local: localhost, local IPs, or local domains
+    if (hostname === 'localhost' ||
+        hostname.startsWith('127.') ||
+        hostname.startsWith('192.168.') ||
+        hostname.startsWith('10.') ||
+        hostname.includes('.local') ||
+        hostname === '' ||
+        hostname === '0.0.0.0') {
+        // For local development, allow override via window.__TAGADA_ENV__ (injected by dev server)
+        if (typeof window !== 'undefined' && window?.__TAGADA_ENV__?.TAGADA_ENVIRONMENT) {
+            const override = window.__TAGADA_ENV__.TAGADA_ENVIRONMENT.toLowerCase();
+            if (override === 'production' || override === 'development' || override === 'local') {
+                console.log(`[SDK] Local override detected: ${override}`);
+                return override;
+            }
+        }
+        return 'local';
+    }
+    // 2. Production: deployed to production domains
     if (hostname === 'app.tagadapay.com' ||
         hostname.includes('tagadapay.com') ||
         hostname.includes('yourproductiondomain.com')) {
         return 'production';
     }
-    // Development: deployed to staging/dev domains or has dev indicators
+    // 3. Development: deployed to staging/dev domains or has dev indicators
     if (hostname === 'app.tagadapay.dev' ||
-        hostname.includes('tagadapay.dev') || // ✅ app.tagadapay.dev and subdomains
+        hostname.includes('tagadapay.dev') ||
         hostname.includes('vercel.app') ||
         hostname.includes('netlify.app') ||
         hostname.includes('surge.sh') ||
@@ -125,16 +149,7 @@ export function detectEnvironment() {
         href.includes('#dev')) {
         return 'development';
     }
-    // Local: localhost, local IPs, or local domains
-    if (hostname === 'localhost' ||
-        hostname.startsWith('127.') ||
-        hostname.startsWith('192.168.') ||
-        hostname.startsWith('10.') ||
-        hostname.includes('.local') ||
-        hostname === '' ||
-        hostname === '0.0.0.0') {
-        return 'local';
-    }
-    // Default fallback for unknown domains (safer to use development)
+    // 4. Default fallback for unknown domains (production is safest)
+    console.warn(`[SDK] Unknown domain: ${hostname}, defaulting to production`);
     return 'production';
 }

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

@@ -18,6 +18,9 @@ export declare class ApiClient {
     axios: AxiosInstance;
     private currentToken;
     private tokenProvider;
+    private requestHistory;
+    private readonly WINDOW_MS;
+    private readonly MAX_REQUESTS;
     constructor(config: ApiClientConfig);
     setTokenProvider(provider: TokenProvider): void;
     get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T>;
@@ -30,4 +33,6 @@ export declare class ApiClient {
     updateToken(token: string | null): void;
     getCurrentToken(): string | null;
     updateConfig(config: Partial<ApiClientConfig>): void;
+    private checkRequestLimit;
+    private cleanupHistory;
 }

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

@@ -7,6 +7,10 @@ export class ApiClient {
     constructor(config) {
         this.currentToken = null;
         this.tokenProvider = null;
+        // Circuit breaker state
+        this.requestHistory = new Map();
+        this.WINDOW_MS = 5000; // 5 seconds window
+        this.MAX_REQUESTS = 5; // Max 5 requests per endpoint in window
         this.axios = axios.create({
             baseURL: config.baseURL,
             timeout: config.timeout || 30000,
@@ -15,8 +19,22 @@ export class ApiClient {
                 ...config.headers,
             },
         });
+        // Cleanup interval for circuit breaker history
+        if (typeof setInterval !== 'undefined') {
+            setInterval(() => this.cleanupHistory(), 10000);
+        }
         // Request interceptor for logging and auth
         this.axios.interceptors.request.use(async (config) => {
+            // Circuit Breaker Check
+            if (config.url) {
+                try {
+                    this.checkRequestLimit(`${config.method?.toUpperCase()}:${config.url}`);
+                }
+                catch (error) {
+                    console.error('[SDK] 🛑 Request blocked by Circuit Breaker:', error);
+                    return Promise.reject(error);
+                }
+            }
             // Check if we need to wait for token
             if (!config.skipAuth && !this.currentToken && this.tokenProvider) {
                 try {
@@ -113,4 +131,33 @@ export class ApiClient {
         }
         console.log('[SDK] ApiClient configuration updated');
     }
+    // Circuit Breaker Implementation
+    checkRequestLimit(key) {
+        const now = Date.now();
+        const history = this.requestHistory.get(key);
+        if (!history) {
+            this.requestHistory.set(key, { count: 1, firstRequestTime: now });
+            return;
+        }
+        if (now - history.firstRequestTime > this.WINDOW_MS) {
+            // Window expired, reset
+            this.requestHistory.set(key, { count: 1, firstRequestTime: now });
+            return;
+        }
+        history.count++;
+        if (history.count > this.MAX_REQUESTS) {
+            const error = new Error(`Circuit Breaker: Too many requests to ${key} (${history.count} in ${this.WINDOW_MS}ms)`);
+            // Add a property to identify this as a circuit breaker error
+            error.isCircuitBreaker = true;
+            throw error;
+        }
+    }
+    cleanupHistory() {
+        const now = Date.now();
+        for (const [key, history] of this.requestHistory.entries()) {
+            if (now - history.firstRequestTime > this.WINDOW_MS) {
+                this.requestHistory.delete(key);
+            }
+        }
+    }
 }

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

@@ -408,6 +408,13 @@ export interface SimpleFunnelContext<TCustom = {}> {
      * - Standard keys provide IntelliSense, custom keys always allowed
      */
     resources?: FunnelResourceMap<TCustom>;
+    /**
+     * Static resources from plugin manifest (type: "static")
+     * - Configured in funnel editor's Static Resources tab
+     * - Available at runtime as context.static
+     * - Example: context.static.offer.id for statically configured offers
+     */
+    static?: Record<string, any>;
     /**
      * Legacy/Custom metadata
      * For backward compatibility and flexible unstructured data

package/dist/v2/core/utils/pluginConfig.d.ts

@@ -7,6 +7,7 @@ export type PluginConfig<TConfig = Record<string, any>> = {
     accountId?: string;
     basePath?: string;
     config?: any;
+    staticResources?: Record<string, any>;
     productId?: string;
     variants?: Record<string, string>;
     prices?: Record<string, any>;

package/dist/v2/core/utils/pluginConfig.js

@@ -14,13 +14,13 @@ const loadLocalDevConfig = async (configVariant = 'default') => {
             // Skip local config loading if explicitly in production mode
             return null;
         }
-        // Only try to load local config in development
-        // Use hostname-based detection for better Vite compatibility
+        // Only try to load local config in TRUE local development (not deployed CDN instances)
+        // Exclude CDN subdomains (e.g., instance-id.cdn.localhost) by checking for 'cdn.' prefix
         const isLocalDev = typeof window !== 'undefined' &&
             (window.location.hostname === 'localhost' ||
-                window.location.hostname.includes('ngrok-free.app') ||
-                window.location.hostname.includes('.localhost') ||
-                window.location.hostname.includes('127.0.0.1'));
+                window.location.hostname === '127.0.0.1' ||
+                window.location.hostname.includes('ngrok-free.app')) &&
+            !window.location.hostname.includes('.cdn.');
         if (!isLocalDev) {
             return null;
         }
@@ -87,6 +87,43 @@ const loadLocalDevConfig = async (configVariant = 'default') => {
         return null;
     }
 };
+/**
+ * Load static resources for local development
+ * Loads /config/resources.static.json
+ */
+const loadStaticResources = async () => {
+    try {
+        // Check for explicit environment override
+        const env = resolveEnvValue('TAGADA_ENV') || resolveEnvValue('TAGADA_ENVIRONMENT');
+        if (env === 'production') {
+            return null;
+        }
+        // Only try to load in TRUE local development (not deployed CDN instances)
+        // Exclude CDN subdomains (e.g., instance-id.cdn.localhost) by checking for 'cdn.' prefix
+        const isLocalDev = typeof window !== 'undefined' &&
+            (window.location.hostname === 'localhost' ||
+                window.location.hostname === '127.0.0.1' ||
+                window.location.hostname.includes('ngrok-free.app')) &&
+            !window.location.hostname.includes('.cdn.');
+        if (!isLocalDev) {
+            return null;
+        }
+        // Load static resources file
+        console.log('🛠️ Attempting to load /config/resources.static.json...');
+        const response = await fetch('/config/resources.static.json');
+        if (!response.ok) {
+            console.log('🛠️ resources.static.json not found or failed to load');
+            return null;
+        }
+        const staticResources = await response.json();
+        console.log('🛠️ ✅ Loaded local static resources:', staticResources);
+        return staticResources;
+    }
+    catch (error) {
+        console.error('🛠️ ❌ Error loading static resources:', error);
+        return null;
+    }
+};
 /**
  * Helper to get content from meta tag
  */
@@ -143,6 +180,8 @@ const loadProductionConfig = async () => {
  * Handles local dev, production, and raw config
  */
 export const loadPluginConfig = async (configVariant = 'default', rawConfig) => {
+    // Load static resources first (only in local dev)
+    const staticResources = await loadStaticResources();
     // If raw config is provided, use it directly
     if (rawConfig) {
         return {
@@ -150,21 +189,32 @@ export const loadPluginConfig = async (configVariant = 'default', rawConfig) =>
             accountId: rawConfig.accountId,
             basePath: rawConfig.basePath ?? '/',
             config: rawConfig.config ?? {},
+            staticResources: staticResources ?? undefined,
         };
     }
     else {
         const rawConfig = await createRawPluginConfig();
         if (rawConfig) {
-            return rawConfig;
+            return {
+                ...rawConfig,
+                staticResources: staticResources ?? undefined,
+            };
         }
     }
     // Try local development config
     const localConfig = await loadLocalDevConfig(configVariant);
     if (localConfig) {
-        return localConfig;
+        return {
+            ...localConfig,
+            staticResources: staticResources ?? undefined,
+        };
     }
     // Fall back to production config
-    return loadProductionConfig();
+    const productionConfig = await loadProductionConfig();
+    return {
+        ...productionConfig,
+        staticResources: staticResources ?? undefined,
+    };
 };
 /**
  * Helper to load local config file for development (from /config directory)

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

@@ -5,7 +5,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useCallback, useEffect, useState } from 'react';
 import { useExpressPaymentMethods } from '../hooks/useExpressPaymentMethods';
-export const ApplePayButton = ({ className = '', disabled = false, onSuccess, onError, onCancel, storeName, currencyCode = 'USD', variant = 'outline', size = 'lg', checkout, }) => {
+export const ApplePayButton = ({ className = '', disabled = false, onSuccess, onError, onCancel, storeName, currencyCode = 'USD', variant = 'default', size = 'lg', checkout, }) => {
     const { applePayPaymentMethod, shippingMethods, lineItems, handleAddExpressId, updateCheckoutSessionValues, updateCustomerEmail, reComputeOrderSummary, setError: setContextError, } = useExpressPaymentMethods();
     const [processingPayment, setProcessingPayment] = useState(false);
     const [isApplePayAvailable, setIsApplePayAvailable] = useState(false);

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>;

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

@@ -21,16 +21,40 @@ const funnelQueryKeys = {
  * and the v2 ApiClient architecture.
  */
 export function useFunnel(options = {}) {
-    const { auth, store, debugMode, updateFunnelDebugData } = useTagadaContext();
+    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')
@@ -106,14 +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;
             }
-            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;
+                return enrichContext(response.context);
             }
             throw new Error(response.error || 'Failed to fetch session');
         },
@@ -125,7 +146,13 @@ 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
@@ -201,31 +228,36 @@ export function useFunnel(options = {}) {
                 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);
+            setSessionCookie(enrichedContext.sessionId);
             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}`);
+            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);
@@ -246,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,
@@ -295,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`;
@@ -308,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
@@ -322,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);
@@ -368,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({
@@ -421,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);
@@ -449,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]);
@@ -514,75 +554,40 @@ export function useFunnel(options = {}) {
      * Priority: URL funnelId > Hook funnelId > Existing session funnelId > Backend default
      */
     useEffect(() => {
-        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');
+        // 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;
-        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...`);
+            console.log(`🔄 Funnel: Switching from funnel ${context.funnelId} to ${explicitFunnelId}`);
             // Mark this funnelId as processed
             lastProcessedUrlFunnelIdRef.current = explicitFunnelId;
             // Clear existing session
@@ -596,18 +601,10 @@ export function useFunnel(options = {}) {
                 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('❌ 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,
         options.funnelId,
@@ -630,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,
@@ -640,6 +638,7 @@ export function useFunnel(options = {}) {
         context,
         isLoading,
         isInitialized,
+        isNavigating, // Expose isNavigating
         initializeSession,
         endSession,
         retryInitialization,

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

@@ -22,11 +22,29 @@ export interface UseOffersQueryOptions {
      * Order ID to associate with the offers (required for payments)
      */
     orderId?: string;
+    /**
+     * The ID of the currently active offer to preview/fetch summary for.
+     * If provided, the hook will automatically fetch and manage the summary for this offer.
+     */
+    activeOfferId?: string;
+    /**
+     * Whether to skip auto-preview fetching (e.g. during navigation or processing)
+     */
+    skipPreview?: boolean;
 }
 export interface UseOffersQueryResult {
     offers: Offer[];
     isLoading: boolean;
     error: Error | null;
+    /**
+     * Summary for the active offer (if activeOfferId is provided)
+     * Automatically falls back to static summary while loading dynamic data
+     */
+    activeSummary: OrderSummary | OfferSummary | null;
+    /**
+     * Whether the active offer summary is currently loading
+     */
+    isActiveSummaryLoading: boolean;
     /**
      * Pay for an offer
      * Initializes a checkout session and pays it

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

@@ -3,18 +3,26 @@
  * Handles offers with automatic caching
  */
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { OffersResource } from '../../core/resources/offers';
 import { useTagadaContext } from '../providers/TagadaProvider';
 import { getGlobalApiClient } from './useApiQuery';
 import { usePluginConfig } from './usePluginConfig';
 export function useOffersQuery(options = {}) {
-    const { offerIds = [], enabled = true, returnUrl, orderId: defaultOrderId } = options;
+    const { offerIds = [], enabled = true, returnUrl, orderId: defaultOrderId, activeOfferId, skipPreview = false } = options;
     const { storeId } = usePluginConfig();
     const { isSessionInitialized, session } = useTagadaContext();
     const _queryClient = useQueryClient();
+    // Version identifier for debugging
+    console.log('[useOffersQuery] Hook initialized - VERSION: 2.2-production-ready', {
+        activeOfferId,
+        skipPreview,
+        isSessionInitialized,
+    });
     // State for checkout sessions per offer (similar to postPurchases)
     const [checkoutSessions, setCheckoutSessions] = useState({});
+    const [isActiveSummaryLoading, setIsActiveSummaryLoading] = useState(false);
+    const lastPreviewedOfferRef = useRef(null);
     // Use ref to break dependency cycles in callbacks
     const checkoutSessionsRef = useRef(checkoutSessions);
     // Update ref on every render
@@ -30,6 +38,8 @@ export function useOffersQuery(options = {}) {
     }, []);
     // Helper function for fetching order summary (similar to postPurchases)
     const fetchOrderSummary = useCallback(async (offerId, sessionId) => {
+        if (!isSessionInitialized)
+            return null;
         try {
             // Set updating state
             setCheckoutSessions(prev => ({
@@ -77,7 +87,7 @@ export function useOffersQuery(options = {}) {
             }));
             throw error;
         }
-    }, [offersResource]);
+    }, [offersResource, isSessionInitialized]);
     // Create query key based on options
     const queryKey = useMemo(() => ['offers', { storeId, offerIds }], [storeId, offerIds]);
     // Use TanStack Query for fetching offers
@@ -120,6 +130,9 @@ export function useOffersQuery(options = {}) {
         return await payWithCheckoutSessionAsync({ checkoutSessionId, orderId });
     }, [payWithCheckoutSessionAsync]);
     const initCheckoutSession = useCallback(async (offerId, orderId, customerId) => {
+        if (!isSessionInitialized) {
+            throw new Error('Cannot initialize checkout session: CMS session is not initialized');
+        }
         // Use customerId from session context if not provided
         const effectiveCustomerId = customerId || session?.customerId;
         if (!effectiveCustomerId) {
@@ -130,8 +143,11 @@ export function useOffersQuery(options = {}) {
             orderId,
             customerId: effectiveCustomerId
         });
-    }, [initCheckoutSessionAsync, session?.customerId]);
+    }, [initCheckoutSessionAsync, session?.customerId, isSessionInitialized]);
     const payOffer = useCallback(async (offerId, orderId) => {
+        if (!isSessionInitialized) {
+            throw new Error('Cannot pay offer: CMS session is not initialized');
+        }
         const effectiveOrderId = orderId || defaultOrderId;
         const effectiveCustomerId = session?.customerId;
         if (!effectiveOrderId) {
@@ -144,18 +160,26 @@ export function useOffersQuery(options = {}) {
         const { checkoutSessionId } = await initCheckoutSession(offerId, effectiveOrderId, effectiveCustomerId);
         // 2. Pay
         await payWithCheckoutSession(checkoutSessionId, effectiveOrderId);
-    }, [initCheckoutSession, payWithCheckoutSession, defaultOrderId, session?.customerId]);
+    }, [initCheckoutSession, payWithCheckoutSession, defaultOrderId, session?.customerId, isSessionInitialized]);
     const preview = useCallback(async (offerId) => {
+        console.log('[useOffersQuery] preview() called for offer:', offerId);
+        if (!isSessionInitialized) {
+            console.log('[useOffersQuery] preview() - session not initialized, returning null');
+            // Return null silently to avoid errors during auto-initialization phases
+            return null;
+        }
         const effectiveOrderId = defaultOrderId;
         const effectiveCustomerId = session?.customerId;
         // Use ref to check current state without creating dependency
         const currentSessions = checkoutSessionsRef.current;
         // If we already have a summary in state, return it
         if (currentSessions[offerId]?.orderSummary) {
+            console.log('[useOffersQuery] preview() - using cached summary for offer:', offerId);
             return currentSessions[offerId].orderSummary;
         }
         // Prevent duplicate initialization if already has a session and is updating
         if (currentSessions[offerId]?.checkoutSessionId && currentSessions[offerId]?.isUpdatingSummary) {
+            console.log('[useOffersQuery] preview() - already updating, skipping for offer:', offerId);
             return null;
         }
         // If we don't have orderId, fallback to static summary from offer object
@@ -189,7 +213,71 @@ export function useOffersQuery(options = {}) {
             console.error("Failed to preview offer", e);
             return null;
         }
-    }, [offers, defaultOrderId, session?.customerId, initCheckoutSession, fetchOrderSummary]); // Removed checkoutSessions dependency
+    }, [offers, defaultOrderId, session?.customerId, initCheckoutSession, fetchOrderSummary, isSessionInitialized]); // Removed checkoutSessions dependency
+    // Auto-preview effect for activeOfferId
+    useEffect(() => {
+        console.log('[useOffersQuery v2.2] Auto-preview effect triggered:', {
+            activeOfferId,
+            skipPreview,
+            isSessionInitialized,
+            lastPreviewed: lastPreviewedOfferRef.current,
+        });
+        if (!activeOfferId || skipPreview || !isSessionInitialized) {
+            console.log('[useOffersQuery] Skipping auto-preview - conditions not met');
+            setIsActiveSummaryLoading(false); // Reset loading state if conditions not met
+            // Reset the ref when conditions are not met
+            if (!activeOfferId) {
+                lastPreviewedOfferRef.current = null;
+            }
+            return;
+        }
+        // Skip if we've already previewed this exact offer
+        if (lastPreviewedOfferRef.current === activeOfferId) {
+            console.log('[useOffersQuery] Skipping auto-preview - already previewed:', activeOfferId);
+            setIsActiveSummaryLoading(false); // Ensure loading is false
+            return;
+        }
+        console.log('[useOffersQuery] Starting auto-preview for offer:', activeOfferId);
+        let isMounted = true;
+        setIsActiveSummaryLoading(true); // Set loading immediately
+        // Debounce the preview call
+        const timer = setTimeout(() => {
+            if (!isMounted) {
+                console.log('[useOffersQuery] Component unmounted before preview call');
+                return;
+            }
+            console.log('[useOffersQuery] Calling preview for offer:', activeOfferId);
+            preview(activeOfferId)
+                .then(() => {
+                if (isMounted) {
+                    console.log('[useOffersQuery] Preview successful for offer:', activeOfferId);
+                    lastPreviewedOfferRef.current = activeOfferId; // Mark as previewed on success
+                }
+            })
+                .catch(err => {
+                console.error('[useOffersQuery] Failed to auto-preview offer:', activeOfferId, err);
+                // Don't mark as previewed on error, to avoid infinite retry loop
+            })
+                .finally(() => {
+                if (isMounted) {
+                    console.log('[useOffersQuery] Preview finished for offer:', activeOfferId);
+                    setIsActiveSummaryLoading(false);
+                }
+            });
+        }, 50);
+        return () => {
+            console.log('[useOffersQuery] Cleaning up auto-preview effect for offer:', activeOfferId);
+            isMounted = false;
+            clearTimeout(timer);
+            setIsActiveSummaryLoading(false); // Reset loading on unmount/cleanup
+        };
+    }, [activeOfferId, skipPreview, isSessionInitialized]); // FIXED: Removed 'preview' from dependencies to prevent infinite loop
+    const activeSummary = useMemo(() => {
+        if (!activeOfferId)
+            return null;
+        // Return dynamic summary if available, otherwise fallback to static summary
+        return checkoutSessions[activeOfferId]?.orderSummary || offers.find(o => o.id === activeOfferId)?.summaries?.[0] || null;
+    }, [activeOfferId, checkoutSessions, offers]);
     const getAvailableVariants = useCallback((offerId, productId) => {
         const sessionState = checkoutSessions[offerId]; // This hook needs to react to state changes
         if (!sessionState?.orderSummary?.options?.[productId])
@@ -208,6 +296,9 @@ export function useOffersQuery(options = {}) {
         return checkoutSessions[offerId]?.loadingVariants?.[productId] ?? false;
     }, [checkoutSessions]);
     const selectVariant = useCallback(async (offerId, productId, variantId) => {
+        if (!isSessionInitialized) {
+            throw new Error('Cannot select variant: CMS session is not initialized');
+        }
         // Use ref for initial check to avoid dependency but we might need latest state for logic
         // Actually for actions it's better to use ref or just dependency if action is not called in useEffect
         const currentSessions = checkoutSessionsRef.current;
@@ -286,12 +377,14 @@ export function useOffersQuery(options = {}) {
                 }
             }));
         }
-    }, [offersResource, fetchOrderSummary]); // Removed checkoutSessions dependency
-    return {
+    }, [offersResource, fetchOrderSummary, isSessionInitialized]); // Removed checkoutSessions dependency
+    const result = {
         // Query data
         offers,
         isLoading,
         error,
+        activeSummary,
+        isActiveSummaryLoading,
         // Actions
         payOffer,
         preview,
@@ -299,4 +392,13 @@ export function useOffersQuery(options = {}) {
         selectVariant,
         isLoadingVariants,
     };
+    console.log('[useOffersQuery] Returning result:', {
+        offersCount: offers.length,
+        isLoading,
+        hasError: !!error,
+        activeOfferId,
+        hasActiveSummary: !!activeSummary,
+        isActiveSummaryLoading,
+    });
+    return result;
 }

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

@@ -42,6 +42,11 @@ interface TagadaContextValue extends TagadaState {
 }
 interface TagadaProviderProps {
     children: ReactNode;
+    /**
+     * Optional environment override.
+     * ⚠️ Leave undefined for automatic runtime detection (recommended).
+     * Only set this if you need to force a specific environment for testing.
+     */
     environment?: Environment;
     customApiConfig?: Partial<EnvironmentConfig>;
     debugMode?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/plugin-sdk",
-  "version": "2.8.9",
+  "version": "2.8.10",
   "description": "Modern React SDK for building Tagada Pay plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",