@tagadapay/plugin-sdk 3.1.11 → 3.1.22

package/dist/v2/standalone/external-tracker.js

@@ -1,36 +1,33 @@
 /**
  * TagadaPay External Page Tracker
  *
- * A lightweight standalone script for tracking users on external pages
- * that are part of a Tagadapay funnel but not hosted on the Tagadapay platform.
+ * Standalone script for tracking users on external pages that are part of a
+ * TagadaPay funnel but not hosted on the TagadaPay platform.
  *
- * ARCHITECTURE:
- * - Reuses core SDK infrastructure (TagadaClient) for authentication and API handling
- * - All tracking handled automatically by funnelOrchestrator via autoInitialize() and navigate()
- * - No separate tracking endpoints needed - unified tracking through orchestrator
+ * Use cases:
+ *   - WooCommerce / WordPress storefronts
+ *   - Custom landing pages
+ *   - Any external page that is a funnel step
  *
- * Usage (via CDN):
+ * @example CDN usage
+ * ```html
  * <script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
  * <script>
  *   TagadaTracker.init({
  *     storeId: 'store_xxx',
  *     accountId: 'acc_xxx',
- *     funnelId: 'funnel_xxx',  // Optional: detected from URL
  *     stepId: 'step_xxx',
- *     stepName: 'External Offer Page',
- *     stepType: 'external'
- *   });
- *
- *   // Navigate to next step (tracking automatic)
- *   TagadaTracker.navigate({
- *     eventType: 'form.submitted',
- *     eventData: { email: 'user@example.com' }
  *   });
  * </script>
+ * ```
  */
 import { createTagadaClient } from './index';
 import { setClientToken } from '../core/utils/tokenStorage';
 // ============================================================================
+// VERSION
+// ============================================================================
+export const TRACKER_VERSION = '1.0.0';
+// ============================================================================
 // UTILITIES
 // ============================================================================
 function getUrlParam(name) {
@@ -44,6 +41,45 @@ function log(debug, ...args) {
         console.log('[TagadaTracker]', ...args);
     }
 }
+function warn(...args) {
+    console.warn('[TagadaTracker]', ...args);
+}
+function validate(config) {
+    if (!config.storeId || typeof config.storeId !== 'string') {
+        throw new Error('TagadaTracker: storeId is required and must be a non-empty string.');
+    }
+    if (!config.accountId || typeof config.accountId !== 'string') {
+        throw new Error('TagadaTracker: accountId is required and must be a non-empty string.');
+    }
+    if (!config.stepId || typeof config.stepId !== 'string') {
+        throw new Error('TagadaTracker: stepId is required and must be a non-empty string.');
+    }
+    if (config.apiBaseUrl) {
+        try {
+            new URL(config.apiBaseUrl);
+        }
+        catch {
+            throw new Error(`TagadaTracker: apiBaseUrl is not a valid URL: "${config.apiBaseUrl}"`);
+        }
+    }
+}
+async function retryWithBackoff(fn, maxRetries, debug) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < maxRetries) {
+                const delay = Math.min(1000 * 2 ** attempt, 8000);
+                log(debug, `Retry ${attempt + 1}/${maxRetries} in ${delay}ms...`);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+    }
+    throw lastError;
+}
 // ============================================================================
 // MAIN CLASS
 // ============================================================================
