@tagadapay/plugin-sdk 3.0.12 → 3.0.15

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

@@ -7,20 +7,105 @@ 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);
+    }
+    /**
+     * 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 }
+     */
+    async preloadCheckout(params, getFunnelSessionId) {
+        // ⚡ GET FUNNEL SESSION ID: Only FunnelClient knows how to properly get it
+        // Priority: explicit param > FunnelClient > backend fallback (via currentUrl)
+        let funnelSessionId = params.funnelSessionId;
+        if (!funnelSessionId && getFunnelSessionId) {
+            // Let FunnelClient handle extraction (from state, URL, cookies, etc.)
+            funnelSessionId = getFunnelSessionId() || undefined;
+        }
+        // Format navigationEvent if it's a string
+        const navigationEvent = typeof params.navigationEvent === 'string'
+            ? { type: params.navigationEvent }
+            : params.navigationEvent;
+        // Build request - backend will also try to extract from currentUrl if not provided
+        const requestParams = {
+            ...params,
+            ...(funnelSessionId && { funnelSessionId }),
+            ...(navigationEvent && { navigationEvent }),
+            // Ensure currentUrl is always set for backend extraction fallback
+            currentUrl: params.currentUrl || (typeof window !== 'undefined' ? window.location.href : undefined),
+        };
+        return this.apiClient.post('/api/v1/checkout/session/preload', requestParams);
+    }
+    /**
+     * 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
@@ -421,6 +430,7 @@ export interface SimpleFunnelContext<TCustom = {}> {
      * For backward compatibility and flexible unstructured data
      */
     metadata?: Record<string, any>;
+    script?: string;
 }
 export interface FunnelInitializeRequest {
     cmsSession: {
@@ -480,11 +490,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 +533,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;
+}

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

@@ -1,16 +1,27 @@
 export interface DeviceInfo {
     userAgent: {
+        name: string;
         browser: {
+            major: string;
             name: string;
             version: string;
+            type?: string;
         };
         os: {
             name: string;
             version: string;
         };
         device?: {
-            type: string;
-            model: string;
+            model?: string;
+            type?: string;
+            vendor?: string;
+        };
+        engine: {
+            name: string;
+            version: string;
+        };
+        cpu: {
+            architecture: string;
         };
     };
     screenResolution: {
@@ -18,13 +29,19 @@ export interface DeviceInfo {
         height: number;
     };
     timeZone: string;
+    flags?: {
+        isBot: boolean;
+        isChromeFamily: boolean;
+        isStandalonePWA: boolean;
+        isAppleSilicon: boolean;
+    };
 }
 /**
  * Get browser locale
  */
 export declare function getBrowserLocale(): string;
 /**
- * Collect all device information
+ * Collect all device information using UAParser
  */
 export declare function collectDeviceInfo(): DeviceInfo;
 /**