@tagadapay/plugin-sdk 3.0.12 → 3.0.15

package/dist/react/types.d.ts

@@ -7,7 +7,9 @@ export interface ApiConfig {
     endpoints: {
         checkout: {
             sessionInit: string;
+            sessionInitAsync: string;
             sessionStatus: string;
+            asyncStatus: string;
         };
         customer: {
             profile: string;

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

@@ -58,6 +58,7 @@ export declare class TagadaClient {
     private tokenPromise;
     private tokenResolver;
     private boundHandleStorageChange;
+    private boundHandlePageshow;
     private readonly config;
     private instanceId;
     private isInitializingSession;
@@ -101,6 +102,10 @@ export declare class TagadaClient {
      * Initialize token and session
      */
     private initializeToken;
+    /**
+     * Normal token initialization flow (no cross-domain handoff)
+     */
+    private fallbackToNormalFlow;
     /**
      * Set token and resolve waiting requests
      */

package/dist/v2/core/client.js

@@ -8,6 +8,7 @@ import { decodeJWTClient, isTokenExpired } from './utils/jwtDecoder';
 import { loadPluginConfig } from './utils/pluginConfig';
 import { handlePreviewMode, isDraftMode, setDraftMode } from './utils/previewMode';
 import { getClientToken, setClientToken } from './utils/tokenStorage';
+import { shouldResolveAuthCode, resolveAuthHandoff } from './utils/authHandoff';
 export class TagadaClient {
     constructor(config = {}) {
         /**
@@ -25,9 +26,36 @@ export class TagadaClient {
         this.config = config;
         this.instanceId = Math.random().toString(36).substr(2, 9);
         this.boundHandleStorageChange = this.handleStorageChange.bind(this);
-        if (this.config.debugMode) {
-            console.log(`[TagadaClient ${this.instanceId}] Initializing...`);
-        }
+        this.boundHandlePageshow = (event) => {
+            if (event.persisted) {
+                if (this.state.debugMode) {
+                    console.log(`[TagadaClient ${this.instanceId}] Page restored from BFcache (back button), re-initializing funnel...`);
+                }
+                // If we have an active session and store, we only need to re-initialize the funnel
+                // This ensures tracking is correct and the session is fresh on the backend
+                if (this.funnel && this.state.session && this.state.store) {
+                    this.funnel.resetInitialization();
+                    const accountId = this.getAccountId();
+                    const urlParams = new URLSearchParams(typeof window !== 'undefined' ? window.location.search : '');
+                    const funnelId = urlParams.get('funnelId') || undefined;
+                    this.funnel.autoInitialize({ customerId: this.state.session.customerId, sessionId: this.state.session.sessionId }, { id: this.state.store.id, accountId }, funnelId).catch((err) => {
+                        console.error('[TagadaClient] Funnel re-initialization failed:', err);
+                    });
+                }
+                else {
+                    // If state is missing, perform a full initialization
+                    this.sessionInitRetryCount = 0;
+                    this.initialize();
+                }
+            }
+        };
+        console.log(`[TagadaClient ${this.instanceId}] Initializing...`);
+        console.log(`[TagadaClient ${this.instanceId}] Config:`, {
+            debugMode: config.debugMode,
+            hasRawPluginConfig: !!config.rawPluginConfig,
+            rawPluginConfig: config.rawPluginConfig,
+            features: config.features,
+        });
         // Handle preview mode FIRST - clears state if needed
         // This ensures clean state when CRM previews pages
         const previewModeActive = handlePreviewMode(this.config.debugMode);
@@ -77,10 +105,14 @@ export class TagadaClient {
             isInitialized: false,
             isSessionInitialized: false,
             pluginConfig: { basePath: '/', config: {} },
-            pluginConfigLoading: !config.rawPluginConfig,
+            pluginConfigLoading: true, // Always true - loadPluginConfig will process rawPluginConfig
             debugMode: config.debugMode ?? env !== 'production',
             token: null,
         };
+        console.log(`[TagadaClient ${this.instanceId}] Initial state:`, {
+            pluginConfigLoading: this.state.pluginConfigLoading,
+            hasRawPluginConfig: !!config.rawPluginConfig,
+        });
         // Initialize API Client
         this.apiClient = new ApiClient({
             baseURL: envConfig.apiConfig.baseUrl,
@@ -96,6 +128,9 @@ export class TagadaClient {
                 pluginConfig: this.state.pluginConfig,
                 environment: this.state.environment,
                 autoRedirect: funnelConfig.autoRedirect,
+                // Pass funnelId and stepId from rawPluginConfig to enable config-based initialization
+                funnelId: config.rawPluginConfig?.funnelId,
+                stepId: config.rawPluginConfig?.stepId,
             });
         }
         // Setup token waiting mechanism
@@ -103,6 +138,7 @@ export class TagadaClient {
         // Listen for storage changes (cross-tab sync)
         if (typeof window !== 'undefined') {
             window.addEventListener('storage', this.boundHandleStorageChange);
+            window.addEventListener('pageshow', this.boundHandlePageshow);
         }
         // Setup config hot-reload listener (for live config editing)
         this.setupConfigHotReload();
@@ -115,6 +151,7 @@ export class TagadaClient {
     destroy() {
         if (typeof window !== 'undefined') {
             window.removeEventListener('storage', this.boundHandleStorageChange);
+            window.removeEventListener('pageshow', this.boundHandlePageshow);
         }
         if (this.state.debugMode) {
             console.log(`[TagadaClient ${this.instanceId}] Destroyed`);
@@ -206,11 +243,19 @@ export class TagadaClient {
      * Load plugin configuration
      */
     async initializePluginConfig() {
-        if (!this.state.pluginConfigLoading)
+        console.log(`[TagadaClient ${this.instanceId}] initializePluginConfig called`, {
+            pluginConfigLoading: this.state.pluginConfigLoading,
+            hasRawPluginConfig: !!this.config.rawPluginConfig,
+        });
+        if (!this.state.pluginConfigLoading) {
+            console.log(`[TagadaClient ${this.instanceId}] Plugin config already loading or loaded, skipping...`);
             return;
+        }
         try {
             const configVariant = this.config.localConfig || 'default';
+            console.log(`[TagadaClient ${this.instanceId}] Loading plugin config with variant: ${configVariant}`);
             const config = await loadPluginConfig(configVariant, this.config.rawPluginConfig);
+            console.log(`[TagadaClient ${this.instanceId}] Plugin config loaded:`, config);
             this.updateState({
                 pluginConfig: config,
                 pluginConfigLoading: false,
@@ -222,9 +267,6 @@ export class TagadaClient {
                     environment: this.state.environment,
                 });
             }
-            if (this.state.debugMode) {
-                console.log('[TagadaClient] Plugin config loaded:', config);
-            }
         }
         catch (error) {
             console.error('[TagadaClient] Failed to load plugin config:', error);
@@ -238,16 +280,69 @@ export class TagadaClient {
      * Initialize token and session
      */
     async initializeToken() {
+        // 🔐 PRIORITY 1: Check for authCode (cross-domain handoff)
+        // This ALWAYS takes precedence over existing tokens
+        if (shouldResolveAuthCode()) {
+            const storeId = this.state.pluginConfig.storeId;
+            if (!storeId) {
+                console.error('[TagadaClient] Cannot resolve authCode: storeId not found in config');
+                return this.fallbackToNormalFlow();
+            }
+            console.log(`[TagadaClient ${this.instanceId}] 🔐 Cross-domain auth detected, resolving...`);
+            try {
+                const authCode = new URLSearchParams(window.location.search).get('authCode');
+                if (!authCode) {
+                    return this.fallbackToNormalFlow();
+                }
+                // Resolve the handoff
+                const handoffData = await resolveAuthHandoff(authCode, storeId, this.state.environment.apiConfig.baseUrl, this.state.debugMode);
+                console.log(`[TagadaClient ${this.instanceId}] ✅ Auth handoff resolved:`, {
+                    customerId: handoffData.customer.id,
+                    role: handoffData.customer.role,
+                    hasContext: Object.keys(handoffData.context).length > 0,
+                });
+                // Set the new token (already stored by resolveAuthHandoff)
+                this.setToken(handoffData.token);
+                // Decode session from token
+                const decodedSession = decodeJWTClient(handoffData.token);
+                if (decodedSession) {
+                    this.updateState({ session: decodedSession });
+                    await this.initializeSession(decodedSession);
+                    // If context has funnelSessionId, restore it
+                    if (handoffData.context?.funnelSessionId && this.funnel) {
+                        if (this.state.debugMode) {
+                            console.log(`[TagadaClient ${this.instanceId}] Restoring funnel session from handoff context:`, handoffData.context.funnelSessionId);
+                        }
+                        // The funnel client will pick this up during auto-initialization
+                    }
+                }
+                else {
+                    console.error('[TagadaClient] Failed to decode token from handoff');
+                    this.updateState({ isInitialized: true, isLoading: false });
+                }
+                return; // ✅ Auth handoff resolved successfully, exit early
+            }
+            catch (error) {
+                console.error(`[TagadaClient ${this.instanceId}] ❌ Auth handoff failed, falling back to normal flow:`, error);
+                // Fall through to normal initialization
+            }
+        }
+        // Continue with normal flow if no authCode or resolution failed
+        await this.fallbackToNormalFlow();
+    }
+    /**
+     * Normal token initialization flow (no cross-domain handoff)
+     */
+    async fallbackToNormalFlow() {
         // Check for existing token in URL or storage
         const existingToken = getClientToken();
         const urlParams = new URLSearchParams(typeof window !== 'undefined' ? window.location.search : '');
         const queryToken = urlParams.get('token');
-        if (this.state.debugMode) {
-            console.log(`[TagadaClient ${this.instanceId}] Initializing token...`, {
-                hasExistingToken: !!existingToken,
-                hasQueryToken: !!queryToken
-            });
-        }
+        console.log(`[TagadaClient ${this.instanceId}] Initializing token (normal flow)...`, {
+            hasExistingToken: !!existingToken,
+            hasQueryToken: !!queryToken,
+            storeId: this.state.pluginConfig.storeId,
+        });
         let tokenToUse = null;
         let shouldPersist = false;
         if (queryToken) {
@@ -280,13 +375,15 @@ export class TagadaClient {
         else {
             // Create anonymous token
             const storeId = this.state.pluginConfig.storeId;
+            console.log(`[TagadaClient ${this.instanceId}] No existing token, creating anonymous token...`, {
+                hasStoreId: !!storeId,
+                storeId,
+            });
             if (storeId) {
-                if (this.state.debugMode) {
-                    console.log(`[TagadaClient ${this.instanceId}] Creating anonymous token for store:`, storeId);
-                }
                 await this.createAnonymousToken(storeId);
             }
             else {
+                console.warn(`[TagadaClient ${this.instanceId}] No storeId in plugin config, skipping anonymous token creation`);
                 this.updateState({ isInitialized: true, isLoading: false });
             }
         }
@@ -404,12 +501,22 @@ export class TagadaClient {
                 osVersion: deviceInfo.userAgent.os.version,
                 deviceType: deviceInfo.userAgent.device?.type,
                 deviceModel: deviceInfo.userAgent.device?.model,
+                deviceVendor: deviceInfo.userAgent.device?.vendor,
+                userAgent: deviceInfo.userAgent.name,
+                engineName: deviceInfo.userAgent.engine.name,
+                engineVersion: deviceInfo.userAgent.engine.version,
+                cpuArchitecture: deviceInfo.userAgent.cpu.architecture,
+                isBot: deviceInfo.flags?.isBot ?? false,
+                isChromeFamily: deviceInfo.flags?.isChromeFamily ?? false,
+                isStandalonePWA: deviceInfo.flags?.isStandalonePWA ?? false,
+                isAppleSilicon: deviceInfo.flags?.isAppleSilicon ?? false,
                 screenWidth: deviceInfo.screenResolution.width,
                 screenHeight: deviceInfo.screenResolution.height,
                 timeZone: deviceInfo.timeZone,
                 draft, // 🎯 Pass draft mode to session init
+                fetchMessages: false,
             };
-            const response = await this.apiClient.post('/api/v1/cms/session/init', sessionInitData);
+            const response = await this.apiClient.post('/api/v1/cms/session/v2/init', sessionInitData);
             // Success - reset error tracking
             this.lastSessionInitError = null;
             this.sessionInitRetryCount = 0;
@@ -451,14 +558,16 @@ export class TagadaClient {
             };
             this.updateState({ store: storeConfig });
         }
-        // Update Locale
-        const localeConfig = {
-            locale: response.locale,
-            language: response.locale.split('-')[0],
-            region: response.locale.split('-')[1] ?? 'US',
-            messages: response.messages ?? {},
-        };
-        this.updateState({ locale: localeConfig });
+        // Update Locale (only if provided - V2 endpoint doesn't return locale)
+        if (response.locale) {
+            const localeConfig = {
+                locale: response.locale,
+                language: response.locale.split('-')[0],
+                region: response.locale.split('-')[1] ?? 'US',
+                messages: response.messages ?? {},
+            };
+            this.updateState({ locale: localeConfig });
+        }
         // Update Currency
         if (response.store) {
             const currencyConfig = {

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

@@ -37,7 +37,9 @@ export const ENVIRONMENT_CONFIGS = {
         endpoints: {
             checkout: {
                 sessionInit: '/api/v1/checkout/session/init',
+                sessionInitAsync: '/api/v1/checkout/session/init-async',
                 sessionStatus: '/api/v1/checkout/session/status',
+                asyncStatus: '/api/public/v1/checkout/async-status',
             },
             customer: {
                 profile: '/api/v1/customer/profile',
@@ -53,7 +55,9 @@ export const ENVIRONMENT_CONFIGS = {
         endpoints: {
             checkout: {
                 sessionInit: '/api/v1/checkout/session/init',
+                sessionInitAsync: '/api/v1/checkout/session/init-async',
                 sessionStatus: '/api/v1/checkout/session/status',
+                asyncStatus: '/api/public/v1/checkout/async-status',
             },
             customer: {
                 profile: '/api/v1/customer/profile',
@@ -69,7 +73,9 @@ export const ENVIRONMENT_CONFIGS = {
         endpoints: {
             checkout: {
                 sessionInit: '/api/v1/checkout/session/init',
+                sessionInitAsync: '/api/v1/checkout/session/init-async',
                 sessionStatus: '/api/v1/checkout/session/status',
+                asyncStatus: '/api/public/v1/checkout/async-status',
             },
             customer: {
                 profile: '/api/v1/customer/profile',

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

@@ -13,6 +13,14 @@ export interface FunnelClientConfig {
      * Set to false if you want to handle navigation manually
      */
     autoRedirect?: boolean;
+    /**
+     * Override funnelId from rawPluginConfig
+     */
+    funnelId?: string;
+    /**
+     * Override stepId from rawPluginConfig
+     */
+    stepId?: string;
 }
 export interface FunnelState {
     context: SimpleFunnelContext | null;
@@ -42,6 +50,15 @@ export declare class FunnelClient {
      * Get current state
      */
     getState(): FunnelState;
+    /**
+     * Get the session ID that would be used for initialization (URL params or cookie)
+     * This allows getting the session ID even before the client is fully initialized.
+     */
+    getDetectedSessionId(): string | null;
+    /**
+     * Reset initialization state (used for back-button restores)
+     */
+    resetInitialization(): void;
     /**
      * Initialize session with automatic detection (cookies, URL, etc.)
      */
@@ -64,8 +81,17 @@ export declare class FunnelClient {
     }, funnelId?: string, entryStepId?: string): Promise<SimpleFunnelContext<{}>>;
     /**
      * Navigate
+     * @param event - Navigation event/action
+     * @param options - Navigation options
+     * @param options.fireAndForget - If true, queues navigation to QStash and returns immediately without waiting for result
+     * @param options.customerTags - Customer tags to set (merged with existing customer tags)
+     * @param options.deviceId - Device ID for geo/device tag enrichment (optional, rarely needed)
      */
-    navigate(event: FunnelAction): Promise<FunnelNavigationResult>;
+    navigate(event: FunnelAction, options?: {
+        fireAndForget?: boolean;
+        customerTags?: string[];
+        deviceId?: string;
+    }): Promise<FunnelNavigationResult>;
     /**
      * Go to a specific step (direct navigation)
      */

package/dist/v2/core/funnelClient.js

@@ -92,6 +92,37 @@ export class FunnelClient {
     getState() {
         return this.state;
     }
+    /**
+     * Get the session ID that would be used for initialization (URL params or cookie)
+     * This allows getting the session ID even before the client is fully initialized.
+     */
+    getDetectedSessionId() {
+        // Priority 1: Already initialized session
+        if (this.state.context?.sessionId) {
+            return this.state.context.sessionId;
+        }
+        if (typeof window === 'undefined')
+            return null;
+        // Priority 2: URL params
+        const params = new URLSearchParams(window.location.search);
+        const urlSessionId = params.get('funnelSessionId');
+        if (urlSessionId)
+            return urlSessionId;
+        // Priority 3: Cookie
+        return getFunnelSessionCookie() || null;
+    }
+    /**
+     * Reset initialization state (used for back-button restores)
+     */
+    resetInitialization() {
+        this.initializationAttempted = false;
+        this.isInitializing = false;
+        // Clear context to force a fresh autoInitialize call to hit the backend
+        this.updateState({
+            context: null,
+            isInitialized: false,
+        });
+    }
     /**
      * Initialize session with automatic detection (cookies, URL, etc.)
      */
@@ -106,31 +137,33 @@ export class FunnelClient {
         this.isInitializing = true;
         this.updateState({ isLoading: true, error: null });
         try {
-            // URL params
+            // 🎯 Get detected session ID
+            const existingSessionId = this.getDetectedSessionId();
+            // URL params for funnelId
             const params = new URLSearchParams(typeof window !== 'undefined' ? window.location.search : '');
             const urlFunnelId = params.get('funnelId');
             const effectiveFunnelId = urlFunnelId || funnelId;
-            let existingSessionId = params.get('funnelSessionId');
-            // Cookie fallback
-            if (!existingSessionId) {
-                existingSessionId = getFunnelSessionCookie() || null;
-            }
             // 🎯 Read funnel tracking data from injected HTML
             const injectedFunnelId = getAssignedFunnelId(); // Funnel ID from server
             const funnelVariantId = getAssignedFunnelVariant(); // A/B test variant ID
-            const funnelStepId = getAssignedFunnelStep(); // Current step ID
+            const injectedStepId = getAssignedFunnelStep(); // Current step ID
             // 🎯 Get SDK override parameters (draft, funnelTracking, etc.)
             const sdkParams = getSDKParams();
-            // Prefer injected funnelId over URL/prop funnelId (more reliable)
-            const finalFunnelId = injectedFunnelId || effectiveFunnelId;
+            // Priority: config override > injected > URL/prop
+            const finalFunnelId = this.config.funnelId || injectedFunnelId || effectiveFunnelId;
+            const finalStepId = this.config.stepId || injectedStepId;
             if (this.config.debugMode) {
                 console.log('🚀 [FunnelClient] Auto-initializing...', {
                     existingSessionId,
                     effectiveFunnelId: finalFunnelId,
                     funnelVariantId, // 🎯 Log variant ID for debugging
-                    funnelStepId, // 🎯 Log step ID for debugging
+                    funnelStepId: finalStepId, // 🎯 Log step ID for debugging
                     draft: sdkParams.draft, // 🎯 Log draft mode
                     funnelTracking: sdkParams.funnelTracking, // 🎯 Log tracking flag
+                    source: {
+                        funnelId: this.config.funnelId ? 'config' : injectedFunnelId ? 'injected' : effectiveFunnelId ? 'url/prop' : 'none',
+                        stepId: this.config.stepId ? 'config' : injectedStepId ? 'injected' : 'none',
+                    },
                 });
             }
             // Note: We proceed even without funnelId/sessionId - the backend will create a new anonymous session if needed
@@ -145,7 +178,7 @@ export class FunnelClient {
                 existingSessionId: existingSessionId || undefined,
                 currentUrl: typeof window !== 'undefined' ? window.location.href : undefined,
                 funnelVariantId, // 🎯 Pass A/B test variant ID to backend
-                funnelStepId, // 🎯 Pass step ID to backend
+                funnelStepId: finalStepId, // 🎯 Pass step ID to backend (with config override)
                 draft: sdkParams.draft, // 🎯 Pass draft mode explicitly (more robust than URL parsing)
                 funnelTracking: sdkParams.funnelTracking, // 🎯 Pass funnel tracking flag explicitly
             });
@@ -215,32 +248,100 @@ export class FunnelClient {
     }
     /**
      * Navigate
+     * @param event - Navigation event/action
+     * @param options - Navigation options
+     * @param options.fireAndForget - If true, queues navigation to QStash and returns immediately without waiting for result
+     * @param options.customerTags - Customer tags to set (merged with existing customer tags)
+     * @param options.deviceId - Device ID for geo/device tag enrichment (optional, rarely needed)
      */
-    async navigate(event) {
+    async navigate(event, options) {
         if (!this.state.context?.sessionId)
             throw new Error('No active session');
         this.updateState({ isNavigating: true, isLoading: true });
         try {
+            // Get current funnel state from injected HTML/meta tags
+            let funnelVariantId = getAssignedFunnelVariant();
+            let funnelStepId = getAssignedFunnelStep();
+            const currentUrl = typeof window !== 'undefined' ? window.location.href : undefined;
+            // ✅ FALLBACK: Use config values if injection not available (e.g., on Shopify storefront)
+            if (!funnelStepId && this.config.stepId) {
+                funnelStepId = this.config.stepId;
+                if (this.config.debugMode) {
+                    console.log('🔍 [FunnelClient.navigate] Using stepId from config (no injection):', funnelStepId);
+                }
+            }
+            if (!funnelVariantId && this.config.variantId) {
+                funnelVariantId = this.config.variantId;
+                if (this.config.debugMode) {
+                    console.log('🔍 [FunnelClient.navigate] Using variantId from config (no injection):', funnelVariantId);
+                }
+            }
+            // ✅ DEBUG: Log what we're sending
+            if (this.config.debugMode) {
+                console.log('🔍 [FunnelClient.navigate] Sending to backend:', {
+                    sessionId: this.state.context.sessionId,
+                    currentUrl,
+                    funnelStepId: funnelStepId || '(not found)',
+                    funnelVariantId: funnelVariantId || '(not found)',
+                    hasInjectedStepId: !!getAssignedFunnelStep(),
+                    hasInjectedVariantId: !!getAssignedFunnelVariant(),
+                    usedConfigFallback: !getAssignedFunnelStep() && !!this.config.stepId,
+                    customerTags: options?.customerTags || '(none)',
+                    deviceId: options?.deviceId || '(none)',
+                });
+            }
+            const fireAndForget = options?.fireAndForget || false;
             const response = await this.resource.navigate({
                 sessionId: this.state.context.sessionId,
-                event
+                event,
+                currentUrl,
+                funnelStepId,
+                funnelVariantId,
+                fireAndForget,
+                customerTags: options?.customerTags,
+                deviceId: options?.deviceId,
             });
-            if (response.success && response.result) {
-                // Refresh session to get updated context
-                await this.refreshSession();
+            if (!response.success || !response.result) {
+                throw new Error(response.error || 'Navigation failed');
+            }
+            const result = response.result;
+            // 🔥 Fire-and-forget mode: Just return acknowledgment, skip everything else
+            if (result.queued) {
                 this.updateState({ isNavigating: false, isLoading: false });
-                const result = response.result;
-                // Auto-redirect if enabled (default: true) and result has a URL
-                const shouldAutoRedirect = this.config.autoRedirect !== false; // Default to true
-                if (shouldAutoRedirect && result?.url && typeof window !== 'undefined') {
+                // Update session ID if it changed (session recovery)
+                if (result.sessionId && result.sessionId !== this.state.context?.sessionId) {
                     if (this.config.debugMode) {
-                        console.log('🚀 [FunnelClient] Auto-redirecting to:', result.url);
+                        console.log(`🔥 [FunnelClient] Session ID updated: ${this.state.context?.sessionId} → ${result.sessionId}`);
+                    }
+                    // Update context session ID
+                    if (this.state.context) {
+                        this.state.context.sessionId = result.sessionId;
                     }
-                    window.location.href = result.url;
+                }
+                if (this.config.debugMode) {
+                    console.log('🔥 [FunnelClient] Navigation queued (fire-and-forget mode)');
                 }
                 return result;
             }
-            throw new Error(response.error || 'Navigation failed');
+            // Normal navigation: handle redirect
+            const shouldAutoRedirect = this.config.autoRedirect !== false; // Default to true
+            // Skip refreshSession if auto-redirecting (next page will initialize with fresh state)
+            // Only refresh if staying on same page (autoRedirect: false)
+            if (!shouldAutoRedirect) {
+                if (this.config.debugMode) {
+                    console.log('🔄 [FunnelClient] Refreshing session (no auto-redirect)');
+                }
+                await this.refreshSession();
+            }
+            this.updateState({ isNavigating: false, isLoading: false });
+            // Auto-redirect if enabled and result has a URL
+            if (shouldAutoRedirect && result?.url && typeof window !== 'undefined') {
+                if (this.config.debugMode) {
+                    console.log('🚀 [FunnelClient] Auto-redirecting to:', result.url, '(skipped session refresh - next page will initialize)');
+                }
+                window.location.href = result.url;
+            }
+            return result;
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));

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

@@ -180,17 +180,92 @@ export declare class CheckoutResource {
     private apiClient;
     constructor(apiClient: ApiClient);
     /**
-     * Initialize a new checkout session
+     * Initialize a new checkout session (sync mode)
+     * Response time: 2-5 seconds (full processing)
      */
     initCheckout(params: CheckoutInitParams): Promise<{
         checkoutUrl: string;
         checkoutSession: CheckoutSession;
         checkoutToken: string;
     }>;
+    /**
+     * Initialize a new checkout session (async mode) ⚡
+     * Response time: ~50ms (20-50x faster!)
+     *
+     * Returns checkoutToken immediately, background job completes processing.
+     * Use getCheckout() to fetch full session data - it auto-waits for completion.
+     *
+     * @example
+     * // Fast init
+     * const { checkoutToken } = await checkout.initCheckoutAsync(params);
+     *
+     * // Redirect user immediately
+     * window.location.href = `/checkout/${checkoutToken}/op`;
+     *
+     * // By the time page loads, background processing is usually complete
+     */
+    initCheckoutAsync(params: CheckoutInitParams): Promise<{
+        checkoutToken: string;
+        customerId: string;
+        status: 'processing';
+    }>;
+    /**
+     * Preload checkout session (ultra-fast background pre-computation) ⚡⚡⚡
+     *
+     * This is the recommended way to handle cart changes or "Buy Now" intent.
+     * It pre-computes everything (checkoutToken, navigation URL, CMS session)
+     * before the user even clicks the checkout button.
+     *
+     * The SDK automatically gets funnelSessionId from FunnelClient if provided.
+     * Only FunnelClient knows how to properly extract funnelSessionId (from state, URL, cookies, etc.)
+     *
+     * @param params - Checkout and funnel parameters
+     * @param getFunnelSessionId - Optional function to get funnelSessionId from FunnelClient
+     *                             This maintains separation of concerns - only FunnelClient knows how to get it
+     *
+     * @returns { checkoutToken, customerId, navigationUrl }
+     */
+    preloadCheckout(params: CheckoutInitParams & {
+        funnelSessionId?: string;
+        currentUrl?: string;
+        funnelStepId?: string;
+        funnelVariantId?: string;
+        navigationEvent?: string | {
+            type: string;
+            data?: any;
+        };
+        navigationOptions?: any;
+    }, getFunnelSessionId?: () => string | null | undefined): Promise<{
+        checkoutToken: string;
+        customerId: string;
+        navigationUrl: string | null;
+        funnelStepId?: string;
+    }>;
+    /**
+     * Check async checkout processing status (instant, no waiting)
+     * Perfect for polling or checking if background job completed
+     */
+    checkAsyncStatus(checkoutToken: string): Promise<{
+        isAsync: boolean;
+        isProcessing: boolean;
+        isComplete: boolean;
+        hasError: boolean;
+        error?: string;
+    }>;
     /**
      * Get checkout session by token
+     *
+     * SDK automatically waits for async completion (skipAsyncWait=false) for seamless UX.
+     * This ensures async checkout sessions are fully processed before returning data.
+     *
+     * If you need to skip waiting (e.g., for manual polling), use getCheckoutRaw() instead.
      */
     getCheckout(checkoutToken: string, currency?: string): Promise<CheckoutData>;
+    /**
+     * Get checkout session by token without waiting for async completion
+     * Useful for manual polling scenarios
+     */
+    getCheckoutRaw(checkoutToken: string, currency?: string): Promise<CheckoutData>;
     /**
      * Update checkout address
      */