@tagadapay/plugin-sdk 2.7.14 → 2.7.16

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

@@ -23,12 +23,26 @@ export interface PathInfo {
     /** URL hash without the # symbol */
     hash: string;
 }
+/**
+ * Result of route matching with extracted parameters
+ */
+export interface RouteMatchResult {
+    /** Whether the route matched */
+    matched: boolean;
+    /** Extracted URL parameters (empty object if no match or no params) */
+    params: Record<string, string>;
+}
 /**
  * Get the internal path that the plugin expects
  *
  * Reads from the meta tag injected by TagadaPay middleware.
  * Results are cached for performance.
  *
+ * **Development/Testing Mode (localhost only):**
+ * You can simulate path remapping in two ways:
+ * 1. Query parameter: `?__remap=/internal-path`
+ * 2. localStorage with explicit external → internal mapping
+ *
  * @returns The internal path from meta tag, or null if no remapping is active
  * @throws {Error} If called in a non-browser environment (SSR)
  *
@@ -39,6 +53,40 @@ export interface PathInfo {
  *   console.log('Remapped from external to:', internalPath);
  * }
  * ```
+ *
+ * @example Simulating remapping in localhost - RECOMMENDED FORMAT
+ * ```typescript
+ * // NEW: Explicit mapping (clear which path remaps to which)
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/myremap/:param',
+ *   internalPath: '/hello-with-param/:myparam'
+ * }));
+ * // Then navigate to: http://localhost:5173/myremap/test123
+ * // Result: Matches external pattern, uses internal path /hello-with-param/:myparam
+ *
+ * // Option 2: Query parameter (for quick tests)
+ * // Navigate to: http://localhost:5173/custom-page?__remap=/hello
+ *
+ * // Clear simulation
+ * localStorage.removeItem('tagadapay-remap');
+ * ```
+ *
+ * @example More Examples
+ * ```typescript
+ * // Remap /products/:id to /hello-with-param/:myparam
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/products/:id',
+ *   internalPath: '/hello-with-param/:myparam'
+ * }));
+ * // Visit: http://localhost:5173/products/abc123
+ *
+ * // Remap /custom-hello to /hello
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/custom-hello',
+ *   internalPath: '/hello'
+ * }));
+ * // Visit: http://localhost:5173/custom-hello
+ * ```
  */
 export declare function getInternalPath(): string | null;
 /**
@@ -72,6 +120,50 @@ export declare function isPathRemapped(): boolean;
  * ```
  */
 export declare function getPathInfo(): PathInfo;
+/**
+ * Match a route and extract URL parameters
+ *
+ * Handles path remapping automatically and extracts parameters from the URL.
+ * This is the preferred method when you need both match status and parameters.
+ *
+ * @param internalPath - The plugin's defined path (must start with /)
+ * @returns Object with `matched` boolean and `params` object
+ * @throws {Error} If internalPath is invalid
+ *
+ * @example
+ * ```typescript
+ * // In a catch-all route handler
+ * const result = matchRoute('/hello-with-param/:myparam');
+ * if (result.matched) {
+ *   console.log('Matched! Param:', result.params.myparam);
+ *   return <HelloPage myparam={result.params.myparam} />;
+ * }
+ * ```
+ */
+export declare function matchRoute(internalPath: string): RouteMatchResult;
+/**
+ * Check if the current URL should match a given internal path
+ *
+ * Handles path remapping automatically. Use this for catch-all routing
+ * implementations where you only need to check if a path matches.
+ *
+ * For extracting parameters, use `matchRoute()` instead.
+ *
+ * @param internalPath - The plugin's defined path (must start with /)
+ * @returns true if current URL should render this path's component
+ * @throws {Error} If internalPath is invalid
+ *
+ * @example
+ * ```typescript
+ * // In a catch-all route handler
+ * if (shouldMatchRoute('/hello')) {
+ *   return <HelloPage />;
+ * }
+ * if (shouldMatchRoute('/about')) {
+ *   return <AboutPage />;
+ * }
+ * ```
+ */
 export declare function shouldMatchRoute(internalPath: string): boolean;
 /**
  * Get the current matched path

package/dist/v2/core/pathRemapping.js

@@ -6,6 +6,7 @@
  *
  * @packageDocumentation
  */
