@tagadapay/plugin-sdk 3.0.9 → 3.0.14

package/dist/v2/core/funnelClient.js

@@ -118,19 +118,24 @@ export class FunnelClient {
             // 🎯 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 +150,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 +220,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,60 @@ 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';
+    }>;
+    /**
+     * 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
      */

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

@@ -7,20 +7,67 @@ export class CheckoutResource {
         this.apiClient = apiClient;
     }
     /**
-     * Initialize a new checkout session
+     * Initialize a new checkout session (sync mode)
+     * Response time: 2-5 seconds (full processing)
      */
     async initCheckout(params) {
         // Pass all params including customerId to prevent duplicate customer creation
         return this.apiClient.post('/api/v1/checkout/session/init', params);
     }
+    /**
+     * 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
+     */
+    async initCheckoutAsync(params) {
+        return this.apiClient.post('/api/v1/checkout/session/init-async', params);
+    }
+    /**
+     * Check async checkout processing status (instant, no waiting)
+     * Perfect for polling or checking if background job completed
+     */
+    async checkAsyncStatus(checkoutToken) {
+        return this.apiClient.get(`/api/public/v1/checkout/async-status/${checkoutToken}`);
+    }
     /**
      * 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.
      */
     async getCheckout(checkoutToken, currency) {
         const queryParams = new URLSearchParams();
         if (currency) {
             queryParams.set('currency', currency);
         }
+        // SDK explicitly waits for async completion (default is skip=true for retro compat)
+        queryParams.set('skipAsyncWait', 'false');
+        const url = `/api/v1/checkout-sessions/${checkoutToken}/v2${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get checkout session by token without waiting for async completion
+     * Useful for manual polling scenarios
+     */
+    async getCheckoutRaw(checkoutToken, currency) {
+        const queryParams = new URLSearchParams();
+        if (currency) {
+            queryParams.set('currency', currency);
+        }
+        queryParams.set('skipAsyncWait', 'true');
         const url = `/api/v1/checkout-sessions/${checkoutToken}/v2${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
         return this.apiClient.get(url);
     }

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

@@ -343,16 +343,25 @@ export interface FunnelNavigationAction {
     data?: any;
 }
 export interface FunnelNavigationResult {
-    stepId: string;
+    stepId?: string;
     url?: string;
-    action: FunnelNavigationAction;
-    context: SimpleFunnelContext;
+    action?: FunnelNavigationAction;
+    context?: SimpleFunnelContext;
     tracking?: {
         from: string;
         to: string;
         event: string;
         timestamp: string;
     };
+    /**
+     * Fire-and-forget response: indicates navigation was queued
+     * When true, stepId, url, action, and context will be undefined
+     */
+    queued?: boolean;
+    /**
+     * Session ID (may be different if session was recovered)
+     */
+    sessionId?: string;
 }
 /**
  * Funnel context available to plugins
@@ -480,11 +489,37 @@ export interface FunnelNavigateRequest {
      * If session is not found and funnelId is provided, a new session will be created
      */
     funnelId?: string;
+    /**
+     * Funnel step ID (from SDK injection/URL params)
+     * Used to sync session state before navigation
+     */
+    funnelStepId?: string;
+    /**
+     * Funnel variant ID (from SDK injection/URL params for A/B testing)
+     * Used to sync session state before navigation
+     */
+    funnelVariantId?: string;
+    /**
+     * Fire and forget mode - queues navigation to QStash and returns immediately
+     * No response data needed, just acknowledgment that request was queued
+     * When true, result will only contain queued status and sessionId (no URL or stepId)
+     */
+    fireAndForget?: boolean;
+    /**
+     * ✅ Customer tags to set (merged with existing customer tags)
+     * @example ['segment:vip', 'cart_value:high']
+     */
+    customerTags?: string[];
+    /**
+     * ✅ Device ID for geo/device tag enrichment (optional)
+     * @example 'dev_abc123xyz'
+     */
+    deviceId?: string;
 }
 export interface FunnelNavigateResponse {
     success: boolean;
     result?: {
-        stepId: string;
+        stepId?: string;
         url?: string;
         /**
          * New session ID if session was recovered (expired/removed)
@@ -497,6 +532,11 @@ export interface FunnelNavigateResponse {
             event: string;
             timestamp: string;
         };
+        /**
+         * Fire-and-forget response: indicates navigation was queued
+         * When present, stepId and url will be undefined
+         */
+        queued?: boolean;
     };
     error?: string;
 }

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

@@ -303,6 +303,32 @@ export declare class OffersResource {
         checkoutSessionId?: string;
         customerId?: string;
     }>;
