@tagadapay/plugin-sdk 2.8.9 → 3.0.1

package/README.md

@@ -4,7 +4,7 @@ A comprehensive React SDK for building plugins on the TagadaPay platform. Create
 
 > **🚀 V2 Now Available!** The new V2 architecture features TanStack Query integration, improved TypeScript support, and better performance. [See V2 Architecture](#-v2-architecture) for details.
 >
-> **Recommended**: Use `@tagadapay/plugin-sdk/v2` for new projects. V1 (`/react`) is still supported for existing projects.
+> **Recommended**: Use `@tagadapay/plugin-sdk/v3` for new projects. V1 (`/react`) is still supported for existing projects.
 
 ## 📚 Documentation
 
@@ -146,7 +146,7 @@ import {
   useISOData,
   useCheckout,
   formatMoney,
-} from '@tagadapay/plugin-sdk/v2';
+} from '@tagadapay/plugin-sdk/v3';
 
 function MyPlugin() {
   const { config, storeId, accountId, basePath, loading } = usePluginConfig();
@@ -199,7 +199,7 @@ export default App;
 
 ### What's New in V2
 
-The TagadaPay Plugin SDK v2 introduces a clean architecture with significant improvements:
+The TagadaPay Plugin SDK v3 introduces a clean architecture with significant improvements:
 
 #### **🔄 TanStack Query Integration**
 
@@ -218,7 +218,7 @@ The TagadaPay Plugin SDK v2 introduces a clean architecture with significant imp
 
 ```tsx
 // V2 (Recommended)
-import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/v2';
+import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/v3';
 
 // Legacy (Still supported)
 import { useCheckout, useOffers, TagadaProvider } from '@tagadapay/plugin-sdk/react';
@@ -257,7 +257,7 @@ import {
   useProducts,
   usePluginConfig,
   formatMoney,
-} from '@tagadapay/plugin-sdk/v2';
+} from '@tagadapay/plugin-sdk/v3';
 
 function CheckoutPage() {
   const [checkoutToken, setCheckoutToken] = useState<string>();
@@ -355,7 +355,7 @@ function App() {
 
 ```tsx
 import React from 'react';
-import { TagadaProvider, useCheckout, useOffers, formatMoney } from '@tagadapay/plugin-sdk/v2';
+import { TagadaProvider, useCheckout, useOffers, formatMoney } from '@tagadapay/plugin-sdk/v3';
 
 // Component 1: Cart Summary
 function CartSummary({ checkoutToken }: { checkoutToken: string }) {
@@ -411,7 +411,7 @@ function CheckoutWithOffers() {
 
 ```tsx
 import React from 'react';
-import { useCheckout } from '@tagadapay/plugin-sdk/v2';
+import { useCheckout } from '@tagadapay/plugin-sdk/v3';
 
 function QuantitySelector({
   checkoutToken,
@@ -555,7 +555,7 @@ interface TagadaProviderProps {
 #### V2 Enhanced Provider Features
 
 ```tsx
-import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';
+import { TagadaProvider } from '@tagadapay/plugin-sdk/v3';
 
 function App() {
   return (
@@ -577,7 +577,7 @@ function App() {
 }
 ```
 
-> **Version Compatibility:** V2 features require `@tagadapay/plugin-sdk/v2`. The `blockUntilSessionReady` option was added in v2.3.0. For older versions, the blocking behavior was the default and only option.
+> **Version Compatibility:** V2 features require `@tagadapay/plugin-sdk/v3`. The `blockUntilSessionReady` option was added in v2.3.0. For older versions, the blocking behavior was the default and only option.
 
 ### Development vs Production
 
@@ -729,7 +729,7 @@ const {
 **Example:**
 
 ```tsx
-import { useStoreConfig } from '@tagadapay/plugin-sdk/v2';
+import { useStoreConfig } from '@tagadapay/plugin-sdk/v3';
 
 function StoreInfo() {
   const { storeConfig, isLoading } = useStoreConfig();
@@ -808,7 +808,7 @@ import {
   useInvalidateQuery,
   usePreloadQuery,
   queryKeys,
-} from '@tagadapay/plugin-sdk/v2';
+} from '@tagadapay/plugin-sdk/v3';
 
 // Custom API queries
 const { data, isLoading } = useApiQuery({
@@ -838,7 +838,7 @@ preloadCheckout({
 Enhanced money formatting with better TypeScript support:
 
 ```typescript
-import { formatMoney, convertCurrency, getCurrencyInfo } from '@tagadapay/plugin-sdk/v2';
+import { formatMoney, convertCurrency, getCurrencyInfo } from '@tagadapay/plugin-sdk/v3';
 
 // Format money with automatic currency detection
 const formatted = formatMoney(2999, 'USD'); // "$29.99"
@@ -867,7 +867,7 @@ import {
   ProductsResource,
   PaymentsResource,
   PluginConfigUtils,
-} from '@tagadapay/plugin-sdk/v2';
+} from '@tagadapay/plugin-sdk/v3';
 
 // Use core functions directly (useful for server-side or non-React contexts)
 const checkoutResource = new CheckoutResource(apiClient);
@@ -883,7 +883,7 @@ const isValid = PluginConfigUtils.validateConfig(config);
 V2 includes built-in debugging tools:
 
 ```tsx
-import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';
+import { TagadaProvider } from '@tagadapay/plugin-sdk/v3';
 
 function App() {
   return (

package/dist/index.js

@@ -15,5 +15,5 @@ export { convertCurrency, formatMoney, formatMoneyWithoutSymbol, formatSimpleMon
 // Export data utilities
 export * from './data/iso3166';
 export * from './data/languages';
-// V2 exports - new clean architecture
+// V2 exports - production-ready clean architecture
 export * from './v2';

package/dist/react/hooks/usePluginConfig.d.ts

@@ -23,6 +23,7 @@ export interface PluginConfig<TConfig = Record<string, any>> {
     accountId?: string;
     basePath?: string;
     config?: TConfig;
+    staticResources?: Record<string, any>;
 }
 export interface RawPluginConfig<TConfig = Record<string, any>> {
     storeId?: string;

package/dist/react/hooks/usePluginConfig.js

@@ -18,6 +18,7 @@
  *    - Headers for store/account info
  *    - Meta tags for deployment config
  */
+import { isLocalEnvironment } from '../../v2/core/config/environment';
 import { useTagadaContext } from '../providers/TagadaProvider';
 // Simple cache for plugin configuration
 let cachedConfig = null;
@@ -29,13 +30,7 @@ let configPromise = null;
 const loadLocalDevConfig = async (configVariant = 'default') => {
     try {
         // Only try to load local config in development
-        // Use hostname-based detection for better Vite compatibility
-        const isLocalDev = typeof window !== 'undefined' &&
-            (window.location.hostname === 'localhost' ||
-                window.location.hostname.includes('ngrok-free.app') ||
-                window.location.hostname.includes('.localhost') ||
-                window.location.hostname.includes('127.0.0.1'));
-        if (!isLocalDev) {
+        if (!isLocalEnvironment()) {
             return null;
         }
         // Load local store/account config
@@ -141,28 +136,89 @@ const loadProductionConfig = async () => {
         return { basePath: '/', config: {} };
     }
 };
+/**
+ * Load static resources for local development
+ * Loads /config/resources.static.json
+ */
+const loadStaticResources = async () => {
+    try {
+        // Only try to load in TRUE local development (not deployed CDN instances)
+        // Exclude CDN subdomains (e.g., instance-id.cdn.localhost)
+        if (!isLocalEnvironment(true)) {
+            console.log('🛠️ Not in local dev environment, skipping static resources loading');
+            return null;
+        }
+        // Load static resources file
+        console.log('🛠️ [V1] Attempting to load /config/resources.static.json...');
+        const response = await fetch('/config/resources.static.json');
+        if (!response.ok) {
+            console.log('🛠️ [V1] resources.static.json not found or failed to load');
+            return null;
+        }
+        const staticResources = await response.json();
+        console.log('🛠️ [V1] ✅ Loaded local static resources:', staticResources);
+        return staticResources;
+    }
+    catch (error) {
+        console.error('🛠️ ❌ Error loading static resources:', error);
+        return null;
+    }
+};
 /**
  * Load plugin configuration (cached)
  * Tries raw config first, then local dev config, then production config
  */
 export const loadPluginConfig = async (configVariant = 'default', rawConfig) => {
+    console.log('🔧 [V1] loadPluginConfig called with variant:', configVariant);
+    // Load static resources first (only in local dev)
+    const staticResources = await loadStaticResources();
+    console.log('🔧 [V1] Static resources loaded:', {
+        hasStaticResources: !!staticResources,
+        staticResourcesKeys: staticResources ? Object.keys(staticResources) : [],
+    });
     // If raw config is provided, use it directly
     if (rawConfig) {
-        console.log('🛠️ Using raw plugin config:', rawConfig);
-        return {
+        console.log('🛠️ [V1] Using raw plugin config:', rawConfig);
+        const result = {
             storeId: rawConfig.storeId,
             accountId: rawConfig.accountId,
             basePath: rawConfig.basePath ?? '/',
             config: rawConfig.config ?? {},
+            staticResources: staticResources ?? undefined,
         };
+        console.log('🔧 [V1] Final config (raw):', {
+            hasStoreId: !!result.storeId,
+            hasStaticResources: !!result.staticResources,
+            staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
+        });
+        return result;
     }
     // Try local development config
     const localConfig = await loadLocalDevConfig(configVariant);
     if (localConfig) {
-        return localConfig;
+        const result = {
+            ...localConfig,
+            staticResources: staticResources ?? undefined,
+        };
+        console.log('🔧 [V1] Final config (local):', {
+            hasStoreId: !!result.storeId,
+            hasStaticResources: !!result.staticResources,
+            staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
+        });
+        return result;
     }
     // Fall back to production config
-    return loadProductionConfig();
+    const productionConfig = await loadProductionConfig();
+    const result = {
+        ...productionConfig,
+        staticResources: staticResources ?? undefined,
+    };
+    console.log('🔧 [V1] Final config (production):', {
+        hasStoreId: !!result.storeId,
+        hasStaticResources: !!result.staticResources,
+        staticResourcesKeys: result.staticResources ? Object.keys(result.staticResources) : [],
+    });
+    return result;
 };
 /**
  * Main hook for plugin configuration
@@ -212,13 +268,8 @@ export const clearPluginConfigCache = () => {
  * Development helper to log current configuration
  */
 export const debugPluginConfig = async (configVariant = 'default', rawConfig) => {
-    // Use hostname-based detection for better Vite compatibility
-    const isLocalDev = typeof window !== 'undefined' &&
-        (window.location.hostname === 'localhost' ||
-            window.location.hostname.includes('ngrok-free.app') ||
-            window.location.hostname.includes('.localhost') ||
-            window.location.hostname.includes('127.0.0.1'));
-    if (!isLocalDev) {
+    // Check if we're in local development
+    if (!isLocalEnvironment()) {
         return;
     }
     const config = await getPluginConfig(configVariant, rawConfig);

package/dist/react/providers/TagadaProvider.js

@@ -49,10 +49,7 @@ export function TagadaProvider({ children, environment, customApiConfig, debugMo
 localConfig, blockUntilSessionReady = false, // Default to new non-blocking behavior
 rawPluginConfig, }) {
     // LOCAL DEV ONLY: Use localConfig override if in local development, otherwise use default
-    const isLocalDev = typeof window !== 'undefined' &&
-        (window.location.hostname === 'localhost' ||
-            window.location.hostname.includes('.localhost') ||
-            window.location.hostname.includes('127.0.0.1'));
+    const isLocalDev = detectEnvironment() === 'local';
     const configVariant = isLocalDev ? localConfig || 'default' : 'default';
     // Debug logging (only log once during initial render)
     const hasLoggedRef = useRef(false);

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

@@ -1,12 +1,24 @@
 import { ApiClient } from './resources/apiClient';
 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;
     debugMode?: boolean;
     localConfig?: string;
     rawPluginConfig?: RawPluginConfig;
     blockUntilSessionReady?: boolean;
+    /**
+     * Optional feature flags to enable/disable subsystems.
+     * By default all features are enabled.
+     */
+    features?: {
+        /**
+         * Funnel session + navigation layer.
+         * Set to false to completely disable funnel behaviour.
+         */
+        funnel?: boolean;
+    };
 }
 export interface TagadaState {
     auth: AuthState;
@@ -27,12 +39,22 @@ export interface TagadaState {
 export declare class TagadaClient {
     apiClient: ApiClient;
     state: TagadaState;
+    /**
+     * Optional funnel client.
+     * Exposed so higher-level SDKs (React, Standalone, Vue) can reuse the same
+     * low-level logic without instantiating a second client.
+     */
+    funnel?: FunnelClient;
     private eventDispatcher;
     private tokenPromise;
     private tokenResolver;
     private boundHandleStorageChange;
     private readonly config;
     private instanceId;
+    private isInitializingSession;
+    private lastSessionInitError;
+    private sessionInitRetryCount;
+    private readonly MAX_SESSION_INIT_RETRIES;
     constructor(config?: TagadaClientConfig);
     /**
      * Cleanup client resources

package/dist/v2/core/client.js

@@ -5,11 +5,17 @@ import { collectDeviceInfo, getBrowserLocale, getUrlParams } from './utils/devic
 import { decodeJWTClient, isTokenExpired } from './utils/jwtDecoder';
 import { getClientToken, setClientToken } from './utils/tokenStorage';
 import { EventDispatcher } from './utils/eventDispatcher';
+import { FunnelClient } from './funnelClient';
 export class TagadaClient {
     constructor(config = {}) {
         this.eventDispatcher = new EventDispatcher();
         this.tokenPromise = null;
         this.tokenResolver = null;
+        // Track initialization state to prevent infinite loops
+        this.isInitializingSession = false;
+        this.lastSessionInitError = null;
+        this.sessionInitRetryCount = 0;
+        this.MAX_SESSION_INIT_RETRIES = 3;
         this.config = config;
         this.instanceId = Math.random().toString(36).substr(2, 9);
         this.boundHandleStorageChange = this.handleStorageChange.bind(this);
@@ -53,6 +59,16 @@ export class TagadaClient {
         this.apiClient = new ApiClient({
             baseURL: envConfig.apiConfig.baseUrl,
         });
+        // Initialize optional funnel client (feature-flagged)
+        const funnelEnabled = config.features?.funnel !== false;
+        if (funnelEnabled) {
+            this.funnel = new FunnelClient({
+                apiClient: this.apiClient,
+                debugMode: this.state.debugMode,
+                pluginConfig: this.state.pluginConfig,
+                environment: this.state.environment,
+            });
+        }
         // Setup token waiting mechanism
         this.apiClient.setTokenProvider(this.waitForToken.bind(this));
         // Listen for storage changes (cross-tab sync)
@@ -86,6 +102,20 @@ export class TagadaClient {
             }
             return;
         }
+        // Prevent infinite loop: Don't re-initialize if we're currently initializing
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization in progress, skipping storage change`);
+            }
+            return;
+        }
+        // Prevent infinite loop: Don't retry if we've hit max retries
+        if (this.sessionInitRetryCount >= this.MAX_SESSION_INIT_RETRIES && this.lastSessionInitError) {
+            if (this.state.debugMode) {
+                console.error(`[TagadaClient ${this.instanceId}] Max session init retries reached, giving up`, this.lastSessionInitError);
+            }
+            return;
+        }
         // Re-run initialization when token may have changed
         if (this.state.debugMode) {
             console.log(`[TagadaClient ${this.instanceId}] Storage changed, re-initializing token...`);
@@ -153,6 +183,13 @@ export class TagadaClient {
                 pluginConfig: config,
                 pluginConfigLoading: false,
             });
+            // Keep funnel client in sync with latest plugin config / environment
+            if (this.funnel) {
+                this.funnel.setConfig({
+                    pluginConfig: config,
+                    environment: this.state.environment,
+                });
+            }
             if (this.state.debugMode) {
                 console.log('[TagadaClient] Plugin config loaded:', config);
             }
@@ -259,6 +296,13 @@ export class TagadaClient {
      * Create anonymous token
      */
     async createAnonymousToken(storeId) {
+        // Prevent concurrent anonymous token creation
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization in progress, skipping anonymous token creation`);
+            }
+            return;
+        }
         try {
             if (this.state.debugMode)
                 console.log('[TagadaClient] Creating anonymous token for store:', storeId);
@@ -282,6 +326,14 @@ export class TagadaClient {
      * Initialize session
      */
     async initializeSession(sessionData) {
+        // Prevent concurrent initialization attempts
+        if (this.isInitializingSession) {
+            if (this.state.debugMode) {
+                console.log(`[TagadaClient ${this.instanceId}] Session initialization already in progress, skipping`);
+            }
+            return;
+        }
+        this.isInitializingSession = true;
         try {
             if (this.state.debugMode) {
                 console.log(`[TagadaClient ${this.instanceId}] Initializing session...`, { sessionId: sessionData.sessionId });
@@ -311,6 +363,9 @@ export class TagadaClient {
                 timeZone: deviceInfo.timeZone,
             };
             const response = await this.apiClient.post('/api/v1/cms/session/init', sessionInitData);
+            // Success - reset error tracking
+            this.lastSessionInitError = null;
+            this.sessionInitRetryCount = 0;
             // Update state with session data
             this.updateSessionState(response, sessionData);
             this.updateState({
@@ -322,12 +377,19 @@ export class TagadaClient {
                 console.log('[TagadaClient] Session initialized successfully');
         }
         catch (error) {
-            console.error('[TagadaClient] Error initializing session:', error);
+            // Track error and increment retry count
+            this.lastSessionInitError = error;
+            this.sessionInitRetryCount++;
+            console.error(`[TagadaClient] Error initializing session (attempt ${this.sessionInitRetryCount}/${this.MAX_SESSION_INIT_RETRIES}):`, error);
             this.updateState({
                 isInitialized: true,
                 isLoading: false,
             });
         }
+        finally {
+            // Always release the lock
+            this.isInitializingSession = false;
+        }
     }
     updateSessionState(response, sessionData) {
         // Update Store
@@ -335,6 +397,8 @@ export class TagadaClient {
             const storeData = response.store;
             const storeConfig = {
                 ...response.store,
+                // Ensure accountId is included - fallback to plugin config or session accountId
+                accountId: storeData.accountId || this.state.pluginConfig?.accountId || sessionData.accountId || '',
                 presentmentCurrencies: storeData.presentmentCurrencies || [response.store.currency || 'USD'],
                 chargeCurrencies: storeData.chargeCurrencies || [response.store.currency || 'USD'],
             };
@@ -368,6 +432,31 @@ export class TagadaClient {
             customer: response.customer ?? null,
             auth: authState
         });
+        // Auto-initialize funnel if enabled
+        // This runs after we have all required data: auth.session, store, accountId
+        if (this.funnel && sessionData.customerId && response.store?.id) {
+            const accountId = response.store.accountId || this.state.pluginConfig?.accountId || sessionData.accountId || '';
+            if (accountId) {
+                // Get funnelId from URL or config
+                const urlParams = new URLSearchParams(typeof window !== 'undefined' ? window.location.search : '');
+                const funnelId = urlParams.get('funnelId') || undefined;
+                if (this.state.debugMode) {
+                    console.log('[TagadaClient] Auto-initializing funnel...', {
+                        customerId: sessionData.customerId,
+                        storeId: response.store.id,
+                        accountId,
+                        funnelId: funnelId || 'auto-detect',
+                    });
+                }
+                // Auto-initialize funnel in background (don't block session init)
+                this.funnel.autoInitialize({ customerId: sessionData.customerId, sessionId: sessionData.sessionId }, { id: response.store.id, accountId }, funnelId).catch((err) => {
+                    console.error('[TagadaClient] Funnel auto-initialization failed:', err);
+                });
+            }
+            else {
+                console.warn('[TagadaClient] Cannot auto-initialize funnel: accountId is missing');
+            }
+        }
     }
     // Helper methods
     getCurrencySymbol(code) {

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

@@ -1,4 +1,17 @@
 import { ApiConfig, Environment, EnvironmentConfig } from '../types';
+/**
+ * ⚠️ 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__)
+ *
+ * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
+ * to prevent incorrect API connections when plugins are deployed to different environments.
+ */
 /**
  * Environment configurations for different deployment environments
  */
@@ -16,7 +29,16 @@ export declare function buildApiUrl(config: EnvironmentConfig, endpointPath: str
  */
 export declare function getEndpointUrl(config: EnvironmentConfig, category: keyof ApiConfig['endpoints'], endpoint: string): string;
 /**
- * Auto-detect environment based on hostname, URL patterns, and deployment context
- * Works with any build tool or deployment system
+ * 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__
  */
 export declare function detectEnvironment(): Environment;
+/**
+ * Check if we're running in local development environment
+ * Uses centralized detectEnvironment() for consistency
+ *
+ * @param excludeCdn - If true, excludes CDN subdomains (e.g., instance-id.cdn.localhost)
+ * @returns true if in local environment (excluding CDN if specified)
+ */
+export declare function isLocalEnvironment(excludeCdn?: boolean): boolean;

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

@@ -1,4 +1,16 @@
-import { resolveEnvValue } from '../utils/env';
+/**
+ * ⚠️ 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__)
+ *
+ * Build-time .env variables (VITE_*, REACT_APP_*, NEXT_PUBLIC_*) are IGNORED
+ * to prevent incorrect API connections when plugins are deployed to different environments.
+ */
 /**
  * Environment configurations for different deployment environments
  */
@@ -87,33 +99,45 @@ export function getEndpointUrl(config, category, endpoint) {
     return buildApiUrl(config, endpointPath);
 }
 /**
- * Auto-detect environment based on hostname, URL patterns, and deployment context
- * Works with any build tool or deployment system
+ * 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__
  */
 export function detectEnvironment() {
-    // 1. Check environment variables first
-    const envVar = resolveEnvValue('TAGADA_ENVIRONMENT') || resolveEnvValue('TAGADA_ENV');
-    if (envVar) {
-        const normalized = envVar.toLowerCase();
-        if (normalized === 'production' || normalized === 'development' || normalized === 'local') {
-            return normalized;
-        }
-    }
     // Check if we're in browser
     if (typeof window === 'undefined') {
         return 'local'; // SSR fallback
     }
     const hostname = window.location.hostname;
     const href = window.location.href;
-    // Production: deployed to production domains
+    // 1. Check for LOCAL environment first (highest priority for dev)
+    // Local: localhost, local IPs, or local domains
+    if (hostname === 'localhost' ||
+        hostname.startsWith('127.') ||
+        hostname.startsWith('192.168.') ||
+        hostname.startsWith('10.') ||
+        hostname.includes('.local') ||
+        hostname === '' ||
+        hostname === '0.0.0.0') {
+        // For local development, allow override via window.__TAGADA_ENV__ (injected by dev server)
+        if (typeof window !== 'undefined' && window?.__TAGADA_ENV__?.TAGADA_ENVIRONMENT) {
+            const override = window.__TAGADA_ENV__.TAGADA_ENVIRONMENT.toLowerCase();
+            if (override === 'production' || override === 'development' || override === 'local') {
+                console.log(`[SDK] Local override detected: ${override}`);
+                return override;
+            }
+        }
+        return 'local';
+    }
+    // 2. Production: deployed to production domains
     if (hostname === 'app.tagadapay.com' ||
         hostname.includes('tagadapay.com') ||
         hostname.includes('yourproductiondomain.com')) {
         return 'production';
     }
-    // Development: deployed to staging/dev domains or has dev indicators
+    // 3. Development: deployed to staging/dev domains or has dev indicators
     if (hostname === 'app.tagadapay.dev' ||
-        hostname.includes('tagadapay.dev') || // ✅ app.tagadapay.dev and subdomains
+        hostname.includes('tagadapay.dev') ||
         hostname.includes('vercel.app') ||
         hostname.includes('netlify.app') ||
         hostname.includes('surge.sh') ||
@@ -125,16 +149,25 @@ export function detectEnvironment() {
         href.includes('#dev')) {
         return 'development';
     }
-    // Local: localhost, local IPs, or local domains
-    if (hostname === 'localhost' ||
-        hostname.startsWith('127.') ||
-        hostname.startsWith('192.168.') ||
-        hostname.startsWith('10.') ||
-        hostname.includes('.local') ||
-        hostname === '' ||
-        hostname === '0.0.0.0') {
-        return 'local';
-    }
-    // Default fallback for unknown domains (safer to use development)
+    // 4. Default fallback for unknown domains (production is safest)
+    console.warn(`[SDK] Unknown domain: ${hostname}, defaulting to production`);
     return 'production';
 }
+/**
+ * Check if we're running in local development environment
+ * Uses centralized detectEnvironment() for consistency
+ *
+ * @param excludeCdn - If true, excludes CDN subdomains (e.g., instance-id.cdn.localhost)
+ * @returns true if in local environment (excluding CDN if specified)
+ */
+export function isLocalEnvironment(excludeCdn = false) {
+    const env = detectEnvironment();
+    if (env !== 'local') {
+        return false;
+    }
+    // If we need to exclude CDN subdomains
+    if (excludeCdn && typeof window !== 'undefined') {
+        return !window.location.hostname.includes('.cdn.');
+    }
+    return true;
+}