@tagadapay/plugin-sdk 3.0.12 → 3.0.14

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

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

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

@@ -1,91 +1,5 @@
-/**
- * Get basic browser information from user agent
- */
-function getBrowserInfo() {
-    const userAgent = navigator.userAgent;
-    // Chrome
-    if (userAgent.includes('Chrome')) {
-        const match = /Chrome\/(\d+)/.exec(userAgent);
-        return { name: 'Chrome', version: match ? match[1] : 'unknown' };
-    }
-    // Firefox
-    if (userAgent.includes('Firefox')) {
-        const match = /Firefox\/(\d+)/.exec(userAgent);
-        return { name: 'Firefox', version: match ? match[1] : 'unknown' };
-    }
-    // Safari
-    if (userAgent.includes('Safari') && !userAgent.includes('Chrome')) {
-        const match = /Version\/(\d+)/.exec(userAgent);
-        return { name: 'Safari', version: match ? match[1] : 'unknown' };
-    }
-    // Edge
-    if (userAgent.includes('Edge')) {
-        const match = /Edge\/(\d+)/.exec(userAgent);
-        return { name: 'Edge', version: match ? match[1] : 'unknown' };
-    }
-    return { name: 'unknown', version: 'unknown' };
-}
-/**
- * Get basic OS information from user agent
- */
-function getOSInfo() {
-    const userAgent = navigator.userAgent;
-    // Windows
-    if (userAgent.includes('Windows')) {
-        if (userAgent.includes('Windows NT 10.0'))
-            return { name: 'Windows', version: '10' };
-        if (userAgent.includes('Windows NT 6.3'))
-            return { name: 'Windows', version: '8.1' };
-        if (userAgent.includes('Windows NT 6.2'))
-            return { name: 'Windows', version: '8' };
-        if (userAgent.includes('Windows NT 6.1'))
-            return { name: 'Windows', version: '7' };
-        return { name: 'Windows', version: 'unknown' };
-    }
-    // macOS
-    if (userAgent.includes('Mac OS X')) {
-        const match = /Mac OS X (\d+[._]\d+)/.exec(userAgent);
-        return { name: 'macOS', version: match ? match[1].replace('_', '.') : 'unknown' };
-    }
-    // iOS
-    if (userAgent.includes('iPhone') || userAgent.includes('iPad')) {
-        const match = /OS (\d+[._]\d+)/.exec(userAgent);
-        return { name: 'iOS', version: match ? match[1].replace('_', '.') : 'unknown' };
-    }
-    // Android
-    if (userAgent.includes('Android')) {
-        const match = /Android (\d+[.\d]*)/.exec(userAgent);
-        return { name: 'Android', version: match ? match[1] : 'unknown' };
-    }
-    // Linux
-    if (userAgent.includes('Linux')) {
-        return { name: 'Linux', version: 'unknown' };
-    }
-    return { name: 'unknown', version: 'unknown' };
-}
-/**
- * Get device information
- */
-function getDeviceInfo() {
-    const userAgent = navigator.userAgent;
-    // Mobile devices
-    if (userAgent.includes('iPhone')) {
-        return { type: 'mobile', model: 'iPhone' };
-    }
-    if (userAgent.includes('iPad')) {
-        return { type: 'tablet', model: 'iPad' };
-    }
-    if (userAgent.includes('Android')) {
-        if (userAgent.includes('Mobile')) {
-            return { type: 'mobile', model: 'Android' };
-        }
-        else {
-            return { type: 'tablet', model: 'Android' };
-        }
-    }
-    // Desktop (no specific device info)
-    return undefined;
-}
+import { UAParser } from '@ua-parser-js/pro-enterprise';
+import { isBot, isChromeFamily, isStandalonePWA, isAppleSilicon, } from '@ua-parser-js/pro-enterprise/helpers';
 /**
  * Get screen resolution
  */