+    /**
+     * Transform offer to 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 transform
+     * const { checkoutToken } = await offers.toCheckoutAsync(offerId, currency, lineItems, returnUrl, mainOrderId);
+     *
+     * // Redirect user immediately
+     * window.location.href = `/checkout/${checkoutToken}/op`;
+     *
+     * // By the time page loads, background processing is usually complete
+     */
+    toCheckoutAsync(offerId: string, currency?: string, lineItems?: Array<{
+        lineItemId?: string;
+        productId?: string;
+        variantId: string;
+        quantity: number;
+    }>, returnUrl?: string, mainOrderId?: string): Promise<{
+        checkoutToken: string;
+        customerId: string;
+        status: 'processing';
+    }>;
     /**
      * @deprecated Use transformToCheckoutSession instead
      * Transform offer to checkout session with dynamic variant selection

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

@@ -202,6 +202,43 @@ export class OffersResource {
             customerId: response.customerId,
         };
     }
+    /**
+     * Transform offer to 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 transform
+     * const { checkoutToken } = await offers.toCheckoutAsync(offerId, currency, lineItems, returnUrl, mainOrderId);
+     *
+     * // Redirect user immediately
+     * window.location.href = `/checkout/${checkoutToken}/op`;
+     *
+     * // By the time page loads, background processing is usually complete
+     */
+    async toCheckoutAsync(offerId, currency = 'USD', lineItems, returnUrl, mainOrderId) {
+        console.log('🛒 [OffersResource] Calling to-checkout-async API:', {
+            offerId,
+            currency,
+            lineItems,
+            returnUrl,
+            mainOrderId,
+            endpoint: `/api/v1/offers/${offerId}/to-checkout-async`,
+        });
+        const response = await this.apiClient.post(`/api/v1/offers/${offerId}/to-checkout-async`, {
+            offerId,
+            lineItems: lineItems?.map(item => ({
+                variantId: item.variantId,
+                quantity: item.quantity,
+            })) || [],
+            returnUrl: returnUrl || (typeof window !== 'undefined' ? window.location.href : ''),
+            mainOrderId: mainOrderId || '',
+        });
+        console.log('📥 [OffersResource] To-checkout-async API response:', response);
+        return response;
+    }
     /**
      * @deprecated Use transformToCheckoutSession instead
      * Transform offer to checkout session with dynamic variant selection

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

@@ -7,7 +7,9 @@ export interface ApiConfig {
     endpoints: {
         checkout: {
             sessionInit: string;
+            sessionInitAsync: string;
             sessionStatus: string;
+            asyncStatus: string;
         };
         customer: {
             profile: string;
@@ -262,7 +264,7 @@ export interface CustomerInfos {
 }
 export interface SessionInitResponse {
     store: Store;
-    locale: string;
+    locale?: string;
     messages?: Record<string, string>;
     customer?: Customer;
     session?: Session;

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

@@ -0,0 +1,60 @@
+/**
+ * Cross-Domain Auth Handoff Utilities
+ *
+ * Handles automatic resolution of authCode query parameters for seamless
+ * cross-domain authentication.
+ *
+ * Flow:
+ * 1. Check URL for authCode parameter
+ * 2. If present, resolve it with backend
+ * 3. Store the returned token (overrides any existing token)
+ * 4. Clean the URL (remove authCode)
+ * 5. Return resolved customer and context
+ */
+export interface AuthHandoffResolveResponse {
+    sessionId: string;
+    token: string;
+    customer: {
+        id: string;
+        email?: string;
+        firstName?: string;
+        lastName?: string;
+        role: 'authenticated' | 'anonymous';
+    };
+    context: Record<string, unknown>;
+}
+/**
+ * Check if authCode is present in URL
+ */
+export declare function hasAuthCode(): boolean;
+/**
+ * Get authCode from URL
+ */
+export declare function getAuthCode(): string | null;
+/**
+ * Check if a code has already been resolved
+ */
+export declare function isCodeAlreadyResolved(code: string): boolean;
+/**
+ * Resolve auth handoff and return token + customer info
+ *
+ * This function:
+ * 1. Calls POST /api/v1/cms/auth/resolve-handoff
+ * 2. Stores the returned token (overrides existing)
+ * 3. Cleans the URL (removes authCode)
+ * 4. Returns customer and context data
+ *
+ * 🔒 Deduplication: Multiple calls with the same code will return the same promise
+ * to prevent duplicate API requests (e.g., React StrictMode double-mounting)
+ */
+export declare function resolveAuthHandoff(authCode: string, storeId: string, apiBaseUrl: string, debugMode?: boolean): Promise<AuthHandoffResolveResponse>;
+/**
+ * Remove authCode from URL without page reload
+ * Uses history.replaceState to update URL cleanly
+ */
+export declare function cleanAuthCodeFromUrl(debugMode?: boolean): void;
+/**
+ * Check if we should resolve authCode
+ * Returns true if authCode is present and valid format
+ */
+export declare function shouldResolveAuthCode(): boolean;

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

