@tagadapay/plugin-sdk 3.0.3 → 3.0.12

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

@@ -0,0 +1,75 @@
+/**
+ * Config Hot Reload Utilities
+ *
+ * Enables live config editing without page reload.
+ * Used by the config editor to push updates to preview iframes.
+ */
+/**
+ * Send config update to target window (iframe, popup, etc.)
+ *
+ * @param targetWindow - Window to send update to (e.g., iframe.contentWindow)
+ * @param config - Updated config object
+ * @param targetOrigin - Target origin (default: '*' for same-origin)
+ */
+export function sendConfigUpdate(targetWindow, config, targetOrigin = '*') {
+    const message = {
+        type: 'TAGADAPAY_CONFIG_UPDATE',
+        config,
+        timestamp: Date.now(),
+    };
+    targetWindow.postMessage(message, targetOrigin);
+}
+/**
+ * Send config update to all iframes on the page
+ * Useful for config editor with multiple preview panes
+ *
+ * @param config - Updated config object
+ * @param selector - CSS selector for iframes (default: 'iframe')
+ */
+export function broadcastConfigUpdate(config, selector = 'iframe') {
+    if (typeof document === 'undefined')
+        return;
+    const iframes = document.querySelectorAll(selector);
+    iframes.forEach((iframe) => {
+        if (iframe.contentWindow) {
+            sendConfigUpdate(iframe.contentWindow, config);
+        }
+    });
+    console.log(`[ConfigHotReload] Broadcasted config update to ${iframes.length} iframe(s)`);
+}
+/**
+ * Setup a listener for config updates
+ * Returns cleanup function
+ *
+ * @param callback - Function to call when config is updated
+ */
+export function onConfigUpdate(callback) {
+    if (typeof window === 'undefined') {
+        return () => { };
+    }
+    const handleMessage = (event) => {
+        if (event.data?.type === 'TAGADAPAY_CONFIG_UPDATE') {
+            callback(event.data.config);
+        }
+    };
+    window.addEventListener('message', handleMessage);
+    return () => {
+        window.removeEventListener('message', handleMessage);
+    };
+}
+/**
+ * Debounce helper for config updates
+ * Prevents too many updates in quick succession
+ */
+export function debounceConfigUpdate(fn, delay = 150) {
+    let timeoutId = null;
+    return (config) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(config);
+            timeoutId = null;
+        }, delay);
+    };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Event Bus for handling domain events and coordination
+ */
+export type EventCallback<T = any> = (data: T) => void | Promise<void>;
+export declare class EventBus {
+    private listeners;
+    on<T = any>(event: string, callback: EventCallback<T>): () => void;
+    off<T = any>(event: string, callback: EventCallback<T>): void;
+    emit<T = any>(event: string, data?: T): Promise<void>;
+    clear(): void;
+}

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

