@tagadapay/plugin-sdk 3.0.2 → 3.0.9

package/dist/react/config/payment.d.ts

@@ -17,13 +17,13 @@ export declare const PAYMENT_CONFIGS: Record<string, PaymentConfig>;
  */
 export declare function getPaymentConfig(environment?: string): PaymentConfig;
 /**
- * Get BasisTheory API key for current environment
+ * Get BasisTheory API key and tenant ID based on environment detection
  *
- * Behavior:
- * - LOCAL/DEVELOPMENT: Always uses embedded test key (key_test_us_pub_VExdfbFQARn821iqP8zNaq)
- *   Environment variables are ignored to prevent accidental production key usage
- *
- * - PRODUCTION: Uses environment variable if set, falls back to embedded production key
- *   This allows deployment-time configuration while having safe defaults
+ * Uses detectEnvironment() to determine if production or test keys should be used.
+ * No environment variables - keys are hardcoded for consistency.
+ */
+export declare function getBasisTheoryApiKey(): string;
+/**
+ * Get BasisTheory tenant ID based on environment detection
  */
-export declare function getBasisTheoryApiKey(environment?: string): string;
+export declare function getBasisTheoryTenantId(): string;

package/dist/react/config/payment.js

@@ -42,28 +42,24 @@ export const PAYMENT_CONFIGS = {
 export function getPaymentConfig(environment = 'local') {
     return PAYMENT_CONFIGS[environment] || PAYMENT_CONFIGS.default || PAYMENT_CONFIGS.local;
 }
+import { detectEnvironment } from '../../v2/core/config/environment';
+import { getBasisTheoryKeys } from '../../config/basisTheory';
 /**
- * Get BasisTheory API key for current environment
+ * Get BasisTheory API key and tenant ID based on environment detection
  *
- * Behavior:
- * - LOCAL/DEVELOPMENT: Always uses embedded test key (key_test_us_pub_VExdfbFQARn821iqP8zNaq)
- *   Environment variables are ignored to prevent accidental production key usage
- *
- * - PRODUCTION: Uses environment variable if set, falls back to embedded production key
- *   This allows deployment-time configuration while having safe defaults
+ * Uses detectEnvironment() to determine if production or test keys should be used.
+ * No environment variables - keys are hardcoded for consistency.
+ */
+export function getBasisTheoryApiKey() {
+    const isProduction = detectEnvironment() === 'production';
+    const keys = getBasisTheoryKeys(isProduction);
+    return keys.apiKey;
+}
+/**
+ * Get BasisTheory tenant ID based on environment detection
  */
-export function getBasisTheoryApiKey(environment = 'local') {
-    // For production environment, allow environment variable override
-    if (environment === 'production') {
-        if (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_BASIS_THEORY_PUBLIC_API_KEY) {
-            return process.env.NEXT_PUBLIC_BASIS_THEORY_PUBLIC_API_KEY;
-        }
-        if (typeof process !== 'undefined' && process.env?.VITE_BASIS_THEORY_PUBLIC_API_KEY) {
-            return process.env.VITE_BASIS_THEORY_PUBLIC_API_KEY;
-        }
-    }
-    // For local/development, always use embedded test key to prevent accidental production key usage
-    // Fall back to embedded configuration based on environment
-    const config = getPaymentConfig(environment);
-    return config.basisTheory.publicApiKey;
+export function getBasisTheoryTenantId() {
+    const isProduction = detectEnvironment() === 'production';
+    const keys = getBasisTheoryKeys(isProduction);
+    return keys.tenantId;
 }

package/dist/react/hooks/useApplePay.js

@@ -9,7 +9,7 @@ export function useApplePay(options = {}) {
     const { createApplePayPaymentInstrument, processApplePayPayment } = usePayment();
     const { environment, apiService } = useTagadaContext();
     // Get API key from environment
-    const apiKey = getBasisTheoryApiKey(environment?.environment || 'local');
+    const apiKey = getBasisTheoryApiKey(); // Auto-detects environment
     // Check Apple Pay availability on mount
     useEffect(() => {
         const checkApplePayAvailability = () => {

package/dist/react/hooks/usePayment.js

@@ -24,10 +24,8 @@ export function usePayment() {
     const { createSession, startChallenge } = useThreeds();
     // Track challenge in progress to prevent multiple challenges
     const challengeInProgressRef = useRef(false);
-    // Stabilize environment value to prevent re-renders
-    const currentEnvironment = useMemo(() => environment?.environment || 'local', [environment?.environment]);
     // Get API key from embedded configuration with proper environment detection
-    const apiKey = useMemo(() => getBasisTheoryApiKey(currentEnvironment), [currentEnvironment]);
+    const apiKey = useMemo(() => getBasisTheoryApiKey(), []); // Auto-detects environment
     // Initialize BasisTheory using React wrapper
     const { bt: basisTheory, error: btError } = useBasisTheory(apiKey, {
         elements: false,

package/dist/react/hooks/useThreeds.js

@@ -41,7 +41,7 @@ export function useThreeds(options = {}) {
                 throw new Error('BasisTheory3ds not loaded yet');
             }
             // Use the same API key approach as the working CMS version
-            const apiKey = getBasisTheoryApiKey('production'); // Use production config for now
+            const apiKey = getBasisTheoryApiKey(); // Auto-detects environment
             const bt3ds = basisTheory3ds(apiKey);
             console.log('paymentInstrument paymentInstrument', paymentInstrument?.token);
             const session = await bt3ds.createSession({
@@ -94,7 +94,7 @@ export function useThreeds(options = {}) {
                 throw new Error('BasisTheory3ds not loaded yet');
             }
             // Use the same API key approach as the working CMS version
-            const apiKey = getBasisTheoryApiKey('production'); // Use production config for now
+            const apiKey = getBasisTheoryApiKey(); // Auto-detects environment
             if (!apiKey) {
                 throw new Error('BasisTheory API key is not set');
             }

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

@@ -1,9 +1,11 @@
+import { FunnelClient } from './funnelClient';
 import { ApiClient } from './resources/apiClient';
+import { AuthState, Currency, Customer, Environment, EnvironmentConfig, Locale, Session, Store } from './types';
+import { EventBus } from './utils/eventBus';
 import { PluginConfig, RawPluginConfig } from './utils/pluginConfig';
-import { Environment, EnvironmentConfig, Session, AuthState, Customer, Store, Locale, Currency } from './types';
-import { FunnelClient } from './funnelClient';
 export interface TagadaClientConfig {
     environment?: Environment;
+    customApiConfig?: Partial<EnvironmentConfig>;
     debugMode?: boolean;
     localConfig?: string;
     rawPluginConfig?: RawPluginConfig;
@@ -16,8 +18,11 @@ export interface TagadaClientConfig {
         /**
          * Funnel session + navigation layer.
          * Set to false to completely disable funnel behaviour.
+         * Pass object to configure behavior.
          */
-        funnel?: boolean;
+        funnel?: boolean | {
+            autoRedirect?: boolean;
+        };
     };
 }
 export interface TagadaState {
@@ -45,6 +50,10 @@ export declare class TagadaClient {
      * low-level logic without instantiating a second client.
      */
     funnel?: FunnelClient;
+    /**
+     * Event bus for domain events and coordination
+     */
+    bus: EventBus;
     private eventDispatcher;
     private tokenPromise;
     private tokenResolver;
@@ -111,4 +120,23 @@ export declare class TagadaClient {
     private updateSessionState;
     private getCurrencySymbol;
     private getCurrencyName;
+    /**
+     * Helper to get accountId with fallbacks
+     */
+    getAccountId(): string;
+    /**
+     * Update plugin config dynamically (hot-reload)
+     * Used for live config editing without page reload
+     */
+    updatePluginConfig(newConfig: Partial<PluginConfig['config']>): void;
+    /**
+     * Setup listener for config updates from parent window (config editor)
+     * Enables live config editing via postMessage
+     */
+    private setupConfigHotReload;
+    /**
+     * Apply CSS properties to a real div child element for highlighting
+     * Used by config editor to highlight elements in preview without altering the element's style
+     */
+    private applyStylesToElement;
 }

package/dist/v2/core/client.js

@@ -1,13 +1,19 @@
-import { ApiClient } from './resources/apiClient';
 import { detectEnvironment, getEnvironmentConfig } from './config/environment';
-import { loadPluginConfig } from './utils/pluginConfig';
+import { FunnelClient } from './funnelClient';
+import { ApiClient } from './resources/apiClient';
 import { collectDeviceInfo, getBrowserLocale, getUrlParams } from './utils/deviceInfo';
+import { EventBus } from './utils/eventBus';
+import { EventDispatcher } from './utils/eventDispatcher';
 import { decodeJWTClient, isTokenExpired } from './utils/jwtDecoder';
+import { loadPluginConfig } from './utils/pluginConfig';
+import { handlePreviewMode, isDraftMode, setDraftMode } from './utils/previewMode';
 import { getClientToken, setClientToken } from './utils/tokenStorage';
-import { EventDispatcher } from './utils/eventDispatcher';
-import { FunnelClient } from './funnelClient';
 export class TagadaClient {
     constructor(config = {}) {
+        /**
+         * Event bus for domain events and coordination
+         */
+        this.bus = new EventBus();
         this.eventDispatcher = new EventDispatcher();
         this.tokenPromise = null;
         this.tokenResolver = null;
@@ -22,9 +28,29 @@ export class TagadaClient {
         if (this.config.debugMode) {
             console.log(`[TagadaClient ${this.instanceId}] Initializing...`);
         }
+        // Handle preview mode FIRST - clears state if needed
+        // This ensures clean state when CRM previews pages
+        const previewModeActive = handlePreviewMode(this.config.debugMode);
+        if (previewModeActive && this.config.debugMode) {
+            console.log(`[TagadaClient ${this.instanceId}] Preview mode active - state cleared`);
+        }
         // Initialize default state
         const env = this.resolveEnvironment();
-        const envConfig = getEnvironmentConfig(env);
+        let envConfig = getEnvironmentConfig(env);
+        // Apply custom API config if provided
+        if (config.customApiConfig) {
+            envConfig = {
+                ...envConfig,
+                ...config.customApiConfig,
+                apiConfig: {
+                    ...envConfig.apiConfig,
+                    ...config.customApiConfig.apiConfig,
+                },
+            };
+            if (this.config.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Applied custom API config:`, envConfig.apiConfig.baseUrl);
+            }
+        }
         this.state = {
             auth: {
                 isAuthenticated: false,
@@ -60,13 +86,16 @@ export class TagadaClient {
             baseURL: envConfig.apiConfig.baseUrl,
         });
         // Initialize optional funnel client (feature-flagged)
-        const funnelEnabled = config.features?.funnel !== false;
+        const funnelFeature = config.features?.funnel;
+        const funnelEnabled = funnelFeature !== false;
         if (funnelEnabled) {
+            const funnelConfig = typeof funnelFeature === 'object' ? funnelFeature : {};
             this.funnel = new FunnelClient({
                 apiClient: this.apiClient,
                 debugMode: this.state.debugMode,
                 pluginConfig: this.state.pluginConfig,
                 environment: this.state.environment,
+                autoRedirect: funnelConfig.autoRedirect,
             });
         }
         // Setup token waiting mechanism
@@ -75,6 +104,8 @@ export class TagadaClient {
         if (typeof window !== 'undefined') {
             window.addEventListener('storage', this.boundHandleStorageChange);
         }
+        // Setup config hot-reload listener (for live config editing)
+        this.setupConfigHotReload();
         // Start initialization
         this.initialize();
     }
@@ -89,6 +120,7 @@ export class TagadaClient {
             console.log(`[TagadaClient ${this.instanceId}] Destroyed`);
         }
         this.eventDispatcher.clear();
+        this.bus.clear();
     }
     /**
      * Handle storage changes (e.g. token update in another tab)
@@ -304,10 +336,17 @@ export class TagadaClient {
             return;
         }
         try {
-            if (this.state.debugMode)
-                console.log('[TagadaClient] Creating anonymous token for store:', storeId);
+            // 🎯 Check draft mode from URL, localStorage, or cookie
+            const draft = isDraftMode();
+            if (this.state.debugMode) {
+                console.log('[TagadaClient] Creating anonymous token for store:', storeId, { draft });
+            }
             // We use fetch directly or ApiClient with skipAuth to avoid waiting for itself
-            const response = await this.apiClient.post('/api/v1/cms/session/anonymous', { storeId, role: 'anonymous' }, { skipAuth: true });
+            const response = await this.apiClient.post('/api/v1/cms/session/anonymous', {
+                storeId,
+                role: 'anonymous',
+                draft, // 🎯 Pass draft mode to anonymous login
+            }, { skipAuth: true });
             this.setToken(response.token);
             setClientToken(response.token);
             const decodedSession = decodeJWTClient(response.token);
@@ -341,6 +380,13 @@ export class TagadaClient {
             const deviceInfo = collectDeviceInfo();
             const urlParams = getUrlParams();
             const browserLocale = getBrowserLocale();
+            // 🎯 Check draft mode from URL, localStorage, or cookie
+            const draft = isDraftMode();
+            // Store draft mode if detected from URL (urlParams may have draft from query string)
+            const draftParam = new URLSearchParams(window.location.search).get('draft');
+            if (draftParam !== null) {
+                setDraftMode(draftParam === 'true');
+            }
             const sessionInitData = {
                 storeId: sessionData.storeId,
                 accountId: sessionData.accountId,
@@ -361,6 +407,7 @@ export class TagadaClient {
                 screenWidth: deviceInfo.screenResolution.width,
                 screenHeight: deviceInfo.screenResolution.height,
                 timeZone: deviceInfo.timeZone,
+                draft, // 🎯 Pass draft mode to session init
             };
             const response = await this.apiClient.post('/api/v1/cms/session/init', sessionInitData);
             // Success - reset error tracking
@@ -472,4 +519,182 @@ export class TagadaClient {
         };
         return names[code] || code;
     }
+    /**
+     * Helper to get accountId with fallbacks
+     */
+    getAccountId() {
+        return this.state.store?.accountId || this.state.pluginConfig?.accountId || this.state.session?.accountId || '';
+    }
+    /**
+     * Update plugin config dynamically (hot-reload)
+     * Used for live config editing without page reload
+     */
+    updatePluginConfig(newConfig) {
+        if (this.state.debugMode) {
+            console.log('[TagadaClient] Hot-reloading config:', newConfig);
+        }
+        // Merge new config with existing
+        const updatedConfig = {
+            ...this.state.pluginConfig.config,
+            ...newConfig,
+        };
+        // Update state
+        this.updateState({
+            pluginConfig: {
+                ...this.state.pluginConfig,
+                config: updatedConfig,
+            },
+        });
+        // Emit config update event
+        this.bus.emit('CONFIG_UPDATED', updatedConfig);
+        if (this.state.debugMode) {
+            console.log('[TagadaClient] Config updated successfully');
+        }
+    }
+    /**
+     * Setup listener for config updates from parent window (config editor)
+     * Enables live config editing via postMessage
+     */
+    setupConfigHotReload() {
+        if (typeof window === 'undefined')
+            return;
+        const handleMessage = (event) => {
+            // Security: Only accept messages from same origin or trusted origins
+            // In production, you might want to check event.origin more strictly
+            if (event.data?.type === 'TAGADAPAY_CONFIG_UPDATE') {
+                const { config } = event.data;
+                if (this.state.debugMode) {
+                    console.log('[TagadaClient] Received config update from parent:', config);
+                }
+                this.updatePluginConfig(config);
+            }
+            else if (event.data?.type === 'APPLY_STYLES_TO_ELEMENT') {
+                const { elementId, styles } = event.data;
+                if (this.state.debugMode) {
+                    console.log('[TagadaClient] Received style application request:', { elementId, styles });
+                }
+                this.applyStylesToElement(elementId, styles);
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        if (this.state.debugMode) {
+            console.log('[TagadaClient] Config hot-reload and style manipulation listeners enabled');
+        }
+    }
+    /**
+     * Apply CSS properties to a real div child element for highlighting
+     * Used by config editor to highlight elements in preview without altering the element's style
+     */
+    applyStylesToElement(elementId, styles) {
+        if (typeof document === 'undefined')
+            return;
+        // Support multiple IDs in editor-id attribute (space-separated)
+        // Use ~= selector to match elementId as a space-separated value
+        const element = document.querySelector(`[editor-id~="${elementId}"]`);
+        if (!element) {
+            if (this.state.debugMode) {
+                console.warn(`[TagadaClient] Element with editor-id containing "${elementId}" not found`);
+            }
+            return;
+        }
+        // List of void/self-closing elements that don't accept children
+        const voidElements = new Set([
+            'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+            'link', 'meta', 'param', 'source', 'track', 'wbr'
+        ]);
+        const isVoidElement = voidElements.has(element.tagName.toLowerCase());
+        // For void elements, wrap them in a container div
+        let targetElement = element;
+        let wrapper = null;
+        if (isVoidElement) {
+            // Check if element is already wrapped (from a previous highlight)
+            const parent = element.parentElement;
+            const existingWrapper = parent?.getAttribute('data-tagada-highlight-wrapper');
+            if (existingWrapper === 'true') {
+                // Reuse existing wrapper
+                targetElement = parent;
+            }
+            else {
+                // Create a new wrapper
+                wrapper = document.createElement('div');
+                wrapper.setAttribute('data-tagada-highlight-wrapper', 'true');
+                // Preserve the element's layout behavior by matching its display style
+                // This minimizes the visual impact of the wrapper
+                const computedStyle = window.getComputedStyle(element);
+                const elementDisplay = computedStyle.display;
+                // Match the display type to preserve layout
+                // For inline elements, use inline-block (to support position: relative)
+                // For all others, use the same display value
+                if (elementDisplay === 'inline') {
+                    wrapper.style.display = 'inline-block';
+                }
+                else {
+                    wrapper.style.display = elementDisplay;
+                }
+                wrapper.style.position = 'relative';
+                // Preserve vertical alignment for inline elements
+                if (elementDisplay === 'inline' || elementDisplay.includes('inline')) {
+                    const verticalAlign = computedStyle.verticalAlign;
+                    if (verticalAlign && verticalAlign !== 'baseline') {
+                        wrapper.style.verticalAlign = verticalAlign;
+                    }
+                }
+                // Insert wrapper before element
+                element.parentNode?.insertBefore(wrapper, element);
+                // Move element into wrapper
+                wrapper.appendChild(element);
+                targetElement = wrapper;
+            }
+        }
+        // Ensure element has position relative for absolute child positioning
+        const computedStyle = getComputedStyle(isVoidElement ? element : targetElement);
+        if (targetElement.style.position === 'static' || !targetElement.style.position) {
+            targetElement.style.position = 'relative';
+        }
+        // Remove any existing highlight div before creating a new one
+        const staticHighlightId = 'tagada-editor-highlight';
+        const existingHighlight = document.getElementById(staticHighlightId);
+        if (existingHighlight) {
+            existingHighlight.remove();
+        }
+        // Create new highlight div with static ID
+        const highlightDiv = document.createElement('div');
+        highlightDiv.id = staticHighlightId;
+        highlightDiv.style.position = 'absolute';
+        highlightDiv.style.inset = '0';
+        highlightDiv.style.pointerEvents = 'none';
+        highlightDiv.style.zIndex = '9999';
+        highlightDiv.style.boxSizing = 'border-box';
+        highlightDiv.style.background = 'none';
+        highlightDiv.style.border = 'none';
+        highlightDiv.style.outline = 'none';
+        // Inherit border radius from parent
+        const borderRadius = computedStyle.borderRadius;
+        if (borderRadius) {
+            highlightDiv.style.borderRadius = borderRadius;
+        }
+        // Append the new highlight div to the target element
+        targetElement.appendChild(highlightDiv);
+        // Apply CSS properties to the highlight div
+        const stylesToApply = styles || { boxShadow: '0 0 0 2px rgb(239 68 68)' }; // Default red ring
+        Object.entries(stylesToApply).forEach(([property, value]) => {
+            // Convert kebab-case to camelCase for style object
+            const camelProperty = property.includes('-')
+                ? property.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+                : property;
+            // Use setProperty for kebab-case or direct assignment for camelCase
+            if (property.includes('-')) {
+                highlightDiv.style.setProperty(property, value);
+            }
+            else {
+                highlightDiv.style[camelProperty] = value;
+            }
+        });
+        // Scroll element into view
+        element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        if (this.state.debugMode) {
+            const appliedStyles = Object.entries(stylesToApply).map(([k, v]) => `${k}: ${v}`).join('; ');
+            console.log(`[TagadaClient] Applied styles to highlight div of element #${elementId}:`, appliedStyles);
+        }
+    }
 }

package/dist/v2/core/config/environment.d.ts

@@ -5,9 +5,14 @@ import { ApiConfig, Environment, EnvironmentConfig } from '../types';
  * This SDK uses RUNTIME hostname detection, NOT build-time environment variables.
  * This ensures the SDK always connects to the correct API based on where it's deployed.
  *
- * - Production domains → production API
- * - Dev/staging domains → development API
- * - Localhost/local IPs → local API (with optional override via window.__TAGADA_ENV__)
+ * Environment detection priority (highest to lowest):
+ * 1. **tagadaClientEnv** - Explicit override via URL param, localStorage, or cookie
+ *    Example: ?tagadaClientEnv=production
+ * 2. **Production domains** → production API (app.tagadapay.com)
+ * 3. **Dev/staging domains** → development API (app.tagadapay.dev, vercel.app, etc.)
+ * 4. **Localhost/local IPs** → local API (localhost, 127.0.0.1, etc.)
+ *    - Can be overridden via window.__TAGADA_ENV__.TAGADA_ENVIRONMENT
+ * 5. **Default fallback** → production API (safest for unknown domains)
  *
  * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
  * to prevent incorrect API connections when plugins are deployed to different environments.
@@ -18,6 +23,8 @@ import { ApiConfig, Environment, EnvironmentConfig } from '../types';
 export declare const ENVIRONMENT_CONFIGS: Record<Environment, ApiConfig>;
 /**
  * Get the environment configuration based on the current environment
+ *
+ * Checks for custom base URL override via tagadaClientBaseUrl parameter
  */
 export declare function getEnvironmentConfig(environment?: Environment): EnvironmentConfig;
 /**
@@ -32,6 +39,12 @@ export declare function getEndpointUrl(config: EnvironmentConfig, category: keyo
  * Auto-detect environment based on hostname and URL patterns at RUNTIME
  * ⚠️ IMPORTANT: Ignores build-time .env variables to ensure correct detection in all environments
  * .env variables are ONLY used for local development via window.__TAGADA_ENV__
+ *
+ * Priority (highest to lowest):
+ * 1. tagadaClientEnv - Explicit override via URL/localStorage/cookie
+ * 2. __TAGADA_ENV__ - Local development override
+ * 3. Hostname-based detection - Production/staging domains
+ * 4. Default fallback - Production (safest)
  */
 export declare function detectEnvironment(): Environment;
 /**

package/dist/v2/core/config/environment.js

@@ -1,12 +1,29 @@
+/**
+ * Get cookie value by name
+ */
+function getCookie(name) {
+    if (typeof document === 'undefined')
+        return null;
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2)
+        return parts.pop()?.split(';').shift() || null;
+    return null;
+}
 /**
  * ⚠️ IMPORTANT: Runtime Environment Detection
  *
  * This SDK uses RUNTIME hostname detection, NOT build-time environment variables.
  * This ensures the SDK always connects to the correct API based on where it's deployed.
  *
- * - Production domains → production API
- * - Dev/staging domains → development API
- * - Localhost/local IPs → local API (with optional override via window.__TAGADA_ENV__)
+ * Environment detection priority (highest to lowest):
+ * 1. **tagadaClientEnv** - Explicit override via URL param, localStorage, or cookie
+ *    Example: ?tagadaClientEnv=production
+ * 2. **Production domains** → production API (app.tagadapay.com)
+ * 3. **Dev/staging domains** → development API (app.tagadapay.dev, vercel.app, etc.)
+ * 4. **Localhost/local IPs** → local API (localhost, 127.0.0.1, etc.)
+ *    - Can be overridden via window.__TAGADA_ENV__.TAGADA_ENVIRONMENT
+ * 5. **Default fallback** → production API (safest for unknown domains)
  *
  * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
  * to prevent incorrect API connections when plugins are deployed to different environments.
@@ -66,6 +83,8 @@ export const ENVIRONMENT_CONFIGS = {
 };
 /**
  * Get the environment configuration based on the current environment
+ *
+ * Checks for custom base URL override via tagadaClientBaseUrl parameter
  */
 export function getEnvironmentConfig(environment = 'local') {
     const apiConfig = ENVIRONMENT_CONFIGS[environment];
@@ -76,6 +95,31 @@ export function getEnvironmentConfig(environment = 'local') {
             apiConfig: ENVIRONMENT_CONFIGS.local,
         };
     }
+    // 🎯 Check for custom base URL override (URL > localStorage > cookie)
+    let customBaseUrl = null;
+    if (typeof window !== 'undefined') {
+        const urlParams = new URLSearchParams(window.location.search);
+        customBaseUrl = urlParams.get('tagadaClientBaseUrl');
+        if (!customBaseUrl) {
+            try {
+                customBaseUrl = localStorage.getItem('tgd_client_base_url') || getCookie('tgd_client_base_url');
+            }
+            catch {
+                // Storage not available
+            }
+        }
+    }
+    // If custom base URL is set, override the apiConfig.baseUrl
+    if (customBaseUrl) {
+        console.log(`[SDK] Using custom API base URL override: ${customBaseUrl}`);
+        return {
+            environment,
+            apiConfig: {
+                ...apiConfig,
+                baseUrl: customBaseUrl,
+            },
+        };
+    }
     return {
         environment,
         apiConfig,
@@ -102,12 +146,37 @@ export function getEndpointUrl(config, category, endpoint) {
  * Auto-detect environment based on hostname and URL patterns at RUNTIME
  * ⚠️ IMPORTANT: Ignores build-time .env variables to ensure correct detection in all environments
  * .env variables are ONLY used for local development via window.__TAGADA_ENV__
+ *
+ * Priority (highest to lowest):
+ * 1. tagadaClientEnv - Explicit override via URL/localStorage/cookie
+ * 2. __TAGADA_ENV__ - Local development override
+ * 3. Hostname-based detection - Production/staging domains
+ * 4. Default fallback - Production (safest)
  */
 export function detectEnvironment() {
     // Check if we're in browser
     if (typeof window === 'undefined') {
         return 'local'; // SSR fallback
     }
+    // 🎯 PRIORITY 1: Check for explicit tagadaClientEnv override (URL > localStorage > cookie)
+    // This allows forcing environment regardless of hostname
+    const urlParams = new URLSearchParams(window.location.search);
+    const urlEnv = urlParams.get('tagadaClientEnv');
+    if (urlEnv && (urlEnv === 'production' || urlEnv === 'development' || urlEnv === 'local')) {
+        console.log(`[SDK] Using explicit environment override: ${urlEnv}`);
+        return urlEnv;
+    }
+    // Check localStorage/cookie for persisted override
+    try {
+        const storageEnv = localStorage.getItem('tgd_client_env') || getCookie('tgd_client_env');
+        if (storageEnv && (storageEnv === 'production' || storageEnv === 'development' || storageEnv === 'local')) {
+            console.log(`[SDK] Using persisted environment override: ${storageEnv}`);
+            return storageEnv;
+        }
+    }
+    catch {
+        // Storage not available
+    }
     const hostname = window.location.hostname;
     const href = window.location.href;
     // 1. Check for LOCAL environment first (highest priority for dev)

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

@@ -66,6 +66,10 @@ export declare class FunnelClient {
      * Navigate
      */
     navigate(event: FunnelAction): Promise<FunnelNavigationResult>;
+    /**
+     * Go to a specific step (direct navigation)
+     */
+    goToStep(stepId: string): Promise<FunnelNavigationResult>;
     /**
      * Refresh session data
      */