@@ -0,0 +1,154 @@
+/**
+ * Cross-Domain Auth Handoff Utilities
+ *
+ * Handles automatic resolution of authCode query parameters for seamless
+ * cross-domain authentication.
+ *
+ * Flow:
+ * 1. Check URL for authCode parameter
+ * 2. If present, resolve it with backend
+ * 3. Store the returned token (overrides any existing token)
+ * 4. Clean the URL (remove authCode)
+ * 5. Return resolved customer and context
+ */
+import { setClientToken } from './tokenStorage';
+// Track in-flight and completed resolutions to prevent duplicates
+const resolutionCache = new Map();
+const resolvedCodes = new Set();
+/**
+ * Check if authCode is present in URL
+ */
+export function hasAuthCode() {
+    if (typeof window === 'undefined')
+        return false;
+    const urlParams = new URLSearchParams(window.location.search);
+    return urlParams.has('authCode');
+}
+/**
+ * Get authCode from URL
+ */
+export function getAuthCode() {
+    if (typeof window === 'undefined')
+        return null;
+    const urlParams = new URLSearchParams(window.location.search);
+    return urlParams.get('authCode');
+}
+/**
+ * Check if a code has already been resolved
+ */
+export function isCodeAlreadyResolved(code) {
+    return resolvedCodes.has(code);
+}
+/**
+ * Resolve auth handoff and return token + customer info
+ *
+ * This function:
+ * 1. Calls POST /api/v1/cms/auth/resolve-handoff
+ * 2. Stores the returned token (overrides existing)
+ * 3. Cleans the URL (removes authCode)
+ * 4. Returns customer and context data
+ *
+ * 🔒 Deduplication: Multiple calls with the same code will return the same promise
+ * to prevent duplicate API requests (e.g., React StrictMode double-mounting)
+ */
+export async function resolveAuthHandoff(authCode, storeId, apiBaseUrl, debugMode = false) {
+    // Check if already resolved
+    if (resolvedCodes.has(authCode)) {
+        if (debugMode) {
+            console.log('[AuthHandoff] Code already resolved, skipping duplicate request');
+        }
+        throw new Error('Auth code already resolved');
+    }
+    // Check if resolution is in-flight
+    const inFlightResolution = resolutionCache.get(authCode);
+    if (inFlightResolution) {
+        if (debugMode) {
+            console.log('[AuthHandoff] Resolution already in progress, waiting for existing request');
+        }
+        return inFlightResolution;
+    }
+    if (debugMode) {
+        console.log('[AuthHandoff] Resolving authCode:', authCode.substring(0, 15) + '...');
+    }
+    // Create resolution promise
+    const resolutionPromise = (async () => {
+        try {
+            // Call resolve endpoint (no authentication required)
+            const response = await fetch(`${apiBaseUrl}/api/v1/cms/auth/resolve-handoff`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    code: authCode,
+                    storeId,
+                }),
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({ message: 'Unknown error' }));
+                throw new Error(errorData.message || `Failed to resolve auth handoff: ${response.status}`);
+            }
+            const data = await response.json();
+            if (debugMode) {
+                console.log('[AuthHandoff] ✅ Resolved successfully:', {
+                    customerId: data.customer.id,
+                    role: data.customer.role,
+                    hasContext: Object.keys(data.context).length > 0,
+                });
+            }
+            // Store token (overrides any existing token)
+            if (debugMode) {
+                console.log('[AuthHandoff] Storing new token (overriding existing)');
+            }
+            setClientToken(data.token);
+            // Clean URL (remove authCode parameter)
+            cleanAuthCodeFromUrl(debugMode);
+            // Mark as resolved
+            resolvedCodes.add(authCode);
+            return data;
+        }
+        catch (error) {
+            console.error('[AuthHandoff] ❌ Failed to resolve:', error);
+            throw error;
+        }
+        finally {
+            // Remove from in-flight cache after completion (success or failure)
+            resolutionCache.delete(authCode);
+        }
+    })();
+    // Cache the in-flight promise
+    resolutionCache.set(authCode, resolutionPromise);
+    return resolutionPromise;
+}
+/**
+ * Remove authCode from URL without page reload
+ * Uses history.replaceState to update URL cleanly
+ */
+export function cleanAuthCodeFromUrl(debugMode = false) {
+    if (typeof window === 'undefined')
+        return;
+    const url = new URL(window.location.href);
+    if (url.searchParams.has('authCode')) {
+        url.searchParams.delete('authCode');
+        // Use replaceState to update URL without reload
+        window.history.replaceState({}, '', url.pathname + url.search + url.hash);
+        if (debugMode) {
+            console.log('[AuthHandoff] Cleaned authCode from URL');
+        }
+    }
+}
+/**
+ * Check if we should resolve authCode
+ * Returns true if authCode is present and valid format
+ */
+export function shouldResolveAuthCode() {
+    const authCode = getAuthCode();
+    if (!authCode || !authCode.startsWith('ah_')) {
+        return false;
+    }
+    // Don't resolve if already resolved
+    if (resolvedCodes.has(authCode)) {
+        return false;
+    }
+    return true;
+}