+import { match } from 'path-to-regexp';
 // ============================================================================
 // Private Cache
 // ============================================================================
@@ -56,6 +57,11 @@ if (isBrowser) {
  * Reads from the meta tag injected by TagadaPay middleware.
  * Results are cached for performance.
  *
+ * **Development/Testing Mode (localhost only):**
+ * You can simulate path remapping in two ways:
+ * 1. Query parameter: `?__remap=/internal-path`
+ * 2. localStorage with explicit external → internal mapping
+ *
  * @returns The internal path from meta tag, or null if no remapping is active
  * @throws {Error} If called in a non-browser environment (SSR)
  *
@@ -66,6 +72,40 @@ if (isBrowser) {
  *   console.log('Remapped from external to:', internalPath);
  * }
  * ```
+ *
+ * @example Simulating remapping in localhost - RECOMMENDED FORMAT
+ * ```typescript
+ * // NEW: Explicit mapping (clear which path remaps to which)
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/myremap/:param',
+ *   internalPath: '/hello-with-param/:myparam'
+ * }));
+ * // Then navigate to: http://localhost:5173/myremap/test123
+ * // Result: Matches external pattern, uses internal path /hello-with-param/:myparam
+ *
+ * // Option 2: Query parameter (for quick tests)
+ * // Navigate to: http://localhost:5173/custom-page?__remap=/hello
+ *
+ * // Clear simulation
+ * localStorage.removeItem('tagadapay-remap');
+ * ```
+ *
+ * @example More Examples
+ * ```typescript
+ * // Remap /products/:id to /hello-with-param/:myparam
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/products/:id',
+ *   internalPath: '/hello-with-param/:myparam'
+ * }));
+ * // Visit: http://localhost:5173/products/abc123
+ *
+ * // Remap /custom-hello to /hello
+ * localStorage.setItem('tagadapay-remap', JSON.stringify({
+ *   externalPath: '/custom-hello',
+ *   internalPath: '/hello'
+ * }));
+ * // Visit: http://localhost:5173/custom-hello
+ * ```
  */
 export function getInternalPath() {
     // SSR check
@@ -77,12 +117,111 @@ export function getInternalPath() {
     }
     // Return cached value if available
     if (internalPathCache !== undefined) {
+        console.log('[TagadaPay SDK] 📦 Returning cached internal path:', internalPathCache);
         return internalPathCache;
     }
+    console.log('[TagadaPay SDK] 🔍 getInternalPath() called for:', window.location.pathname);
     try {
-        // Query the meta tag
+        // Development/Testing: Check for simulation via query parameter or localStorage
+        // Only works on localhost for security
+        const isLocalhost = window.location.hostname === 'localhost' ||
+            window.location.hostname === '127.0.0.1' ||
+            window.location.hostname.endsWith('.localhost');
+        console.log('[TagadaPay SDK] 🏠 isLocalhost:', isLocalhost);
+        if (isLocalhost) {
+            // Priority 1: Query parameter ?__remap=/internal-path
+            const urlParams = new URLSearchParams(window.location.search);
+            const queryRemap = urlParams.get('__remap');
+            console.log('[TagadaPay SDK] 🔍 Query parameter __remap:', queryRemap);
+            if (queryRemap) {
+                internalPathCache = queryRemap;
+                if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+                    console.log(`[TagadaPay SDK] 🔧 Simulating path remap via query: ${window.location.pathname} → ${queryRemap}`);
+                }
+                return queryRemap;
+            }
+            // Priority 2: localStorage tagadapay-remap
+            // Format: JSON object with external -> internal mapping
+            // Example: {"externalPath": "/myremap/:param", "internalPath": "/hello-with-param/:myparam"}
+            try {
+                const storageRemap = localStorage.getItem('tagadapay-remap');
+                console.log('[TagadaPay SDK] 🔍 localStorage tagadapay-remap:', storageRemap);
+                if (storageRemap) {
+                    try {
+                        // Try parsing as JSON first (new explicit format)
+                        const remapConfig = JSON.parse(storageRemap);
+                        console.log('[TagadaPay SDK] 📝 Parsed remap config:', remapConfig);
+                        if (remapConfig.externalPath && remapConfig.internalPath) {
+                            const currentPath = window.location.pathname;
+                            console.log('[TagadaPay SDK] 🔍 Checking if', currentPath, 'matches pattern', remapConfig.externalPath);
+                            // Check if current path matches the external path pattern
+                            const matchFn = match(remapConfig.externalPath, {
+                                decode: decodeURIComponent,
+                                end: true
+                            });
+                            const result = matchFn(currentPath);
+                            console.log('[TagadaPay SDK] 🎯 Match result:', result);
+                            if (result !== false) {
+                                // Current path matches the external pattern, return internal path
+                                internalPathCache = remapConfig.internalPath;
+                                console.log(`[TagadaPay SDK] ✅ Path remap: ${remapConfig.externalPath} → ${remapConfig.internalPath}`);
+                                console.log(`[TagadaPay SDK] ✅ Current URL ${currentPath} matches external pattern`);
+                                console.log('[TagadaPay SDK] 📦 Caching and returning:', remapConfig.internalPath);
+                                return remapConfig.internalPath;
+                            }
+                            else {
+                                // Current path doesn't match the external pattern, no remap
+                                console.log(`[TagadaPay SDK] ❌ Current URL ${currentPath} does NOT match external pattern ${remapConfig.externalPath}`);
+                                internalPathCache = null;
+                                return null;
+                            }
+                        }
+                        else {
+                            console.log('[TagadaPay SDK] ⚠️ Parsed config missing externalPath or internalPath');
+                        }
+                    }
+                    catch (jsonError) {
+                        // Not JSON, treat as legacy format (just internal path)
+                        console.log('[TagadaPay SDK] ⚠️ Failed to parse as JSON, using legacy format:', jsonError);
+                        internalPathCache = storageRemap;
+                        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+                            console.log(`[TagadaPay SDK] 🔧 Simulating path remap (legacy): ${window.location.pathname} → ${storageRemap}`);
+                        }
+                        return storageRemap;
+                    }
+                }
+                else {
+                    console.log('[TagadaPay SDK] 📭 No localStorage tagadapay-remap found');
+                }
+            }
+            catch (e) {
+                console.log('[TagadaPay SDK] ❌ localStorage error:', e);
+            }
+        }
+        // Production: Try to get internal path from full remap config first (new way)
+        const fullRemapMetaTag = document.querySelector('meta[name="tagadapay-path-remap"]');
+        if (fullRemapMetaTag) {
+            try {
+                const content = fullRemapMetaTag.getAttribute('content');
+                if (content) {
+                    const decodedContent = decodeURIComponent(content);
+                    const parsed = JSON.parse(decodedContent);
+                    if (parsed.internal) {
+                        console.log('[TagadaPay SDK] ✅ Got internal path from full remap config:', parsed.internal);
+                        internalPathCache = parsed.internal;
+                        return parsed.internal;
+                    }
+                }
+            }
+            catch (e) {
+                console.error('[TagadaPay SDK] Error parsing full remap config:', e);
+                // Fall through to try legacy meta tag
+            }
+        }
+        // Fallback: Try legacy meta tag (old way, for backward compatibility)
         const metaTag = document.querySelector('meta[name="x-plugin-internal-path"]');
         if (!metaTag) {
+            console.log('[TagadaPay SDK] ℹ️  No path remap meta tags found');
             internalPathCache = null;
             return null;
         }
@@ -104,6 +243,7 @@ export function getInternalPath() {
             internalPathCache = null;
             return null;
         }
+        console.log('[TagadaPay SDK] ✅ Got internal path from legacy meta tag:', trimmedContent);
         // Cache and return
         internalPathCache = trimmedContent;
         return trimmedContent;
@@ -207,36 +347,75 @@ export function getPathInfo() {
 /**
  * Helper function to match a path against a pattern using path-to-regexp
  * @param pathname - The actual path to test
- * @param pattern - The pattern to match against (can include :params)
- * @returns true if the path matches the pattern
+ * @param pattern - The pattern to match against (can include :params, wildcards, etc.)
+ * @returns Object with matched status and extracted params
  */
 function matchesPathPattern(pathname, pattern) {
     try {
         // Exact match (no pattern)
         if (pathname === pattern) {
-            return true;
+            return { matched: true, params: {} };
         }
-        // Check if pattern contains parameters (e.g., :id, :name)
-        if (!pattern.includes(':')) {
-            // No parameters - use simple prefix matching
-            return pathname.startsWith(pattern);
+        // Check if pattern contains special characters that require path-to-regexp
+        // :param, *wildcard, {optional}, etc.
+        const hasPatternSyntax = pattern.includes(':') || pattern.includes('*') || pattern.includes('{');
+        if (!hasPatternSyntax) {
+            // No pattern syntax - use exact match only
+            // For paths without parameters, we should match exactly, not with prefix
+            return { matched: pathname === pattern, params: {} };
         }
-        // Use path-to-regexp for parameterized patterns
-        // Import dynamically to avoid bundle size issues
-        const { match } = require('path-to-regexp');
-        const matchFn = match(pattern, { decode: decodeURIComponent, end: false });
+        // Use path-to-regexp for patterns with parameters, wildcards, or optional segments
+        const matchFn = match(pattern, {
+            decode: decodeURIComponent,
+            end: true
+        });
         const result = matchFn(pathname);
-        return result !== false;
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.log(`[TagadaPay SDK] Pattern match: "${pathname}" against "${pattern}" =`, result !== false);
+        }
+        if (result === false) {
+            return { matched: false, params: {} };
+        }
+        // Extract params from result
+        const params = {};
+        if (typeof result === 'object' && result.params) {
+            Object.keys(result.params).forEach(key => {
+                const value = result.params[key];
+                // Convert to string and handle arrays (for splat params)
+                params[key] = Array.isArray(value) ? value.join('/') : String(value);
+            });
+        }
+        return { matched: true, params };
     }
     catch (error) {
         // Fallback to exact match if path-to-regexp fails
         if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
             console.warn(`[TagadaPay SDK] Pattern matching failed for "${pattern}":`, error);
         }
-        return pathname === pattern || pathname.startsWith(pattern);
+        return { matched: pathname === pattern, params: {} };
     }
 }
-export function shouldMatchRoute(internalPath) {
+/**
+ * Match a route and extract URL parameters
+ *
+ * Handles path remapping automatically and extracts parameters from the URL.
+ * This is the preferred method when you need both match status and parameters.
+ *
+ * @param internalPath - The plugin's defined path (must start with /)
+ * @returns Object with `matched` boolean and `params` object
+ * @throws {Error} If internalPath is invalid
+ *
+ * @example
+ * ```typescript
+ * // In a catch-all route handler
+ * const result = matchRoute('/hello-with-param/:myparam');
+ * if (result.matched) {
+ *   console.log('Matched! Param:', result.params.myparam);
+ *   return <HelloPage myparam={result.params.myparam} />;
+ * }
+ * ```
+ */
+export function matchRoute(internalPath) {
     // Validate input
     if (typeof internalPath !== 'string') {
         throw new Error(`[TagadaPay SDK] internalPath must be a string, got ${typeof internalPath}`);
@@ -249,25 +428,120 @@ export function shouldMatchRoute(internalPath) {
     }
     // SSR check
     if (!isBrowser) {
-        return false;
+        return { matched: false, params: {} };
     }
     try {
         const currentPath = window.location.pathname;
         const remappedInternalPath = getInternalPath();
-        // If remapped, check if the remapped internal path matches the pattern
+        // If remapped, need to extract params from external URL using external pattern
         if (remappedInternalPath) {
-            return matchesPathPattern(remappedInternalPath, internalPath);
+            const internalMatch = matchesPathPattern(remappedInternalPath, internalPath);
+            if (!internalMatch.matched) {
+                return { matched: false, params: {} };
+            }
+            // Get the external pattern from remap config
+            let externalPattern = null;
+            // Check localStorage for remap config (development/testing)
+            if (typeof localStorage !== 'undefined') {
+                try {
+                    const remapData = localStorage.getItem('tagadapay-remap');
+                    if (remapData) {
+                        const parsed = JSON.parse(remapData);
+                        if (parsed.externalPath && parsed.internalPath === remappedInternalPath) {
+                            externalPattern = parsed.externalPath;
+                        }
+                    }
+                }
+                catch (e) {
+                    // Ignore parsing errors
+                }
+            }
+            // Check meta tag for production remap config
+            if (!externalPattern && typeof document !== 'undefined') {
+                console.log('[TagadaPay SDK] 🔍 Checking for production path remap meta tag...');
+                const metaTag = document.querySelector('meta[name="tagadapay-path-remap"]');
+                if (metaTag) {
+                    try {
+                        const content = metaTag.getAttribute('content');
+                        console.log('[TagadaPay SDK] 📄 Found meta tag content (encoded):', content?.substring(0, 100) + '...');
+                        if (content) {
+                            // Decode URL-encoded content before parsing
+                            const decodedContent = decodeURIComponent(content);
+                            console.log('[TagadaPay SDK] 📄 Decoded content:', decodedContent);
+                            const parsed = JSON.parse(decodedContent);
+                            console.log('[TagadaPay SDK] 📦 Parsed remap config:', parsed);
+                            console.log('[TagadaPay SDK] 🔍 Checking if internal path matches:', {
+                                parsedInternal: parsed.internal,
+                                remappedInternalPath
+                            });
+                            if (parsed.external && parsed.internal === remappedInternalPath) {
+                                externalPattern = parsed.external;
+                                console.log('[TagadaPay SDK] ✅ Using external pattern from meta tag:', externalPattern);
+                            }
+                            else {
+                                console.log('[TagadaPay SDK] ⚠️  Internal path mismatch - not using meta tag config');
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // Ignore parsing errors
+                        console.error('[TagadaPay SDK] ❌ Error parsing path remap meta tag:', e);
+                    }
+                }
+                else {
+                    console.log('[TagadaPay SDK] ❌ No tagadapay-path-remap meta tag found');
+                }
+            }
+            // Extract params from current URL using external pattern
+            if (externalPattern) {
+                const externalMatch = matchesPathPattern(currentPath, externalPattern);
+                if (externalMatch.matched) {
+                    // Since we enforce matching parameter names in CRM, 
+                    // the params extracted from external pattern will have the correct names
+                    return { matched: true, params: externalMatch.params };
+                }
+            }
+            // Fallback: try to extract from current URL using internal pattern
+            // (in case external pattern not found or doesn't match)
+            const currentMatch = matchesPathPattern(currentPath, internalPath);
+            return { matched: true, params: currentMatch.params };
         }
-        // No remapping - check if current path matches the pattern
+        // No remapping - match and extract from current path
         return matchesPathPattern(currentPath, internalPath);
     }
     catch (error) {
         if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
-            console.error('[TagadaPay SDK] Error in shouldMatchRoute:', error);
+            console.error('[TagadaPay SDK] Error in matchRoute:', error);
         }
-        return false;
+        return { matched: false, params: {} };
     }
 }
+/**
+ * Check if the current URL should match a given internal path
+ *
+ * Handles path remapping automatically. Use this for catch-all routing
+ * implementations where you only need to check if a path matches.
+ *
+ * For extracting parameters, use `matchRoute()` instead.
+ *
+ * @param internalPath - The plugin's defined path (must start with /)
+ * @returns true if current URL should render this path's component
+ * @throws {Error} If internalPath is invalid
+ *
+ * @example
+ * ```typescript
+ * // In a catch-all route handler
+ * if (shouldMatchRoute('/hello')) {
+ *   return <HelloPage />;
+ * }
+ * if (shouldMatchRoute('/about')) {
+ *   return <AboutPage />;
+ * }
+ * ```
+ */
+export function shouldMatchRoute(internalPath) {
+    return matchRoute(internalPath).matched;
+}
 /**
  * Get the current matched path
  *

package/dist/v2/core/resources/funnel.d.ts

@@ -6,6 +6,12 @@ export interface FunnelEvent {
     type: string;
     data?: any;
     timestamp?: string;
+    /**
+     * Current URL for session synchronization (browser back/forward handling)
+     * If not provided, SDK will automatically use window.location.href
+     * @example '/checkout', 'https://store.com/payment'
+     */
+    currentUrl?: string;
 }
 export interface FunnelNavigationAction {
     type: 'redirect' | 'replace' | 'push' | 'external' | 'none';
@@ -30,6 +36,11 @@ export interface SimpleFunnelContext {
     funnelId: string;
     currentStepId: string;
     previousStepId?: string;
+    /**
+     * Furthest step reached in the funnel (for progress tracking in cyclic funnels)
+     * Only moves forward, never backward - used for analytics
+     */
+    furthestStepId?: string;
     startedAt: number;
     lastActivityAt: number;
     metadata?: Record<string, any>;
@@ -54,6 +65,11 @@ export interface FunnelNavigateRequest {
     sessionId: string;
     event: FunnelEvent;
     contextUpdates?: Partial<SimpleFunnelContext>;
+    /**
+     * Current URL for URL-to-Step mapping (browser back/forward sync)
+     * Automatically extracted from event.currentUrl or window.location.href
+     */
+    currentUrl?: string;
 }
 export interface FunnelNavigateResponse {
     success: boolean;
@@ -100,8 +116,10 @@ export declare class FunnelResource {
     }>;
     /**
      * Get funnel session by ID
+     * @param sessionId - The session ID to fetch
+     * @param currentUrl - Optional current URL for session synchronization on page load
      */
-    getSession(sessionId: string): Promise<{
+    getSession(sessionId: string, currentUrl?: string): Promise<{
         success: boolean;
         context?: SimpleFunnelContext;
         error?: string;

package/dist/v2/core/resources/funnel.js

@@ -31,8 +31,12 @@ export class FunnelResource {
     }
     /**
      * Get funnel session by ID
+     * @param sessionId - The session ID to fetch
+     * @param currentUrl - Optional current URL for session synchronization on page load
      */
-    async getSession(sessionId) {
-        return this.apiClient.get(`/api/v1/funnel/session/${sessionId}`);
+    async getSession(sessionId, currentUrl) {
+        const params = currentUrl ? new URLSearchParams({ currentUrl }) : undefined;
+        const url = `/api/v1/funnel/session/${sessionId}${params ? `?${params}` : ''}`;
+        return this.apiClient.get(url);
     }
 }

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

@@ -65,6 +65,7 @@ export interface Order {
         firstName: string;
         lastName: string;
         address1: string;
+        address2?: string;
         city: string;
         country: string;
         state: string;

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

@@ -41,6 +41,17 @@ export interface CreateRawPluginConfigOptions {
  * @returns A RawPluginConfig object or undefined if required fields are missing
  */
 export declare function createRawPluginConfig(options?: CreateRawPluginConfigOptions): Promise<RawPluginConfig | undefined>;
+/**
+ * Simple helper to get local plugin config with minimal boilerplate
+ * Returns null if not in development or config not found
+ *
+ * @example
+ * const config = await localConfigIfAny('blue');
+ * if (config) {
+ *   console.log('Config loaded:', config);
+ * }
+ */
+export declare function localConfigIfAny(configName?: string): Promise<RawPluginConfig | null>;
 export declare class PluginConfigUtils {
     /**
      * Get plugin configuration from various sources

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

@@ -252,6 +252,34 @@ export async function createRawPluginConfig(options) {
         return undefined;
     }
 }
+/**
+ * Simple helper to get local plugin config with minimal boilerplate
+ * Returns null if not in development or config not found
+ *
+ * @example
+ * const config = await localConfigIfAny('blue');
+ * if (config) {
+ *   console.log('Config loaded:', config);
+ * }
+ */
+export async function localConfigIfAny(configName) {
+    try {
+        // Only work in localhost
+        const isLocalhost = typeof window !== 'undefined' &&
+            (window.location.hostname === 'localhost' ||
+                window.location.hostname.includes('.localhost') ||
+                window.location.hostname.includes('127.0.0.1'));
+        if (!isLocalhost) {
+            return null;
+        }
+        const rawConfig = await createRawPluginConfig();
+        return rawConfig || null;
+    }
+    catch (error) {
+        console.warn('[localConfigIfAny] Failed to load config:', error);
+        return null;
+    }
+}
 export class PluginConfigUtils {
     /**
      * Get plugin configuration from various sources

package/dist/v2/index.d.ts

@@ -22,7 +22,7 @@ export type { ApplyDiscountResponse, Discount, DiscountCodeValidation, RemoveDis
 export type { ToggleOrderBumpResponse, VipOffer, VipPreviewResponse } from './core/resources/vipOffers';
 export type { StoreConfig } from './core/resources/storeConfig';
 export type { FunnelContextUpdateRequest, FunnelContextUpdateResponse, FunnelEvent, FunnelInitializeRequest, FunnelInitializeResponse, FunnelNavigateRequest, FunnelNavigateResponse, FunnelNavigationAction, FunnelNavigationResult, SimpleFunnelContext } from './core/resources/funnel';
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLocalPluginConfig, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
 export type { TranslateFunction, TranslationText, UseTranslationOptions, UseTranslationResult } from './react/hooks/useTranslation';
 export type { ClubOffer, ClubOfferItem, ClubOfferLineItem, ClubOfferSummary, UseClubOffersOptions, UseClubOffersResult } from './react/hooks/useClubOffers';
 export type { UseLoginOptions, UseLoginResult } from './react/hooks/useLogin';

package/dist/v2/index.js

@@ -14,4 +14,4 @@ export * from './core/utils/products';
 // Path remapping helpers (framework-agnostic)
 export * from './core/pathRemapping';
 // React exports (hooks and components only, types are exported above)
-export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';
+export { ApplePayButton, ExpressPaymentMethodsProvider, formatMoney, getAvailableLanguages, GooglePayButton, queryKeys, TagadaProvider, useApiMutation, useApiQuery, useAuth, useCheckout, useCheckoutToken, useClubOffers, useCountryOptions, useCurrency, useCustomer, useCustomerInfos, useCustomerOrders, useCustomerSubscriptions, useDiscounts, useExpressPaymentMethods, useFunnel, useGeoLocation, useGoogleAutocomplete, useInvalidateQuery, useISOData, useLanguageImport, useLocalPluginConfig, useLogin, useOffers, useOrder, useOrderBump, usePayment, usePluginConfig, usePostPurchases, usePreloadQuery, useProducts, usePromotions, useRegionOptions, useRemappableParams, useShippingRates, useSimpleFunnel, useStoreConfig, useTagadaContext, useThreeds, useThreedsModal, useTranslation, useVipOffers } from './react';