@@ -53,41 +89,67 @@ class TagadaExternalTracker {
         this.client = null;
         this.initialized = false;
         this.initializing = false;
+        this.unsubscribe = null;
+        /** Tracker version */
+        this.version = TRACKER_VERSION;
     }
     /**
-     * Initialize the tracker using SDK infrastructure
+     * Initialize the tracker.
+     * When `onError` is provided, errors are passed to the callback and init()
+     * resolves to `null` instead of throwing.
      */
     async init(config) {
-        if (this.initialized || this.initializing) {
-            log(config.debug || false, 'Already initialized or initializing');
+        if (this.initialized) {
+            log(config.debug || false, 'Already initialized — returning existing session.');
             return this.getSession();
         }
+        if (this.initializing) {
+            log(config.debug || false, 'Initialization in progress — skipping duplicate call.');
+            return null;
+        }
         this.initializing = true;
-        this.config = {
-            debug: false,
-            ...config,
-        };
-        log(this.config.debug, '🚀 Initializing external tracker with SDK...', config);
+        this.config = { debug: false, ...config };
+        const debug = this.config.debug;
+        try {
+            validate(this.config);
+        }
+        catch (err) {
+            this.initializing = false;
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (this.config.onError) {
+                this.config.onError(error);
+                return null;
+            }
+            throw error;
+        }
+        log(debug, `🚀 Initializing external tracker v${TRACKER_VERSION}`, {
+            storeId: config.storeId,
+            accountId: config.accountId,
+            stepId: config.stepId,
+            funnelId: config.funnelId,
+        });
         try {
-            // 1. Check for token in URL and save to storage (bootstrap auth)
-            // TagadaClient will automatically pick it up from storage
             const urlToken = getUrlParam('token');
             if (urlToken) {
                 setClientToken(urlToken);
-                log(this.config.debug, '🔑 Bootstrapped token from URL');
+                log(debug, '🔑 Bootstrapped token from URL');
             }
-            // 2. Create TagadaClient
             this.client = createTagadaClient({
-                debugMode: this.config.debug,
-                features: { funnel: true },
+                debugMode: debug,
+                features: { funnel: { skipAutoInit: true } },
+                rawPluginConfig: {
+                    storeId: this.config.storeId,
+                    accountId: this.config.accountId,
+                },
+                customApiConfig: this.config.apiBaseUrl ? {
+                    apiConfig: {
+                        baseUrl: this.config.apiBaseUrl.trim(),
+                    },
+                } : undefined,
             });
-            // 3. Wait for client to be ready (load token, init auth state)
             await this.waitForClientReady();
-            // 4. Auto-initialize funnel session
-            // FunnelClient handles cookies, existing session restoration, etc.
-            // Orchestrator automatically tracks session start and step view
-            const funnelContext = await this.initializeFunnel();
-            log(this.config.debug, '✅ Session initialized (tracking handled by orchestrator):', funnelContext);
+            const funnelContext = await retryWithBackoff(() => this.initializeFunnel(), 2, debug);
+            log(debug, '✅ Session initialized:', funnelContext);
             this.initialized = true;
             const session = this.getSession();
             if (session) {
@@ -95,19 +157,20 @@ class TagadaExternalTracker {
             }
             return session;
         }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            log(this.config.debug, '❌ Initialization failed:', err);
-            this.config.onError?.(err);
-            throw err;
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            log(debug, '❌ Initialization failed:', error);
+            if (this.config.onError) {
+                this.config.onError(error);
+                return null;
+            }
+            throw error;
         }
         finally {
             this.initializing = false;
         }
     }
-    /**
-     * Get current session from SDK state
-     */
+    /** Get current session data. */
     getSession() {
         if (!this.client?.funnel?.state.context)
             return null;
@@ -121,31 +184,27 @@ class TagadaExternalTracker {
             cmsToken: this.client.state.token || undefined,
         };
     }
-    /**
-     * Check if tracker is ready
-     */
+    /** Whether the tracker is fully initialized and ready. */
     isReady() {
         return this.initialized && !!this.client?.funnel?.state.context;
     }
     /**
-     * Navigate to next step in funnel using SDK's funnel client
+     * Navigate to the next step in the funnel.
+     * By default, auto-redirects the browser window.
      */
     async navigate(options) {
         if (!this.isReady()) {
-            throw new Error('Tracker not initialized. Call init() first.');
+            throw new Error('TagadaTracker: not initialized. Call init() first.');
         }
         log(this.config.debug, '🚀 Navigating:', options);
-        // Determine if we should auto-redirect (default: true)
         const shouldAutoRedirect = options.autoRedirect !== false;
         try {
             const result = await this.client.funnel.navigate({
                 type: options.eventType,
                 data: options.eventData || {},
-            }, { autoRedirect: false } // Always disable SDK auto-redirect, we handle it here
-            );
+            }, { autoRedirect: false });
             if (result?.url) {
                 log(this.config.debug, '✅ Navigation result:', result.url);
-                // Only redirect if autoRedirect is enabled
                 if (shouldAutoRedirect && typeof window !== 'undefined') {
                     window.location.href = options.returnUrl || result.url;
                 }
@@ -159,37 +218,51 @@ class TagadaExternalTracker {
         }
     }
     /**
-     * Get customer ID (for identifying the user)
+     * Track a custom event (e.g., button click, scroll depth, video play).
+     * Events are sent through the funnel orchestrator for unified analytics.
      */
+    async trackEvent(options) {
+        if (!this.isReady()) {
+            warn('trackEvent called before init — event dropped:', options.name);
+            return;
+        }
+        log(this.config.debug, '📊 Tracking event:', options.name, options.data);
+        try {
+            await this.client.funnel.navigate({
+                type: options.name,
+                data: options.data || {},
+            }, { autoRedirect: false });
+        }
+        catch {
+            // Non-critical — swallow errors for tracking events
+            log(this.config.debug, '⚠️ Event tracking failed (non-critical):', options.name);
+        }
+    }
+    /** Get customer ID. */
     getCustomerId() {
-        return this.client?.state.auth.customer?.id || this.client?.funnel?.state.context?.customerId || null;
+        return this.client?.state.auth.customer?.id
+            || this.client?.funnel?.state.context?.customerId
+            || null;
     }
-    /**
-     * Get funnel session ID
-     */
+    /** Get funnel session ID. */
     getFunnelSessionId() {
         return this.client?.funnel?.state.context?.sessionId || null;
     }
     /**
-     * Build a URL with funnel context parameters
-     * Useful for linking to other external pages while preserving session
+     * Build a URL that preserves funnel session context.
+     * Use this to link to other external pages within the same funnel.
      */
     buildUrl(baseUrl, additionalParams) {
         const session = this.getSession();
-        if (!session) {
+        if (!session)
             return baseUrl;
-        }
         const url = new URL(baseUrl, typeof window !== 'undefined' ? window.location.origin : undefined);
-        // Add funnel session context
         url.searchParams.set('funnelSessionId', session.sessionId);
-        if (session.cmsToken) {
+        if (session.cmsToken)
             url.searchParams.set('token', session.cmsToken);
-        }
-        if (session.funnelId) {
+        if (session.funnelId)
             url.searchParams.set('funnelId', session.funnelId);
-        }
         url.searchParams.set('storeId', session.storeId);
-        // Add any additional params
         if (additionalParams) {
             Object.entries(additionalParams).forEach(([key, value]) => {
                 url.searchParams.set(key, value);
@@ -197,60 +270,94 @@ class TagadaExternalTracker {
         }
         return url.toString();
     }
-    /**
-     * Get the underlying SDK client (for advanced usage)
-     */
+    /** Get the underlying SDK client (advanced usage). */
     getClient() {
         return this.client;
     }
+    /**
+     * Reset the tracker to a new step without re-creating the session.
+     * Useful for SPAs that navigate between funnel steps client-side.
+     */
+    async reset(newStepId) {
+        if (!this.client || !this.config) {
+            throw new Error('TagadaTracker: not initialized. Call init() first.');
+        }
+        log(this.config.debug, '🔄 Resetting to step:', newStepId);
+        this.config.stepId = newStepId;
+        const ctx = await this.initializeFunnel();
+        const session = this.getSession();
+        if (session)
+            this.config.onReady?.(session);
+        return session;
+    }
+    /**
+     * Destroy the tracker, clean up event listeners and state.
+     * Call this when the tracker is no longer needed (e.g., SPA teardown).
+     */
+    destroy() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+        if (this.client) {
+            this.client.destroy?.();
+        }
+        this.client = null;
+        this.config = null;
+        this.initialized = false;
+        this.initializing = false;
+        log(false, '🗑️ Tracker destroyed');
+    }
     // ========================================================================
     // PRIVATE METHODS
     // ========================================================================
     async waitForClientReady() {
         if (!this.client)
             return;
-        // Wait for token/auth to be resolved
+        // Wait for isInitialized which is set AFTER the full init sequence:
+        // anonymous token → session/v2/init → isInitialized=true
+        // Do NOT resolve on token alone — that fires before session init.
         return new Promise((resolve) => {
-            let retries = 0;
-            const checkReady = () => {
-                // Check if initialized OR if we have a token (sometimes isInitialized is lazy)
-                if (this.client?.state.isInitialized || this.client?.state.token) {
+            if (this.client?.state.isInitialized) {
+                resolve();
+                return;
+            }
+            let resolved = false;
+            const timeout = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    log(this.config?.debug || false, '⏱️ Client ready timeout — proceeding');
                     resolve();
                 }
-                else if (retries > 40) { // 2 seconds timeout
-                    resolve(); // Proceed anyway (might be anonymous)
-                }
-                else {
-                    retries++;
-                    setTimeout(checkReady, 50);
+            }, 10000);
+            this.unsubscribe = this.client.subscribe(() => {
+                if (!resolved && this.client?.state.isInitialized) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    resolve();
                 }
-            };
-            checkReady();
+            });
         });
     }
     async initializeFunnel() {
         if (!this.client?.funnel)
             return null;
-        // Prepare auth session object
+        const customerId = this.client.state.auth.customer?.id;
+        const sessionId = this.client.state.auth.session?.sessionId;
+        if (!customerId && !sessionId) {
+            warn('No auth session available — funnel init may fail.');
+        }
         const authSession = {
-            customerId: this.client.state.auth.customer?.id || 'anon_placeholder',
-            sessionId: this.client.state.auth.session?.sessionId || 'sess_placeholder',
+            customerId: customerId || 'anon_placeholder',
+            sessionId: sessionId || 'sess_placeholder',
         };
         const store = {
             id: this.config.storeId,
-            accountId: this.config.accountId || '',
+            accountId: this.config.accountId,
         };
-        // IMPORTANT: For external pages, we must explicitly pass stepId as entryStepId
-        // because URL-to-step mapping won't work for external URLs not hosted on Tagadapay
         const entryStepId = this.config.stepId;
-        if (!entryStepId) {
-            throw new Error('stepId is required for external page tracking (URL mapping does not work for external pages)');
-        }
-        log(this.config.debug, '🔍 Initializing external page at step:', entryStepId);
-        // Use initialize() (not autoInitialize()) to explicitly specify the step
-        // Orchestrator will automatically track session start and step view at this step
-        return this.client.funnel.initialize(authSession, store, this.config.funnelId || getUrlParam('funnelId') || undefined, entryStepId // ✅ Explicitly tell orchestrator which step we're on
-        );
+        log(this.config.debug, '🔍 Initializing funnel at step:', entryStepId);
+        return this.client.funnel.initialize(authSession, store, this.config.funnelId || getUrlParam('funnelId') || undefined, entryStepId);
     }
 }
 // ============================================================================

