@tagadapay/plugin-sdk 2.3.0 → 2.3.3

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/package.json

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