@tagadapay/plugin-sdk 3.0.3 → 3.0.12

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,7 +1,8 @@
+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>;
@@ -17,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 {
@@ -46,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;
@@ -112,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,6 +28,12 @@ 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();
         let envConfig = getEnvironmentConfig(env);
@@ -74,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
@@ -89,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();
     }
@@ -103,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)
@@ -318,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);
@@ -355,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,
@@ -375,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
@@ -486,4 +519,289 @@ 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;
+        // Always remove any existing highlight, even if the target element is not found
+        const staticHighlightId = 'tagada-editor-highlight';
+        const existingHighlight = document.getElementById(staticHighlightId);
+        if (existingHighlight) {
+            existingHighlight.remove();
+        }
+        const applyToElement = (element) => {
+            // 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;
+            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' && parent instanceof HTMLElement) {
+                    // Reuse existing wrapper
+                    targetElement = parent;
+                }
+                else {
+                    // Create a new wrapper
+                    const newWrapper = document.createElement('div');
+                    newWrapper.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') {
+                        newWrapper.style.display = 'inline-block';
+                    }
+                    else {
+                        newWrapper.style.display = elementDisplay;
+                    }
+                    newWrapper.style.position = 'relative';
+                    // Preserve vertical alignment for inline elements
+                    if (elementDisplay === 'inline' || elementDisplay.includes('inline')) {
+                        const verticalAlign = computedStyle.verticalAlign;
+                        if (verticalAlign && verticalAlign !== 'baseline') {
+                            newWrapper.style.verticalAlign = verticalAlign;
+                        }
+                    }
+                    // Preserve spacing and layout properties from the original element
+                    // List of CSS properties that affect spacing and layout
+                    const spacingProperties = [
+                        // Width and height
+                        'width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+                        // Flex properties
+                        'flex', 'flexGrow', 'flexShrink', 'flexBasis',
+                        // Grid properties
+                        'gridColumn', 'gridRow', 'gridColumnStart', 'gridColumnEnd',
+                        'gridRowStart', 'gridRowEnd', 'gridArea',
+                        // Alignment properties
+                        'alignSelf', 'justifySelf',
+                        // Box sizing
+                        'boxSizing',
+                        // Gap (for grid/flex)
+                        'gap', 'rowGap', 'columnGap',
+                        // Order (for flex/grid)
+                        'order',
+                        // Aspect ratio
+                        'aspectRatio',
+                    ];
+                    spacingProperties.forEach(prop => {
+                        const camelProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+                        const value = computedStyle.getPropertyValue(camelProp);
+                        // Only copy if the value is not empty
+                        // For most properties, we want to preserve the value even if it's 'auto' or '0px'
+                        // as these might be intentional layout choices
+                        if (value && value.trim() !== '') {
+                            // Handle special cases
+                            if (prop === 'flex' && value !== 'none' && value !== '0 1 auto') {
+                                newWrapper.style.flex = value;
+                            }
+                            else if (prop === 'boxSizing') {
+                                newWrapper.style.boxSizing = value;
+                            }
+                            else {
+                                // Use setProperty for kebab-case properties
+                                // Preserve all values including percentages, auto, etc.
+                                newWrapper.style.setProperty(camelProp, value);
+                            }
+                        }
+                    });
+                    // Also check inline styles for spacing properties
+                    // This handles cases where styles are set directly on the element
+                    if (element.style) {
+                        const inlineSpacingProps = [
+                            'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
+                            'flex', 'flex-grow', 'flex-shrink', 'flex-basis',
+                            'grid-column', 'grid-row', 'grid-column-start', 'grid-column-end',
+                            'grid-row-start', 'grid-row-end', 'grid-area',
+                            'align-self', 'justify-self',
+                            'box-sizing', 'gap', 'row-gap', 'column-gap', 'order', 'aspect-ratio'
+                        ];
+                        inlineSpacingProps.forEach(prop => {
+                            const inlineValue = element.style.getPropertyValue(prop);
+                            if (inlineValue) {
+                                newWrapper.style.setProperty(prop, inlineValue);
+                            }
+                        });
+                    }
+                    // Insert wrapper before element
+                    element.parentNode?.insertBefore(newWrapper, element);
+                    // Move element into wrapper
+                    newWrapper.appendChild(element);
+                    targetElement = newWrapper;
+                }
+            }
+            // 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';
+            }
+            // 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';
+            highlightDiv.style.margin = '0';
+            highlightDiv.style.padding = '0';
+            // 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);
+            }
+        };
+        // Support multiple IDs in editor-id attribute (space-separated)
+        // Use ~= selector to match elementId as a space-separated value
+        const maxAttempts = 5;
+        const intervalMs = 1000;
+        let attempts = 0;
+        const isElementHidden = (element) => {
+            const style = window.getComputedStyle(element);
+            return (style.display === 'none' ||
+                style.visibility === 'hidden' ||
+                style.opacity === '0' ||
+                element.hidden ||
+                element.offsetWidth === 0 ||
+                element.offsetHeight === 0);
+        };
+        const findAndApply = () => {
+            const elements = document.querySelectorAll(`[editor-id~="${elementId}"]`);
+            if (elements.length === 0) {
+                attempts += 1;
+                if (attempts >= maxAttempts) {
+                    if (this.state.debugMode) {
+                        console.warn(`[TagadaClient] Element with editor-id containing "${elementId}" not found after ${maxAttempts} attempts`);
+                    }
+                    return;
+                }
+                if (this.state.debugMode) {
+                    console.warn(`[TagadaClient] Element with editor-id containing "${elementId}" not found (attempt ${attempts}/${maxAttempts}), retrying in ${intervalMs / 1000}s`);
+                }
+                setTimeout(findAndApply, intervalMs);
+                return;
+            }
+            // If multiple elements found, prioritize the one that is not hidden
+            let element = null;
+            if (elements.length === 1) {
+                element = elements[0];
+            }
+            else {
+                // Find the first non-hidden element
+                for (let i = 0; i < elements.length; i++) {
+                    if (!isElementHidden(elements[i])) {
+                        element = elements[i];
+                        break;
+                    }
+                }
+                // If all are hidden, use the first one
+                if (!element) {
+                    element = elements[0];
+                }
+            }
+            if (element) {
+                applyToElement(element);
+            }
+        };
+        findAndApply();
+    }
 }

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