@@ -120,28 +34,82 @@ export function getBrowserLocale() {
     }
 }
 /**
- * Collect all device information
+ * Collect all device information using UAParser
  */
 export function collectDeviceInfo() {
     if (typeof window === 'undefined') {
         // Server-side fallback
         return {
             userAgent: {
-                browser: { name: 'unknown', version: 'unknown' },
-                os: { name: 'unknown', version: 'unknown' },
+                name: '',
+                browser: { major: '', name: '', version: '' },
+                os: { name: '', version: '' },
+                device: undefined,
+                engine: { name: '', version: '' },
+                cpu: { architecture: '' },
             },
             screenResolution: { width: 0, height: 0 },
             timeZone: 'UTC',
+            flags: {
+                isBot: false,
+                isChromeFamily: false,
+                isStandalonePWA: false,
+                isAppleSilicon: false,
+            },
+        };
+    }
+    const parser = new UAParser();
+    const result = parser.getResult();
+    // Enhanced detection using UAParser official helpers
+    let flags;
+    try {
+        flags = {
+            isBot: isBot(result),
+            isChromeFamily: isChromeFamily(result),
+            isStandalonePWA: isStandalonePWA(),
+            isAppleSilicon: isAppleSilicon(result),
+        };
+    }
+    catch (error) {
+        console.error('Failed to compute device flags:', error);
+        flags = {
+            isBot: false,
+            isChromeFamily: false,
+            isStandalonePWA: false,
+            isAppleSilicon: false,
         };
     }
     return {
         userAgent: {
-            browser: getBrowserInfo(),
-            os: getOSInfo(),
-            device: getDeviceInfo(),
+            name: result.ua,
+            browser: {
+                major: result.browser.major || '',
+                name: result.browser.name || '',
+                version: result.browser.version || '',
+                type: result.browser.type,
+            },
+            os: {
+                name: result.os.name || '',
+                version: result.os.version || '',
+            },
+            device: result.device.model || result.device.type || result.device.vendor
+                ? {
+                    model: result.device.model,
+                    type: result.device.type,
+                    vendor: result.device.vendor,
+                }
+                : undefined,
+            engine: {
+                name: result.engine.name || '',
+                version: result.engine.version || '',
+            },
+            cpu: {
+                architecture: result.cpu.architecture || '',
+            },
         },
         screenResolution: getScreenResolution(),
         timeZone: getTimeZone(),
+        flags,
     };
 }
 /**

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

@@ -13,6 +13,9 @@
  * - token: Authentication token (URL > localStorage)
  * - funnelSessionId: Active funnel session (URL > cookie)
  *
+ * ⚠️ Note: authCode is NOT handled here - it has highest priority and is handled
+ * separately in client.ts before all other initialization logic.
+ *
  * Usage examples:
  * - Force production API: ?tagadaClientEnv=production
  * - Force development API: ?tagadaClientEnv=development
@@ -20,6 +23,7 @@
  * - Custom API URL: ?tagadaClientBaseUrl=https://tagada.loclx.io
  * - Combined: ?tagadaClientEnv=local&tagadaClientBaseUrl=https://tagada.loclx.io
  * - Hard reset + production: ?forceReset=true&tagadaClientEnv=production
+ * - Cross-domain auth: ?authCode=ah_... (automatically handled, highest priority)
  */
 /**
  * SDK Override Parameters - centralized across all SDK functions

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

@@ -13,6 +13,9 @@
  * - token: Authentication token (URL > localStorage)
  * - funnelSessionId: Active funnel session (URL > cookie)
  *
+ * ⚠️ Note: authCode is NOT handled here - it has highest priority and is handled
+ * separately in client.ts before all other initialization logic.
+ *
  * Usage examples:
  * - Force production API: ?tagadaClientEnv=production
  * - Force development API: ?tagadaClientEnv=development
@@ -20,6 +23,7 @@
  * - Custom API URL: ?tagadaClientBaseUrl=https://tagada.loclx.io
  * - Combined: ?tagadaClientEnv=local&tagadaClientBaseUrl=https://tagada.loclx.io
  * - Hard reset + production: ?forceReset=true&tagadaClientEnv=production
+ * - Cross-domain auth: ?authCode=ah_... (automatically handled, highest priority)
  */
 import { clearClientToken, setClientToken, getClientToken } from './tokenStorage';
 import { clearFunnelSessionCookie } from './sessionStorage';

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

@@ -13,7 +13,6 @@ export interface UseCheckoutQueryResult {
     error: Error | null;
     isSuccess: boolean;
     init: (params: CheckoutInitParams) => Promise<{
-        checkoutUrl: string;
         checkoutSession: any;
         checkoutToken: string;
     }>;