@tagadapay/plugin-sdk 2.8.10 → 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,6 +39,12 @@ 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;

package/dist/v2/core/client.js

@@ -5,6 +5,7 @@ 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();
@@ -58,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)
@@ -172,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);
             }
@@ -379,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'],
             };
@@ -412,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

@@ -34,3 +34,11 @@ export declare function getEndpointUrl(config: EnvironmentConfig, category: keyo
  * .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

@@ -153,3 +153,21 @@ export function detectEnvironment() {
     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;
+}

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

@@ -0,0 +1,84 @@
+import { ApiClient } from './resources/apiClient';
+import { SimpleFunnelContext, FunnelAction, FunnelNavigationResult } from './resources/funnel';
+import { PluginConfig } from './utils/pluginConfig';
+export interface FunnelClientConfig {
+    apiClient: ApiClient;
+    debugMode?: boolean;
+    pluginConfig?: PluginConfig;
+    environment?: {
+        environment: 'local' | 'development' | 'production' | 'staging';
+    };
+    /**
+     * Automatically redirect to result.url after navigation (default: true)
+     * Set to false if you want to handle navigation manually
+     */
+    autoRedirect?: boolean;
+}
+export interface FunnelState {
+    context: SimpleFunnelContext | null;
+    isLoading: boolean;
+    isInitialized: boolean;
+    isNavigating: boolean;
+    error: Error | null;
+    sessionError: Error | null;
+}
+export declare class FunnelClient {
+    state: FunnelState;
+    private resource;
+    private eventDispatcher;
+    private config;
+    private isInitializing;
+    private initializationAttempted;
+    constructor(config: FunnelClientConfig);
+    /**
+     * Update configuration (e.g. when plugin config loads)
+     */
+    setConfig(config: Partial<FunnelClientConfig>): void;
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(listener: (state: FunnelState) => void): () => void;
+    /**
+     * Get current state
+     */
+    getState(): FunnelState;
+    /**
+     * Initialize session with automatic detection (cookies, URL, etc.)
+     */
+    autoInitialize(authSession: {
+        customerId: string;
+        sessionId: string;
+    }, store: {
+        id: string;
+        accountId: string;
+    }, funnelId?: string): Promise<SimpleFunnelContext | null>;
+    /**
+     * Manual initialization
+     */
+    initialize(authSession: {
+        customerId: string;
+        sessionId: string;
+    }, store: {
+        id: string;
+        accountId: string;
+    }, funnelId?: string, entryStepId?: string): Promise<SimpleFunnelContext<{}>>;
+    /**
+     * Navigate
+     */
+    navigate(event: FunnelAction): Promise<FunnelNavigationResult>;
+    /**
+     * Refresh session data
+     */
+    refreshSession(): Promise<SimpleFunnelContext<{}> | undefined>;
+    /**
+     * Update context data
+     */
+    updateContext(updates: Partial<SimpleFunnelContext>): Promise<void>;
+    /**
+     * End session
+     */
+    endSession(): Promise<void>;
+    private updateState;
+    private handleSessionSuccess;
+    private enrichContext;
+}