@easyflow/javascript-sdk 2.1.24 → 2.1.26

package/PLATFORM-INTEGRATION.md

@@ -0,0 +1,235 @@
+# 🚀 Easyflow SDK - Platform Integration Guide
+
+## 📋 Overview
+
+The Easyflow SDK provides a **dual initialization approach** to serve both traditional developers and low-code/no-code platforms. This guide explains the `initializeForPlatform` mechanism and how to use it effectively.
+
+## 🔧 Two Ways to Initialize
+
+### 1. **Traditional Initialization** (For Developers)
+
+```javascript
+// Direct SDK instance - Full control
+const sdk = new EasyflowSDK('your-business-id')
+
+// Use all SDK methods directly
+await sdk.createCustomer(customerData)
+await sdk.placeOrder(offerId, orderData)
+await sdk.charge(paymentData)
+```
+
+### 2. **Platform Integration** (For Low-Code/No-Code)
+
+```javascript
+// Platform wrapper - Simplified API
+const wrapper = EasyflowSDK.initializeForPlatform({
+    businessId: 'your-business-id',
+    enableDebug: true,
+})
+
+// Use simplified methods
+await wrapper.createCustomer(customerData)
+await wrapper.placeOrder(offerId, orderData)
+await wrapper.charge(paymentData)
+```
+
+## 🎯 When to Use Each Approach
+
+| **Use Case**             | **Method**                | **Benefits**                                    |
+| ------------------------ | ------------------------- | ----------------------------------------------- |
+| **Full Control**         | `new EasyflowSDK()`       | Complete API access, custom error handling      |
+| **Platform Integration** | `initializeForPlatform()` | Simplified API, automatic callbacks, validation |
+| **Quick Prototyping**    | `initializeForPlatform()` | Faster setup, less configuration                |
+| **Production Apps**      | `new EasyflowSDK()`       | Better performance, more control                |
+
+## ⚙️ Platform Integration Features
+
+### **Automatic Callbacks**
+
+```javascript
+const wrapper = EasyflowSDK.initializeForPlatform({
+    businessId: 'your-business-id',
+    enableDebug: true,
+})
+
+// Set up event handlers
+wrapper.on('customerCreated', (customer) => {
+    console.log('Customer created:', customer)
+})
+
+wrapper.on('paymentProcessed', (result, method) => {
+    console.log('Payment processed:', result, method)
+})
+
+wrapper.on('error', (error) => {
+    console.error('Error occurred:', error)
+})
+```
+
+### **Simplified Validation**
+
+```javascript
+// Automatic validation with friendly error messages
+const validation = wrapper.validate('email', 'user@example.com')
+if (!validation.valid) {
+    console.error('Validation failed:', validation.error)
+}
+```
+
+### **Configuration Management**
+
+```javascript
+// Update configuration on the fly
+wrapper.configure({
+    enableDebug: false,
+    timeout: 30000,
+})
+
+// Get current status
+const status = wrapper.getStatus()
+console.log('Wrapper status:', status)
+```
+
+## 🔄 How It Works
+
+### **1. Method Call**
+
+```javascript
+static initializeForPlatform(config) {
+    return initializeEasyflow(config)
+}
+```
+
+### **2. Wrapper Creation**
+
+```javascript
+function initializeEasyflow(config) {
+    return new EasyflowIntegrationWrapper(config)
+}
+```
+
+### **3. Simplified Interface**
+
+The wrapper provides:
+
+- ✅ **Simplified method names**
+- ✅ **Automatic error handling**
+- ✅ **Built-in validation**
+- ✅ **Event management**
+- ✅ **Configuration persistence**
+
+## 📱 Platform Examples
+
+### **Bubble Integration**
+
+```javascript
+// In Bubble's JavaScript actions
+const easyflow = EasyflowSDK.initializeForPlatform({
+    businessId: bubble.get('business_id'),
+    enableDebug: true,
+})
+
+// Use in workflows
+const customer = await easyflow.createCustomer({
+    name: bubble.get('customer_name'),
+    email: bubble.get('customer_email'),
+})
+```
+
+### **Webflow Integration**
+
+```javascript
+// In Webflow's custom code
+const easyflow = EasyflowSDK.initializeForPlatform({
+    businessId: 'your-business-id',
+})
+
+// Handle form submissions
+document
+    .getElementById('payment-form')
+    .addEventListener('submit', async (e) => {
+        e.preventDefault()
+        const result = await easyflow.charge(paymentData)
+    })
+```
+
+### **Custom Platform**
+
+```javascript
+// For your own platform
+class MyPlatform {
+    constructor() {
+        this.easyflow = EasyflowSDK.initializeForPlatform({
+            businessId: this.config.businessId,
+            enableDebug: this.config.debug,
+        })
+    }
+
+    async processPayment(data) {
+        return await this.easyflow.charge(data)
+    }
+}
+```
+
+## 🛡️ Security & Validation
+
+### **Automatic Sanitization**
+
+- All input data is automatically sanitized
+- Dangerous characters and protocols are removed
+- Sensitive information is handled securely
+
+### **Built-in Validation**
+
+```javascript
+// Automatic validation for common data types
+wrapper.validate('email', email) // Email format
+wrapper.validate('cpf', cpf) // CPF validation
+wrapper.validate('cnpj', cnpj) // CNPJ validation
+wrapper.validate('phone', phone) // Phone format
+wrapper.validate('address', address) // Address structure
+wrapper.validate('customer', customer) // Customer data
+```
+
+## 📊 Performance Considerations
+
+### **Memory Usage**
+
+- **Traditional SDK**: Lower memory footprint, direct access
+- **Platform Wrapper**: Slightly higher memory due to additional features
+
+### **Execution Speed**
+
+- **Traditional SDK**: Faster execution, no wrapper overhead
+- **Platform Wrapper**: Minimal overhead, optimized for ease of use
+
+## 🔧 Configuration Options
+
+```javascript
+const wrapper = EasyflowSDK.initializeForPlatform({
+    businessId: 'your-business-id', // Required
+    enableDebug: true, // Optional: Enable debug logs
+    timeout: 30000, // Optional: Request timeout (ms)
+    retryAttempts: 3, // Optional: Retry attempts
+    enableValidation: true, // Optional: Enable validation
+    enableCallbacks: true, // Optional: Enable callbacks
+})
+```
+
+## 📚 Related Documentation
+
+- **[README.md](README.md)** - Main SDK documentation
+- **[INDEX.md](INDEX.md)** - Documentation hub
+- **[DATA-STRUCTURES.md](DATA-STRUCTURES.md)** - Data structure reference
+- **[API Reference](docs/index.html)** - Complete API documentation
+
+## 🚀 Getting Started
+
+1. **Choose your approach** based on your needs
+2. **Initialize the SDK** using the appropriate method
+3. **Configure callbacks** if using platform integration
+4. **Start building** your payment solution
+
+---
+
+**Need help?** Check the main [README.md](README.md) or create an issue on GitHub.