@tagadapay/plugin-sdk 2.2.9 → 2.3.2

package/README.md

@@ -15,6 +15,7 @@ A comprehensive React SDK for building plugins on the TagadaPay platform. Create
 ### Plugin Development
 
 - **[Plugin Configuration](./docs/PLUGIN_CONFIG.md)** - How to access store context, config, and branding
+- **[Initialization Modes](#-initialization-modes)** - Choose between blocking and non-blocking initialization
 - **[Google Autocomplete](./docs/README-google-autocomplete.md)** - Address autocomplete with Google Places API
 - **[ISO Data](./docs/README-iso-data.md)** - Country and region data with Google integration
 
@@ -164,6 +165,95 @@ function App() {
 export default App;
 ```
 
+## 🚀 Initialization Modes
+
+The TagadaProvider supports two initialization modes to give you control over when your components render:
+
+### Non-Blocking Mode (Default - Recommended)
+
+```tsx
+<TagadaProvider>
+  {/* Children render immediately after config loads */}
+  <YourApp />
+</TagadaProvider>
+
+// OR explicitly
+<TagadaProvider blockUntilSessionReady={false}>
+  <YourApp />
+</TagadaProvider>
+```
+
+**Flow:**
+1. **Phase 1 & 2** ✅ Plugin config loads → Children render immediately
+2. **Phase 3** 🔄 Session initialization runs in background  
+3. **API calls** 🔄 Hooks automatically wait for session to be ready
+
+**Benefits:**
+- ⚡ **Faster rendering** - UI appears immediately
+- 🎯 **Better UX** - Show loading states while session initializes
+- 🔄 **Automatic waiting** - Hooks handle session timing for you
+
+### Blocking Mode (Legacy Behavior)
+
+```tsx
+<TagadaProvider blockUntilSessionReady={true}>
+  {/* Children render only after ALL initialization completes */}
+  <YourApp />
+</TagadaProvider>
+```
+
+**Flow:**
+1. **All Phases** ⏳ Config + Session must complete before children render
+2. **API calls** ✅ Work immediately (no waiting needed)
+
+**Use when:**
+- 🔄 **Migrating** from older SDK versions
+- 🎯 **Simple apps** that don't need progressive loading
+
+### Console Logs
+
+The SDK logs help you understand which mode you're using:
+
+**Non-blocking mode:**
+```
+✅ Phase 1 & 2 Complete - Plugin config loaded
+🚀 Non-blocking mode: Children can now render - Phase 3 will continue in background
+🔄 [useCheckout] Waiting for session initialization to complete...
+✅ Phase 3 Complete - Session initialization completed successfully  
+✅ [useCheckout] Session initialized, proceeding with checkout init
+```
+
+**Blocking mode:**
+```
+✅ Phase 1 & 2 Complete - Plugin config loaded
+⏳ Blocking mode: Children will render after Phase 3 completes
+✅ Phase 3 Complete - Session initialization completed successfully
+```
+
+### TagadaProvider API
+
+```tsx
+interface TagadaProviderProps {
+  children: ReactNode;
+  environment?: 'local' | 'development' | 'staging' | 'production';
+  customApiConfig?: Partial<EnvironmentConfig>;
+  debugMode?: boolean;
+  localConfig?: string; // LOCAL DEV ONLY: Override config variant
+  blockUntilSessionReady?: boolean; // Default: false
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Your plugin components |
+| `environment` | `string` | auto-detect | Override environment detection |
+| `customApiConfig` | `object` | - | Custom API configuration |
+| `debugMode` | `boolean` | auto (false in prod) | Enable debug features |
+| `localConfig` | `string` | `'default'` | Config variant for local dev |
+| `blockUntilSessionReady` | `boolean` | `false` | Use legacy blocking behavior |
+
+> **Version Compatibility:** The `blockUntilSessionReady` option was added in v2.3.0. For older versions, the blocking behavior was the default and only option.
+
 ### Development vs Production
 
 | Environment    | Store/Account ID | Deployment Config | How it Works       |

package/dist/react/hooks/useCheckout.js

@@ -1,7 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useCurrency } from '../hooks/useCurrency';
 import { useTagadaContext } from '../providers/TagadaProvider';
-import { collectTrackingData } from '../utils/trackingUtils';
 import { usePluginConfig } from './usePluginConfig';
 export function useCheckout(options = {}) {
     const { apiService, updateCheckoutDebugData, refreshCoordinator, currency, isSessionInitialized } = useTagadaContext();
@@ -58,6 +57,8 @@ export function useCheckout(options = {}) {
             throw new Error('Cannot initialize new checkout when checkoutToken is already provided. The existing checkout will be auto-loaded.');
         }
         // Wait for CMS session to initialize before making API calls
+        // Note: If TagadaProvider has blockUntilSessionReady=true, this component won't render
+        // until session is ready, so this wait is mainly for the new non-blocking mode
         if (!isSessionInitialized) {
             console.log('🔄 [useCheckout] Waiting for session initialization to complete...');
             await new Promise((resolve) => {
@@ -76,13 +77,9 @@ export function useCheckout(options = {}) {
         setIsLoading(true);
         setError(null);
         try {
-            // Collect tracking data
-            const trackingData = await collectTrackingData();
-            // Enhanced customerMetadata with tracking data
+            // Enhanced customerMetadata without tracking data
             const enhancedCustomerMetadata = {
                 ...params.customerMetadata,
-                localStorage: trackingData.localStorageData,
-                cookies: trackingData.trackingCookiesData,
             };
             const requestBody = {
                 ...params,

package/dist/react/providers/TagadaProvider.d.ts

@@ -53,8 +53,9 @@ interface TagadaProviderProps {
     customApiConfig?: Partial<EnvironmentConfig>;
     debugMode?: boolean;
     localConfig?: string;
+    blockUntilSessionReady?: boolean;
 }
 export declare function TagadaProvider({ children, environment, customApiConfig, debugMode, // Remove default, will be set based on environment
-localConfig, }: TagadaProviderProps): import("react/jsx-runtime").JSX.Element;
+localConfig, blockUntilSessionReady, }: TagadaProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useTagadaContext(): TagadaContextValue;
 export {};

package/dist/react/providers/TagadaProvider.js

@@ -46,7 +46,8 @@ const InitializationLoader = () => (_jsxs("div", { style: {
       ` })] }));
 const TagadaContext = createContext(null);
 export function TagadaProvider({ children, environment, customApiConfig, debugMode, // Remove default, will be set based on environment
-localConfig, }) {
+localConfig, blockUntilSessionReady = false, // Default to new non-blocking behavior
+ }) {
     // LOCAL DEV ONLY: Use localConfig override if in local development, otherwise use default
     const isLocalDev = typeof window !== 'undefined' &&
         (window.location.hostname === 'localhost' ||
@@ -83,7 +84,12 @@ localConfig, }) {
                     basePath: config.basePath,
                     hasConfig: !!config.config,
                 });
-                console.log('🚀 Children can now render - Phase 3 (session init) will continue in background');
+                if (blockUntilSessionReady) {
+                    console.log('⏳ Blocking mode: Children will render after Phase 3 (session init) completes');
+                }
+                else {
+                    console.log('🚀 Non-blocking mode: Children can now render - Phase 3 (session init) will continue in background');
+                }
             }
             catch (error) {
                 console.error('❌ Failed to load plugin config in TagadaProvider:', error);
@@ -517,9 +523,11 @@ localConfig, }) {
     ]);
     // Determine if we should show loading
     // Phase 1 & 2 are mandatory: config loading and storeId availability
-    // Phase 3 (session initialization) is now optional/non-blocking
+    // Phase 3 (session initialization) is optional/non-blocking by default
     const shouldShowLoading = configLoading || (!storeId && configLoading);
-    const canRenderChildren = !configLoading && storeId; // Remove isInitialized requirement
+    const canRenderChildren = blockUntilSessionReady
+        ? (!configLoading && storeId && isInitialized) // Old behavior: wait for all phases
+        : (!configLoading && storeId); // New behavior: render after phases 1 & 2
     return (_jsxs(TagadaContext.Provider, { value: contextValue, children: [shouldShowLoading && _jsx(InitializationLoader, {}), finalDebugMode && canRenderChildren && (_jsxs(_Fragment, { children: [_jsx("button", { onClick: () => setIsDebugDrawerOpen(true), style: {
                             position: 'fixed',
                             bottom: '16px',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/plugin-sdk",
-  "version": "2.2.9",
+  "version": "2.3.2",
   "description": "Modern React SDK for building Tagada Pay plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/react/utils/trackingUtils.d.ts

@@ -1,24 +0,0 @@
-export interface TrackingData {
-    trackingCookiesData: Record<string, string>;
-    localStorageData: Record<string, string>;
-}
-/**
- * Define pixel tracking cookie patterns for various platforms
- */
-export declare const trackingCookiePatterns: RegExp[];
-/**
- * Function to get cookies with retry logic
- */
-export declare const getCookiesWithRetry: (maxRetries?: number, delay?: number) => Promise<string[]>;
-/**
- * Collect localStorage data as dictionary
- */
-export declare const getLocalStorageData: () => Record<string, string>;
-/**
- * Collect tracking cookies data based on defined patterns
- */
-export declare const getTrackingCookiesData: () => Promise<Record<string, string>>;
-/**
- * Collect all tracking data (localStorage and cookies)
- */
-export declare const collectTrackingData: () => Promise<TrackingData>;

package/dist/react/utils/trackingUtils.js

@@ -1,172 +0,0 @@
-/**
- * Define pixel tracking cookie patterns for various platforms
- */
-export const trackingCookiePatterns = [
-    // Meta/Facebook pixels
-    /^_fbp/,
-    /^_fbc/,
-    /^fr$/,
-    /^_fbq/,
-    /^fbq/,
-    /^sb$/,
-    // Google Analytics & Ads
-    /^_ga/,
-    /^_gid/,
-    /^_gcl_au/,
-    /^_gac_/,
-    /^_gtag/,
-    /^_gat/,
-    /^_dc_gtm_/,
-    /^_gtm/,
-    // Google Ads
-    /^_gcl_/,
-    /^_gclid/,
-    /^_gclsrc/,
-    // Snapchat
-    /^_scid/,
-    /^_sctr/,
-    /^_schn/,
-    /^_scpx/,
-    // TikTok
-    /^_ttp/,
-    /^_tt_enable_cookie/,
-    /^_ttclid/,
-    /^_tta/,
-    // Pinterest
-    /^_pin/,
-    /^_pinterest_/,
-    /^_pinid/,
-    // Twitter/X
-    /^_twitter/,
-    /^_twid/,
-    /^muc_ads/,
-    // LinkedIn
-    /^_li/,
-    /^AnalyticsSyncHistory/,
-    /^bcookie/,
-    /^bscookie/,
-    // Microsoft/Bing
-    /^_uetsid/,
-    /^_uetvid/,
-    /^MUID/,
-    /^_msdcs/,
-    // Amazon
-    /^ad-id/,
-    /^ad-privacy/,
-    // CVG tracking
-    /^__cvg_uid/,
-    /^__cvg_sid/,
-    /^__cvg_session/,
-    // Shopify tracking
-    /^_shopify_y/,
-    /^_shopify_s/,
-    /^_shopify_ga/,
-    /^_shopify_ga_/,
-    /^_shopify_sa_p/,
-    /^_shopify_sa_t/,
-    // General tracking
-    /^_awc/,
-    /^_aw_/,
-    /^utm_/,
-    /^_clck/,
-    /^_clsk/,
-];
-/**
- * Function to get cookies with retry logic
- */
-export const getCookiesWithRetry = async (maxRetries = 3, delay = 100) => {
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            const cookies = document.cookie.split('; ');
-            if (cookies.length > 0 && cookies[0] !== '') {
-                return cookies;
-            }
-            // If no cookies found, wait and retry
-            if (attempt < maxRetries) {
-                console.log(`Cookie collection attempt ${attempt} failed, retrying in ${delay}ms...`);
-                await new Promise((resolve) => setTimeout(resolve, delay));
-            }
-        }
-        catch (error) {
-            console.warn(`Cookie collection attempt ${attempt} failed:`, error);
-            if (attempt < maxRetries) {
-                await new Promise((resolve) => setTimeout(resolve, delay));
-            }
-        }
-    }
-    return [];
-};
-/**
- * Collect localStorage data as dictionary
- */
-export const getLocalStorageData = () => {
-    const localStorageData = {};
-    try {
-        for (let i = 0; i < localStorage.length; i++) {
-            const key = localStorage.key(i);
-            if (key) {
-                localStorageData[key] = localStorage.getItem(key) || '';
-            }
-        }
-    }
-    catch (error) {
-        console.warn('Failed to read localStorage:', error);
-    }
-    return localStorageData;
-};
-/**
- * Collect tracking cookies data based on defined patterns
- */
-export const getTrackingCookiesData = async () => {
-    const trackingCookiesData = {};
-    try {
-        // Get cookies with retry logic
-        const cookies = await getCookiesWithRetry();
-        if (cookies.length === 0) {
-            console.warn('No cookies found after retry attempts');
-        }
-        else {
-            console.log(`Successfully collected ${cookies.length} cookies`);
-        }
-        cookies.forEach((cookie) => {
-            const [key, ...valueParts] = cookie.split('=');
-            const value = valueParts.join('='); // Handle values that might contain =
-            if (key && trackingCookiePatterns.some((pattern) => pattern.test(key))) {
-                try {
-                    trackingCookiesData[key] = decodeURIComponent(value || '');
-                }
-                catch (error) {
-                    // If decoding fails, use raw value
-                    trackingCookiesData[key] = value || '';
-                }
-            }
-        });
-        // Log specific cookies we're looking for
-        const importantCookies = ['_shopify_y', '__cvg_uid', '_fbp', '_ga'];
-        importantCookies.forEach((cookieName) => {
-            if (trackingCookiesData[cookieName]) {
-                console.log(`Found ${cookieName}:`, trackingCookiesData[cookieName]);
-            }
-            else {
-                console.log(`Missing ${cookieName} cookie`);
-            }
-        });
-    }
-    catch (error) {
-        console.warn('Failed to read tracking cookies:', error);
-    }
-    return trackingCookiesData;
-};
-/**
- * Collect all tracking data (localStorage and cookies)
- */
-export const collectTrackingData = async () => {
-    const [localStorageData, trackingCookiesData] = await Promise.all([
-        Promise.resolve(getLocalStorageData()),
-        getTrackingCookiesData(),
-    ]);
-    return {
-        localStorageData,
-        trackingCookiesData,
-    };
-};