package/dist/v2/standalone/index.d.ts

@@ -9,15 +9,37 @@
 import { TagadaClient, TagadaClientConfig, TagadaState } from '../core/client';
 import { ApiClient } from '../core/resources/apiClient';
 import { CheckoutResource } from '../core/resources/checkout';
+/**
+ * Auto-inject all stepConfig scripts
+ * Called automatically when SDK loads
+ * Can also be called manually if needed (e.g., after dynamic config update)
+ */
+export declare function injectStepConfigScripts(): void;
 /**
  * Factory function to create a Tagada Client instance.
  * Features (like funnel) can be toggled via the config.
  */
 export declare function createTagadaClient(config?: TagadaClientConfig): TagadaClient;
 export { TagadaClient, ApiClient, CheckoutResource };
+export { ShippingRatesResource } from '../core/resources/shippingRates';
+export { PaymentsResource } from '../core/resources/payments';
+export { OrdersResource } from '../core/resources/orders';
+export type { ShippingRate, ShippingRatesResponse, ShippingRatesPreviewParams } from '../core/resources/shippingRates';
+export type { Payment, PaymentResponse, CardPaymentMethod, BasisTheoryInstance, GooglePayToken, PaymentInstrumentInput, } from '../core/resources/payments';
+export { ISODataCore } from '../core/isoData';
+export type { ISOCountry, ISORegion } from '../core/isoData';
+export { GoogleAutocompleteCore } from '../core/googleAutocomplete';
+export type { GooglePrediction, GooglePlaceDetails, AddressComponents } from '../core/googleAutocomplete';
+export { TagadaError, TagadaApiError, TagadaNetworkError, TagadaAuthError, TagadaValidationError, TagadaCircuitBreakerError, TagadaErrorCode, } from '../core/errors';
+export type { TagadaErrorOptions, TagadaErrorCodeValue } from '../core/errors';
 export type { TagadaClientConfig, TagadaState };
 export { FunnelActionType } from '../core/resources/funnel';
 export type { FunnelAction, FunnelNavigationResult, SimpleFunnelContext } from '../core/resources/funnel';
