@tagadapay/plugin-sdk 2.4.34 → 2.4.36

package/dist/react/hooks/useFunnel.js

@@ -0,0 +1,385 @@
+import { useState, useCallback, useEffect } from 'react';
+import { useTagadaContext } from '../providers/TagadaProvider';
+/**
+ * React Hook for Funnel Navigation (Plugin SDK Version)
+ *
+ * Simplified funnel navigation using KV storage for funnel sessions.
+ * Integrates with TagadaPay authentication and plugin routing.
+ */
+export function useFunnel(options) {
+    const { auth, apiService, store } = useTagadaContext();
+    const [isLoading, setIsLoading] = useState(false);
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [context, setContext] = useState(null);
+    const [initializationAttempted, setInitializationAttempted] = useState(false);
+    const [initializationError, setInitializationError] = useState(null);
+    const currentStepId = options.currentStepId || context?.currentStepId;
+    // Check for URL parameter overrides
+    const urlParams = typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : new URLSearchParams();
+    const urlFunnelId = urlParams.get('funnelId') || undefined;
+    const effectiveFunnelId = urlFunnelId || options.funnelId;
+    // Removed checkExistingSession - now handled in single initialize call
+    /**
+     * Set funnel session cookie
+     */
+    const setSessionCookie = useCallback((sessionId) => {
+        const maxAge = 24 * 60 * 60; // 24 hours
+        const expires = new Date(Date.now() + maxAge * 1000).toUTCString();
+        // Set cookie for same-domain scenarios
+        document.cookie = `tgd-funnel-session-id=${sessionId}; path=/; expires=${expires}; SameSite=Lax`;
+        console.log(`🍪 Funnel: Set session cookie: ${sessionId}`);
+    }, []);
+    /**
+     * Initialize funnel session
+     */
+    const initializeSession = useCallback(async (entryStepId) => {
+        if (!auth.session?.customerId || !store?.id) {
+            throw new Error('Authentication required for funnel session');
+        }
+        setIsLoading(true);
+        setInitializationAttempted(true);
+        setInitializationError(null);
+        try {
+            // Check for existing session ID in URL parameters
+            let existingSessionId = urlParams.get('funnelSessionId') || undefined;
+            if (existingSessionId) {
+                console.log(`🍪 Funnel: Found session ID in URL params: ${existingSessionId}`);
+            }
+            else {
+                // Fallback to cookie for same-domain scenarios
+                const funnelSessionCookie = document.cookie
+                    .split('; ')
+                    .find(row => row.startsWith('tgd-funnel-session-id='));
+                existingSessionId = funnelSessionCookie ? funnelSessionCookie.split('=')[1] : undefined;
+                if (existingSessionId) {
+                    console.log(`🍪 Funnel: Found session in cookie: ${existingSessionId}`);
+                }
+            }
+            if (!existingSessionId) {
+                console.log(`🍪 Funnel: No existing session found in URL params or cookie`);
+            }
+            // Use URL funnel ID if provided, otherwise use options (or undefined for backend fallback)
+            const effectiveFunnelId = urlFunnelId || options.funnelId;
+            // Send minimal CMS session data
+            const cmsSessionData = {
+                customerId: auth.session.customerId,
+                storeId: store.id,
+                sessionId: auth.session.sessionId,
+                accountId: auth.session.accountId
+            };
+            // Get current pathname with fallback
+            const currentPathname = typeof window !== 'undefined' ? window.location.pathname : '/';
+            console.log(`🍪 Funnel: Current pathname: "${currentPathname}"`);
+            // Call API to initialize session - backend will restore existing or create new
+            const requestBody = {
+                cmsSession: cmsSessionData,
+                entryStepId, // Optional override
+                existingSessionId // Pass existing session ID from URL or cookie
+            };
+            // Only include funnelId if it's provided (for backend fallback)
+            if (effectiveFunnelId) {
+                requestBody.funnelId = effectiveFunnelId;
+            }
+            const response = await apiService.fetch('/api/v1/funnel/initialize', {
+                method: 'POST',
+                body: requestBody
+            });
+            if (response.success && response.context) {
+                // Backend returns the initialized session
+                setContext(response.context);
+                setIsInitialized(true);
+                // Set session cookie for persistence across page reloads
+                setSessionCookie(response.context.sessionId);
+                console.log(`🍪 Funnel: Initialized new session for funnel ${effectiveFunnelId || 'default'}`, response.context);
+            }
+            else {
+                throw new Error(response.error || 'Failed to initialize funnel session');
+            }
+        }
+        catch (error) {
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            setInitializationError(errorObj);
+            console.error('Error initializing funnel session:', error);
+            if (options.onError) {
+                options.onError(errorObj);
+            }
+            throw error;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [auth.session?.customerId, store?.id, effectiveFunnelId, apiService, options.onError]);
+    /**
+     * Navigate to next step based on event
+     */
+    const next = useCallback(async (event) => {
+        if (!context) {
+            throw new Error('Funnel session not initialized');
+        }
+        if (!context.sessionId) {
+            throw new Error('Funnel session ID missing - session may be corrupted');
+        }
+        setIsLoading(true);
+        try {
+            console.log(`🍪 Funnel: Navigating with session ID: ${context.sessionId}`);
+            const response = await apiService.fetch('/api/v1/funnel/navigate', {
+                method: 'POST',
+                body: {
+                    sessionId: context.sessionId, // Send session ID for navigation
+                    event: {
+                        type: event.type,
+                        data: event.data,
+                        timestamp: event.timestamp?.toISOString() || new Date().toISOString()
+                    },
+                    contextUpdates: {
+                        lastActivityAt: Date.now()
+                    }
+                }
+            });
+            if (response.success && response.result) {
+                const result = response.result;
+                // Update local context
+                const newContext = {
+                    ...context,
+                    currentStepId: result.stepId,
+                    previousStepId: context.currentStepId,
+                    lastActivityAt: Date.now(),
+                    metadata: {
+                        ...context.metadata,
+                        lastEvent: event.type,
+                        lastTransition: new Date().toISOString()
+                    }
+                };
+                setContext(newContext);
+                // Create typed navigation result
+                const navigationResult = {
+                    stepId: result.stepId,
+                    action: {
+                        type: 'redirect', // Default action type
+                        url: result.url
+                    },
+                    context: newContext,
+                    tracking: result.tracking
+                };
+                // Handle navigation callback with override capability
+                let shouldPerformDefaultNavigation = true;
+                if (options.onNavigate) {
+                    const callbackResult = options.onNavigate(navigationResult);
+                    if (callbackResult === false) {
+                        shouldPerformDefaultNavigation = false;
+                    }
+                }
+                // Perform default navigation if not overridden
+                if (shouldPerformDefaultNavigation && navigationResult.action.url) {
+                    // Add URL parameters for cross-domain session continuity
+                    const urlWithParams = addSessionParams(navigationResult.action.url, newContext.sessionId, effectiveFunnelId || options.funnelId);
+                    const updatedAction = { ...navigationResult.action, url: urlWithParams };
+                    performNavigation(updatedAction);
+                }
+                console.log(`🍪 Funnel: Navigated from ${context.currentStepId} to ${result.stepId}`);
+                return result;
+            }
+            else {
+                throw new Error(response.error || 'Navigation failed');
+            }
+        }
+        catch (error) {
+            console.error('Funnel navigation error:', error);
+            if (options.onError) {
+                options.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+            throw error;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [context, apiService, options.onNavigate, options.onError]);
+    /**
+     * Go directly to a specific step (bypass conditions)
+     */
+    const goToStep = useCallback(async (stepId) => {
+        return next({
+            type: 'direct_navigation',
+            data: { targetStepId: stepId },
+            timestamp: new Date()
+        });
+    }, [next]);
+    /**
+     * Update funnel context
+     */
+    const updateContext = useCallback(async (updates) => {
+        if (!context) {
+            throw new Error('Funnel session not initialized');
+        }
+        setIsLoading(true);
+        try {
+            const response = await apiService.fetch('/api/v1/funnel/context', {
+                method: 'PATCH',
+                body: {
+                    contextUpdates: updates
+                }
+            });
+            if (response.success) {
+                const updatedContext = {
+                    ...context,
+                    ...updates,
+                    lastActivityAt: Date.now()
+                };
+                setContext(updatedContext);
+                console.log(`🍪 Funnel: Updated context for step ${context.currentStepId}`);
+            }
+            else {
+                throw new Error(response.error || 'Context update failed');
+            }
+        }
+        catch (error) {
+            console.error('Error updating funnel context:', error);
+            if (options.onError) {
+                options.onError(error instanceof Error ? error : new Error(String(error)));
+            }
+            throw error;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [context, apiService, options.onError]);
+    /**
+     * End current funnel session
+     */
+    const endSession = useCallback(async () => {
+        if (!context) {
+            return;
+        }
+        try {
+            await apiService.fetch(`/api/v1/funnel/session/${context.sessionId}`, {
+                method: 'DELETE'
+            });
+            setContext(null);
+            setIsInitialized(false);
+            console.log(`🍪 Funnel: Ended session ${context.sessionId}`);
+        }
+        catch (error) {
+            console.error('Error ending funnel session:', error);
+            // Don't throw here - session ending is best effort
+        }
+    }, [context, apiService]);
+    /**
+     * Add session parameters to URL for cross-domain continuity
+     */
+    const addSessionParams = useCallback((url, sessionId, funnelId) => {
+        try {
+            const urlObj = new URL(url);
+            urlObj.searchParams.set('funnelSessionId', sessionId);
+            if (funnelId) {
+                urlObj.searchParams.set('funnelId', funnelId);
+            }
+            const urlWithParams = urlObj.toString();
+            console.log(`🍪 Funnel: Added session params to URL: ${url} → ${urlWithParams}`);
+            return urlWithParams;
+        }
+        catch (error) {
+            console.warn('Failed to add session params to URL:', error);
+            return url; // Return original URL if parsing fails
+        }
+    }, []);
+    /**
+     * Perform navigation based on action type
+     */
+    const performNavigation = useCallback((action) => {
+        if (!action.url)
+            return;
+        // Handle relative URLs by making them absolute
+        let targetUrl = action.url;
+        if (targetUrl.startsWith('/') && !targetUrl.startsWith('//')) {
+            // Relative URL - use current origin
+            targetUrl = window.location.origin + targetUrl;
+        }
+        switch (action.type) {
+            case 'redirect':
+                console.log(`🍪 Funnel: Redirecting to ${targetUrl}`);
+                window.location.href = targetUrl;
+                break;
+            case 'replace':
+                console.log(`🍪 Funnel: Replacing current page with ${targetUrl}`);
+                window.location.replace(targetUrl);
+                break;
+            case 'push':
+                console.log(`🍪 Funnel: Pushing to history: ${targetUrl}`);
+                window.history.pushState({}, '', targetUrl);
+                // Trigger a popstate event to update React Router
+                window.dispatchEvent(new PopStateEvent('popstate'));
+                break;
+            case 'external':
+                console.log(`🍪 Funnel: Opening external URL: ${targetUrl}`);
+                window.open(targetUrl, '_blank');
+                break;
+            case 'none':
+                console.log(`🍪 Funnel: No navigation action required`);
+                break;
+            default:
+                console.warn(`🍪 Funnel: Unknown navigation action type: ${action.type}`);
+                break;
+        }
+    }, []);
+    /**
+     * Retry initialization after fixing errors
+     */
+    const retryInitialization = useCallback(async () => {
+        setInitializationAttempted(false);
+        setInitializationError(null);
+        await initializeSession();
+    }, [initializeSession]);
+    // Auto-initialize if requested and not already initialized (prevent infinite loops)
+    useEffect(() => {
+        if (options.autoInitialize &&
+            !isInitialized &&
+            !initializationAttempted &&
+            !initializationError &&
+            auth.session?.customerId &&
+            store?.id) {
+            console.log('🍪 Funnel: Auto-initializing session...');
+            initializeSession().catch(error => {
+                console.error('Auto-initialization failed - will not retry:', error);
+            });
+        }
+    }, [
+        options.autoInitialize,
+        isInitialized,
+        initializationAttempted,
+        initializationError,
+        auth.session?.customerId,
+        store?.id,
+        initializeSession
+    ]);
+    return {
+        next,
+        goToStep,
+        updateContext,
+        currentStep: {
+            id: currentStepId || 'unknown'
+        },
+        context,
+        isLoading,
+        isInitialized,
+        initializeSession,
+        endSession,
+        retryInitialization,
+        initializationError
+    };
+}
+/**
+ * Simplified funnel hook for basic step tracking
+ */
+export function useSimpleFunnel(funnelId, initialStepId) {
+    const funnel = useFunnel({
+        funnelId,
+        currentStepId: initialStepId,
+        autoInitialize: true
+    });
+    return {
+        currentStepId: funnel.currentStep.id,
+        next: funnel.next,
+        goToStep: funnel.goToStep,
+        isLoading: funnel.isLoading
+    };
+}

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

@@ -14,29 +14,48 @@ export interface UseISODataResult {
     getRegions: (countryCode: string) => ISORegion[];
     findRegion: (countryCode: string, regionCode: string) => ISORegion | null;
     mapGoogleToISO: (googleState: string, googleStateLong: string, countryCode: string) => ISORegion | null;
+    isLanguageLoaded: boolean;
+    registeredLanguages: SupportedLanguage[];
 }
 /**
- * React hook for accessing ISO3166 countries and regions data
+ * React hook for accessing ISO3166 countries and regions data with dynamic language loading
  * @param language - Language code (supports: en, ru, de, fr, es, zh, hi, pt, ja, ar, it, he)
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  * @param disputeSetting - Territorial dispute perspective (currently only UN is supported)
  * @returns Object with countries data and helper functions
  */
-export declare function useISOData(language?: SupportedLanguage, disputeSetting?: string): UseISODataResult;
+export declare function useISOData(language?: SupportedLanguage, autoImport?: boolean, disputeSetting?: string): UseISODataResult;
 /**
  * Get available languages for ISO data
  */
 export declare function getAvailableLanguages(): SupportedLanguage[];
+/**
+ * Hook to manually import and register a language
+ * @param language - Language code to import
+ * @returns Object with loading state and error handling
+ */
+export declare function useLanguageImport(language: SupportedLanguage): {
+    importLanguage: () => Promise<void>;
+    isLoading: boolean;
+    error: string | null;
+    isRegistered: boolean;
+};
 /**
  * Get list of countries as options for select components
+ * @param language - Language code (defaults to 'en')
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  */
-export declare function useCountryOptions(language?: SupportedLanguage): {
+export declare function useCountryOptions(language?: SupportedLanguage, autoImport?: boolean): {
     value: string;
     label: string;
 }[];
 /**
  * Get list of regions/states for a country as options for select components
+ * @param countryCode - ISO country code
+ * @param language - Language code (defaults to 'en')
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  */
-export declare function useRegionOptions(countryCode: string, language?: SupportedLanguage): {
+export declare function useRegionOptions(countryCode: string, language?: SupportedLanguage, autoImport?: boolean): {
     value: string;
     label: string;
 }[];

package/dist/react/hooks/useISOData.js

@@ -1,16 +1,32 @@
-import { useMemo } from 'react';
+import { useMemo, useEffect, useState, useCallback } from 'react';
 // Import the pre-built ISO data functions
-import { getCountries, getStatesForCountry } from '../../data/iso3166';
+import { getCountries, getStatesForCountry, importLanguage, isLanguageRegistered, getRegisteredLanguages } from '../../data/iso3166';
 /**
- * React hook for accessing ISO3166 countries and regions data
+ * React hook for accessing ISO3166 countries and regions data with dynamic language loading
  * @param language - Language code (supports: en, ru, de, fr, es, zh, hi, pt, ja, ar, it, he)
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  * @param disputeSetting - Territorial dispute perspective (currently only UN is supported)
  * @returns Object with countries data and helper functions
  */
-export function useISOData(language = 'en', disputeSetting = 'UN') {
+export function useISOData(language = 'en', autoImport = true, disputeSetting = 'UN') {
+    const [isLanguageLoaded, setIsLanguageLoaded] = useState(isLanguageRegistered(language));
+    const [registeredLanguages, setRegisteredLanguages] = useState(getRegisteredLanguages);
+    // Auto-import language if not registered and autoImport is true
+    useEffect(() => {
+        if (!isLanguageRegistered(language) && autoImport && language !== 'en') {
+            importLanguage(language)
+                .then(() => {
+                setIsLanguageLoaded(true);
+                setRegisteredLanguages(getRegisteredLanguages());
+            })
+                .catch((error) => {
+                console.error(`Failed to auto-import language ${language}:`, error);
+            });
+        }
+    }, [language, autoImport]);
     const data = useMemo(() => {
         try {
-            // Get countries from pre-built data with language support (now synchronous)
+            // Get countries from pre-built data with language support
             const countriesArray = getCountries(language);
             // Transform to our expected format (Record<string, ISOCountry>)
             const countries = {};
@@ -66,6 +82,8 @@ export function useISOData(language = 'en', disputeSetting = 'UN') {
                 getRegions,
                 findRegion,
                 mapGoogleToISO,
+                isLanguageLoaded,
+                registeredLanguages,
             };
         }
         catch (error) {
@@ -75,23 +93,58 @@ export function useISOData(language = 'en', disputeSetting = 'UN') {
                 getRegions: () => [],
                 findRegion: () => null,
                 mapGoogleToISO: () => null,
+                isLanguageLoaded,
+                registeredLanguages,
             };
         }
-    }, [language, disputeSetting]);
+    }, [language, disputeSetting, isLanguageLoaded, registeredLanguages]);
     return data;
 }
 /**
  * Get available languages for ISO data
  */
 export function getAvailableLanguages() {
-    // Return all statically imported languages for browser compatibility
+    // Return all available languages (not just registered ones)
     return ['en', 'ru', 'de', 'fr', 'es', 'zh', 'hi', 'pt', 'ja', 'ar', 'it', 'he'];
 }
+/**
+ * Hook to manually import and register a language
+ * @param language - Language code to import
+ * @returns Object with loading state and error handling
+ */
+export function useLanguageImport(language) {
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const importLanguageData = useCallback(async () => {
+        if (isLanguageRegistered(language)) {
+            return; // Already registered
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            await importLanguage(language);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : 'Failed to import language');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [language]);
+    return {
+        importLanguage: importLanguageData,
+        isLoading,
+        error,
+        isRegistered: isLanguageRegistered(language),
+    };
+}
 /**
  * Get list of countries as options for select components
+ * @param language - Language code (defaults to 'en')
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  */
-export function useCountryOptions(language = 'en') {
-    const { countries } = useISOData(language);
+export function useCountryOptions(language = 'en', autoImport = true) {
+    const { countries } = useISOData(language, autoImport);
     return useMemo(() => {
         return Object.entries(countries)
             .map(([code, country]) => ({
@@ -103,9 +156,12 @@ export function useCountryOptions(language = 'en') {
 }
 /**
  * Get list of regions/states for a country as options for select components
+ * @param countryCode - ISO country code
+ * @param language - Language code (defaults to 'en')
+ * @param autoImport - Whether to automatically import the language if not registered (default: true)
  */
-export function useRegionOptions(countryCode, language = 'en') {
-    const { getRegions } = useISOData(language);
+export function useRegionOptions(countryCode, language = 'en', autoImport = true) {
+    const { getRegions } = useISOData(language, autoImport);
     return useMemo(() => {
         if (!countryCode)
             return [];

package/dist/react/hooks/useLogin.js

@@ -1,7 +1,7 @@
 import { useCallback, useState } from 'react';
 import { useTagadaContext } from '../providers/TagadaProvider';
-import { setClientToken } from '../utils/tokenStorage';
 import { usePluginConfig } from './usePluginConfig';
+import { setClientToken } from '../utils/tokenStorage';
 export function useLogin() {
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);

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

@@ -2,8 +2,21 @@
  * Plugin Configuration Hook
  *
  * Professional SDK approach to access plugin configuration:
+ * - Raw Config: Direct configuration passed via TagadaProvider (highest priority)
  * - Store ID, Account ID, Base Path: from .local.json (dev) or headers (production)
  * - Deployment Config: from config/*.json (dev) or meta tags (production)
+ *
+ * Usage:
+ * 1. Raw config (recommended for programmatic usage):
+ *    <TagadaProvider rawPluginConfig={{ storeId: 'store_123', config: {...} }}>
+ *
+ * 2. File-based config (for development):
+ *    - .local.json for store/account info
+ *    - config/default.tgd.json for deployment config
+ *
+ * 3. Production config:
+ *    - Headers for store/account info
+ *    - Meta tags for deployment config
  */
 export interface PluginConfig<TConfig = Record<string, any>> {
     storeId?: string;
@@ -11,6 +24,12 @@ export interface PluginConfig<TConfig = Record<string, any>> {
     basePath?: string;
     config?: TConfig;
 }
+export interface RawPluginConfig<TConfig = Record<string, any>> {
+    storeId?: string;
+    accountId?: string;
+    basePath?: string;
+    config?: TConfig;
+}
 export interface LocalDevConfig {
     storeId: string;
     accountId: string;
@@ -18,9 +37,9 @@ export interface LocalDevConfig {
 }
 /**
  * Load plugin configuration (cached)
- * Tries local dev config first, then production config
+ * Tries raw config first, then local dev config, then production config
  */
-export declare const loadPluginConfig: (configVariant?: string) => Promise<PluginConfig>;
+export declare const loadPluginConfig: (configVariant?: string, rawConfig?: RawPluginConfig) => Promise<PluginConfig>;
 /**
  * Main hook for plugin configuration
  * Gets config from TagadaProvider context (no parameters needed)
@@ -42,7 +61,7 @@ export declare const useBasePath: () => {
 /**
  * Get cached config directly (for non-React usage)
  */
-export declare const getPluginConfig: (configVariant?: string) => Promise<PluginConfig>;
+export declare const getPluginConfig: (configVariant?: string, rawConfig?: RawPluginConfig) => Promise<PluginConfig>;
 /**
  * Clear the config cache (useful for testing)
  */
@@ -50,4 +69,4 @@ export declare const clearPluginConfigCache: () => void;
 /**
  * Development helper to log current configuration
  */
-export declare const debugPluginConfig: (configVariant?: string) => Promise<void>;
+export declare const debugPluginConfig: (configVariant?: string, rawConfig?: RawPluginConfig) => Promise<void>;