@@ -0,0 +1,34 @@
+export class EventBus {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => this.off(event, callback);
+    }
+    off(event, callback) {
+        if (this.listeners.has(event)) {
+            this.listeners.get(event).delete(callback);
+        }
+    }
+    async emit(event, data) {
+        if (this.listeners.has(event)) {
+            const callbacks = Array.from(this.listeners.get(event));
+            await Promise.all(callbacks.map(cb => {
+                try {
+                    return Promise.resolve(cb(data));
+                }
+                catch (e) {
+                    console.error(`[EventBus] Error in listener for event "${event}":`, e);
+                    return Promise.resolve();
+                }
+            }));
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}

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

@@ -15,7 +15,6 @@ export type PluginConfig<TConfig = Record<string, any>> = {
     hidePriceId?: string;
     upsellId?: string;
     googleApiKey?: string;
-    branding?: any;
 } & TConfig;
 export type RawPluginConfig<TConfig = Record<string, any>> = {
     storeId?: string;
@@ -25,7 +24,13 @@ export type RawPluginConfig<TConfig = Record<string, any>> = {
 } & TConfig;
 /**
  * Core plugin config loading function
- * Handles local dev, production, and raw config
+ *
+ * PRIORITY ORDER (highest to lowest):
+ * 1. Injected meta tags (runtime config) - ALWAYS CHECK FIRST
+ * 2. Raw config parameter (programmatic override)
+ * 3. Environment variables (build-time config)
+ * 4. Local dev files (.local.json + config files)
+ * 5. Defaults
  */
 export declare const loadPluginConfig: (configVariant?: string, rawConfig?: RawPluginConfig) => Promise<PluginConfig>;
 /**
@@ -34,9 +39,13 @@ export declare const loadPluginConfig: (configVariant?: string, rawConfig?: RawP
  */
 export declare function loadLocalConfig(configName?: string, defaultConfig?: any): Promise<Record<string, unknown> | null>;
 /**
- * Creates a RawPluginConfig object from provided options
- * @param options - Configuration options including storeId, accountId, basePath, configName, or a direct config object
- * @returns A RawPluginConfig object or undefined if required fields are missing
+ * Creates a RawPluginConfig from environment variables (build-time config)
+ *
+ * This should ONLY be used when:
+ * 1. Running in localhost development
+ * 2. Meta tags are not present (not a deployed plugin)
+ *
+ * @returns A RawPluginConfig object or undefined if not applicable
  */
 export declare function createRawPluginConfig(): Promise<RawPluginConfig | undefined>;
 export declare class PluginConfigUtils {

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

@@ -123,15 +123,25 @@ const getMetaContent = (name) => {
     return metaTag?.getAttribute('content') || undefined;
 };
 /**
- * Load production config from meta tags
+ * Load production config from meta tags (HIGHEST PRIORITY)
  * Meta tags are injected by the plugin middleware during HTML serving
  * This avoids making an additional HEAD request (~300ms savings)
+ *
+ * Returns null if meta tags are not present (not in production deployment)
  */
 const loadProductionConfig = async () => {
     try {
+        // Check if we're in a browser environment
+        if (typeof document === 'undefined') {
+            return null;
+        }
         // Read store/account info from meta tags (injected by middleware)
         const storeId = getMetaContent('x-plugin-store-id');
         const accountId = getMetaContent('x-plugin-account-id');
+        // If no store ID in meta tags, this is not a production deployment with injected config
+        if (!storeId) {
+            return null;
+        }
         const basePath = getMetaContent('x-plugin-base-path') || '/';
         // Get deployment config from meta tags
         let config = {};
@@ -143,42 +153,57 @@ const loadProductionConfig = async () => {
             }
         }
         catch (error) {
-            console.warn('Failed to parse plugin config from meta tag:', error);
-        }
-        // Final validation and warnings
-        if (!storeId) {
-            console.warn('⚠️ Plugin config: Store ID not found in meta tags');
+            console.warn('⚠️ Failed to parse plugin config from meta tag:', error);
         }
+        // Final validation
         if (!accountId) {
             console.warn('⚠️ Plugin config: Account ID not found in meta tags');
         }
         const result = { storeId, accountId, basePath, config };
-        console.log('🚀 Plugin config loaded from meta tags (no HEAD request needed):', {
+        console.log('🚀 [HIGHEST PRIORITY] Plugin config loaded from meta tags (runtime injected config):', {
             storeId,
             accountId,
             basePath,
-            configKeys: Object.keys(config)
+            configKeys: Object.keys(config),
+            configSize: JSON.stringify(config).length
         });
         return result;
     }
     catch (error) {
-        console.warn('⚠️ Failed to load production config from meta tags, using defaults:', error);
-        return { basePath: '/', config: {} };
+        console.warn('⚠️ Error loading production config from meta tags:', error);
+        return null;
     }
 };
 /**
  * Core plugin config loading function
- * Handles local dev, production, and raw config
+ *
+ * PRIORITY ORDER (highest to lowest):
+ * 1. Injected meta tags (runtime config) - ALWAYS CHECK FIRST
+ * 2. Raw config parameter (programmatic override)
+ * 3. Environment variables (build-time config)
+ * 4. Local dev files (.local.json + config files)
+ * 5. Defaults
  */
 export const loadPluginConfig = async (configVariant = 'default', rawConfig) => {
     console.log('🔧 [V2] loadPluginConfig called with variant:', configVariant);
     // Load static resources first (only in local dev)
     const staticResources = await loadStaticResources();
-    console.log('🔧 [V2] Static resources loaded:', {
-        hasStaticResources: !!staticResources,
-        staticResourcesKeys: staticResources ? Object.keys(staticResources) : [],
-    });
-    // If raw config is provided, use it directly
+    // ============================================================
+    // PRIORITY 1: Check meta tags FIRST (runtime injected config)
+    // This ensures deployed plugins always use injected config
+    // ============================================================
+    const productionConfig = await loadProductionConfig();
+    if (productionConfig) {
+        const result = {
+            ...productionConfig,
+            staticResources: staticResources ?? undefined,
+        };
+        console.log('✅ [V2] Using INJECTED config from meta tags (HIGHEST PRIORITY)');
+        return result;
+    }
+    // ============================================================
+    // PRIORITY 2: Raw config parameter (programmatic override)
+    // ============================================================
     if (rawConfig) {
         const result = {
             storeId: rawConfig.storeId,
@@ -187,54 +212,43 @@ export const loadPluginConfig = async (configVariant = 'default', rawConfig) =>
             config: rawConfig.config ?? {},
             staticResources: staticResources ?? undefined,
         };
-        console.log('🔧 [V2] Final config (raw):', {
-            hasStoreId: !!result.storeId,
-            hasStaticResources: !!result.staticResources,
-            staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
-        });
+        console.log('✅ [V2] Using raw config parameter (PRIORITY 2)');
         return result;
     }
-    else {
-        const rawConfig = await createRawPluginConfig();
-        if (rawConfig) {
-            const result = {
-                ...rawConfig,
-                staticResources: staticResources ?? undefined,
-            };
-            console.log('🔧 [V2] Final config (createRawPluginConfig):', {
-                hasStoreId: !!result.storeId,
-                hasStaticResources: !!result.staticResources,
-                staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
-            });
-            return result;
-        }
+    // ============================================================
+    // PRIORITY 3: Environment variables (build-time config)
+    // Only in localhost - production should use meta tags
+    // ============================================================
+    const envConfig = await createRawPluginConfig();
+    if (envConfig) {
+        const result = {
+            ...envConfig,
+            staticResources: staticResources ?? undefined,
+        };
+        console.log('✅ [V2] Using environment variables config (PRIORITY 3 - build time)');
+        return result;
     }
-    // Try local development config
+    // ============================================================
+    // PRIORITY 4: Local development config files
+    // ============================================================
     const localConfig = await loadLocalDevConfig(configVariant);
     if (localConfig) {
         const result = {
             ...localConfig,
             staticResources: staticResources ?? undefined,
         };
-        console.log('🔧 [V2] Final config (local):', {
-            hasStoreId: !!result.storeId,
-            hasStaticResources: !!result.staticResources,
-            staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
-        });
+        console.log('✅ [V2] Using local dev config files (PRIORITY 4)');
         return result;
     }
-    // Fall back to production config
-    const productionConfig = await loadProductionConfig();
-    const result = {
-        ...productionConfig,
+    // ============================================================
+    // PRIORITY 5: Defaults (no config found)
+    // ============================================================
+    console.warn('⚠️ [V2] No plugin config found - using defaults');
+    return {
+        basePath: '/',
+        config: {},
         staticResources: staticResources ?? undefined,
     };
-    console.log('🔧 [V2] Final config (production):', {
-        hasStoreId: !!result.storeId,
-        hasStaticResources: !!result.staticResources,
-        staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
-    });
-    return result;
 };
 /**
  * Helper to load local config file for development (from /config directory)
@@ -276,15 +290,18 @@ export async function loadLocalConfig(configName = 'default', defaultConfig) {
     }
 }
 /**
- * Creates a RawPluginConfig object from provided options
- * @param options - Configuration options including storeId, accountId, basePath, configName, or a direct config object
- * @returns A RawPluginConfig object or undefined if required fields are missing
+ * Creates a RawPluginConfig from environment variables (build-time config)
+ *
+ * This should ONLY be used when:
+ * 1. Running in localhost development
+ * 2. Meta tags are not present (not a deployed plugin)
+ *
+ * @returns A RawPluginConfig object or undefined if not applicable
  */
 export async function createRawPluginConfig() {
     try {
-        // Only run in true localhost - production should use meta tags
+        // Only run in true localhost - production MUST use meta tags
         if (!isLocalEnvironment()) {
-            console.log('[createRawPluginConfig] Not localhost, skipping - will use meta tags in production');
             return undefined;
         }
         const storeId = resolveEnvValue('TAGADA_STORE_ID');
@@ -292,12 +309,10 @@ export async function createRawPluginConfig() {
         const basePath = resolveEnvValue('TAGADA_BASE_PATH');
         const configName = resolveEnvValue('TAGADA_CONFIG_NAME');
         if (!storeId || !accountId) {
-            console.warn('[createRawPluginConfig] No storeId provided');
             return undefined;
         }
         const resolvedConfig = await loadLocalConfig(configName);
         if (!resolvedConfig) {
-            console.warn('[createRawPluginConfig] No config found');
             return undefined;
         }
         const rawConfig = {
@@ -306,7 +321,7 @@ export async function createRawPluginConfig() {
             basePath: basePath || '/',
             config: resolvedConfig,
         };
-        console.log('[createRawPluginConfig] Created raw plugin config:', {
+        console.log('🛠️ [createRawPluginConfig] Using environment variables (build-time config):', {
             hasStoreId: !!rawConfig.storeId,
             hasAccountId: !!rawConfig.accountId,
             basePath: rawConfig.basePath,

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

@@ -0,0 +1,114 @@
+/**
+ * SDK Override Parameters
+ *
+ * Centralized parameter management for SDK behavior overrides.
+ * Parameters can come from URL query params, localStorage, or cookies.
+ *
+ * Key concepts:
+ * - forceReset: Clears all stored state (localStorage, cookies) - simulates hard refresh
+ * - draft: Marks customers/sessions as draft (for staging/preview/testing)
+ * - funnelTracking: Controls whether funnel events are tracked
+ * - tagadaClientEnv: Forces specific environment (production/development/local) - overrides auto-detection
+ * - tagadaClientBaseUrl: Forces custom API base URL - overrides environment-based URL
+ * - token: Authentication token (URL > localStorage)
+ * - funnelSessionId: Active funnel session (URL > cookie)
+ *
+ * Usage examples:
+ * - Force production API: ?tagadaClientEnv=production
+ * - Force development API: ?tagadaClientEnv=development
+ * - Force local API: ?tagadaClientEnv=local
+ * - Custom API URL: ?tagadaClientBaseUrl=https://tagada.loclx.io
+ * - Combined: ?tagadaClientEnv=local&tagadaClientBaseUrl=https://tagada.loclx.io
+ * - Hard reset + production: ?forceReset=true&tagadaClientEnv=production
+ */
+/**
+ * SDK Override Parameters - centralized across all SDK functions
+ * Can be set via URL params, localStorage, or cookies
+ */
+export interface SDKOverrideParams {
+    /** Force clean state (clear localStorage and cookies) - simulates hard refresh */
+    forceReset?: boolean;
+    /** Token from URL (overrides localStorage) */
+    token?: string | null;
+    /** Funnel session ID from URL (overrides cookie) */
+    funnelSessionId?: string | null;
+    /** Funnel ID from URL */
+    funnelId?: string | null;
+    /** Draft mode - marks customers/sessions as draft */
+    draft?: boolean;
+    /** Enable/disable funnel tracking events (false in config editor iframe, true in funnel previews) */
+    funnelTracking?: boolean;
+    /** Force specific environment (production/development/local) - overrides auto-detection */
+    tagadaClientEnv?: 'production' | 'development' | 'local';
+    /** Force custom API base URL - overrides environment-based URL */
+    tagadaClientBaseUrl?: string;
+}
+/**
+ * Check if force reset is active (simulates hard refresh)
+ */
+export declare function isForceReset(): boolean;
+/**
+ * Get SDK override parameters from all sources (URL, localStorage, cookies)
+ * Priority: URL > localStorage > Cookie
+ */
+export declare function getSDKParams(): SDKOverrideParams;
+/**
+ * Legacy alias for backward compatibility
+ * @deprecated Use getSDKParams() instead
+ */
+export declare function getPreviewParams(): SDKOverrideParams;
+/**
+ * Check if draft mode is active
+ * Uses centralized getSDKParams()
+ */
+export declare function isDraftMode(): boolean;
+/**
+ * Set draft mode in storage for persistence
+ */
+export declare function setDraftMode(draft: boolean): void;
+/**
+ * Initialize SDK with override parameters
+ *
+ * This function handles SDK initialization based on override params:
+ * 1. If forceReset flag is set: Clear all stored state (simulates hard refresh)
+ * 2. If token in URL: Use it (override localStorage)
+ * 3. If draft in URL: Persist it to storage
+ * 4. If funnelTracking in URL: Persist it to storage
+ *
+ * @returns True if force reset was activated and state was cleared
+ */
+export declare function handlePreviewMode(debugMode?: boolean): boolean;
+/**
+ * Set funnel tracking mode in storage for persistence
+ */
+export declare function setFunnelTracking(enabled: boolean): void;
+/**
+ * Set client environment override in storage for persistence
+ */
+export declare function setClientEnvironment(env: 'production' | 'development' | 'local'): void;
+/**
+ * Clear client environment override
+ */
+export declare function clearClientEnvironment(): void;
+/**
+ * Set custom API base URL override in storage for persistence
+ */
+export declare function setClientBaseUrl(baseUrl: string): void;
+/**
+ * Clear custom API base URL override
+ */
+export declare function clearClientBaseUrl(): void;
+/**
+ * Check if we should use URL params over stored values
+ *
+ * Returns true if:
+ * - Force reset is active, OR
+ * - Explicit token/sessionId in URL (indicating intentional override)
+ */
+export declare function shouldUseUrlParams(): boolean;
+/**
+ * Check if funnel tracking is enabled
+ * Uses centralized getSDKParams()
+ * Default is true for normal operations
+ */
+export declare function isFunnelTrackingEnabled(): boolean;