+export type { CheckoutData, CheckoutSession, CheckoutSummary, CheckoutSummaryItem, CheckoutLineItem, CheckoutInitParams, Promotion, } from '../core/resources/checkout';
+export type { Order, OrderItem, OrderAddress, OrderSummary, OrderWithRelations, PaymentSummary, PromotionSummary, Subscription, DeviceInfo, PromotionCode, Customer, Store, PickupPoint, } from '../core/types';
 export * from '../core/utils';
+export { matchRoute, getInternalPath, isPathRemapped, getPathInfo, } from '../core/pathRemapping';
+export { resolvePixelEvents, mapMetaEvent, mapTikTokEvent, mapSnapchatEvent, mapPinterestEvent, mapGTMEvent, isEventEnabled, getEligiblePixels, applyGoogleAdsConversion, } from '../core/pixelMapping';
+export type { StandardPixelEvent, PixelProviderKey, MappedEvent, ProviderEvent, } from '../core/pixelMapping';
 export { TagadaTracker, TagadaExternalTracker, } from './external-tracker';
 export type { TagadaTrackerConfig, ExternalTrackerSession, NavigateOptions, } from './external-tracker';

package/dist/v2/standalone/index.js

@@ -9,6 +9,117 @@
 import { TagadaClient } from '../core/client';
 import { ApiClient } from '../core/resources/apiClient';
 import { CheckoutResource } from '../core/resources/checkout';
+import { getAssignedStepConfig } from '../core/funnelClient';
+/**
+ * Parse step config from window variable or meta tag
+ */
+function parseStepConfigScripts() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return [];
+    }
+    // Try to get stepConfig (uses same logic as getAssignedStepConfig)
+    const stepConfig = getAssignedStepConfig();
+    if (stepConfig?.scripts) {
+        return stepConfig.scripts.filter(s => s.enabled);
+    }
+    return [];
+}
+/**
+ * Inject a script at the specified position
+ */
+function injectScript(script, index) {
+    const position = script.position || 'body-end';
+    const scriptId = `tagada-stepconfig-script-${index}`;
+    // Skip if already injected
+    if (document.getElementById(scriptId)) {
+        return;
+    }
+    // Extract script content (remove <script> tags if present)
+    let scriptBody = script.content.trim();
+    const scriptTagMatch = scriptBody.match(/^<script[^>]*>([\s\S]*)<\/script>$/i);
+    if (scriptTagMatch) {
+        scriptBody = scriptTagMatch[1].trim();
+    }
+    if (!scriptBody)
+        return;
+    // Wrap script content with error handling
+    // NOTE: Use string concatenation instead of template literals to avoid breaking
+    // when scriptBody contains backticks or ${...} expressions
+    const wrappedScript = '(function() {\n' +
+        '  try {\n' +
+        '    // Script: ' + script.name + '\n' +
+        scriptBody + '\n' +
+        '  } catch (error) {\n' +
+        '    console.error("[TagadaPay] StepConfig script error:", error);\n' +
+        '  }\n' +
+        '})();';
+    // Create script element
+    const scriptElement = document.createElement('script');
+    scriptElement.id = scriptId;
+    scriptElement.setAttribute('data-tagada-stepconfig-script', 'true');
+    scriptElement.setAttribute('data-script-name', script.name);
+    scriptElement.textContent = wrappedScript;
+    // Inject at the correct position
+    switch (position) {
+        case 'head-start':
+            if (document.head.firstChild) {
+                document.head.insertBefore(scriptElement, document.head.firstChild);
+            }
+            else {
+                document.head.appendChild(scriptElement);
+            }
+            break;
+        case 'head-end':
+            document.head.appendChild(scriptElement);
+            break;
+        case 'body-start':
+            if (document.body.firstChild) {
+                document.body.insertBefore(scriptElement, document.body.firstChild);
+            }
+            else {
+                document.body.appendChild(scriptElement);
+            }
+            break;
+        case 'body-end':
+        default:
+            document.body.appendChild(scriptElement);
+            break;
+    }
+}
+/**
+ * Auto-inject all stepConfig scripts
+ * Called automatically when SDK loads
+ * Can also be called manually if needed (e.g., after dynamic config update)
+ */
+export function injectStepConfigScripts() {
+    const scripts = parseStepConfigScripts();
+    if (scripts.length === 0)
+        return;
+    scripts.forEach((script, index) => {
+        injectScript(script, index);
+    });
+}
+// Auto-run script injection when SDK loads
+// Uses requestIdleCallback or setTimeout fallback for non-blocking execution
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    const runInjection = () => {
+        // Wait for body to be available
+        if (document.body) {
+            injectStepConfigScripts();
+        }
+        else {
+            // Body not ready, wait for DOMContentLoaded
+            document.addEventListener('DOMContentLoaded', injectStepConfigScripts, { once: true });
+        }
+    };
+    // Run after current script execution completes
+    if ('requestIdleCallback' in window) {
+        window.requestIdleCallback(runInjection, { timeout: 100 });
+    }
+    else {
+        setTimeout(runInjection, 0);
+    }
+}
 /**
  * Factory function to create a Tagada Client instance.
  * Features (like funnel) can be toggled via the config.
@@ -18,9 +129,23 @@ export function createTagadaClient(config = {}) {
 }
 // Re-export Core Classes
 export { TagadaClient, ApiClient, CheckoutResource };
+// Re-export Resource Classes (for standalone resolvers / builders)
+export { ShippingRatesResource } from '../core/resources/shippingRates';
+export { PaymentsResource } from '../core/resources/payments';
+export { OrdersResource } from '../core/resources/orders';
+// Re-export ISO Data Core (for standalone address form / resolvers)
+export { ISODataCore } from '../core/isoData';
+// Re-export Google Autocomplete Core (for standalone address form)
+export { GoogleAutocompleteCore } from '../core/googleAutocomplete';
+// Re-export Error Types
+export { TagadaError, TagadaApiError, TagadaNetworkError, TagadaAuthError, TagadaValidationError, TagadaCircuitBreakerError, TagadaErrorCode, } from '../core/errors';
 export { FunnelActionType } from '../core/resources/funnel';
 // Re-export Utilities (includes formatMoney from core/utils/currency)
 export * from '../core/utils';
+// Re-export path remapping utilities (for SPA routing)
+export { matchRoute, getInternalPath, isPathRemapped, getPathInfo, } from '../core/pathRemapping';
+// Re-export pixel mapping (for standalone pixel tracking)
+export { resolvePixelEvents, mapMetaEvent, mapTikTokEvent, mapSnapchatEvent, mapPinterestEvent, mapGTMEvent, isEventEnabled, getEligiblePixels, applyGoogleAdsConversion, } from '../core/pixelMapping';
 // ============================================================================
 // EXTERNAL PAGE TRACKER
 // ============================================================================