@easyflow/javascript-sdk 2.1.7

package/INTEGRATION-GUIDE.md

@@ -0,0 +1,521 @@
+# 🚀 Easyflow SDK - Guia de Integração Low-Code/No-Code
+
+Este guia mostra como integrar o Easyflow SDK em plataformas low-code/no-code de forma **NO BRAINER** - simples, segura e eficiente.
+
+## 🎯 **Plataformas Suportadas**
+
+- ✅ **[Lovable.dev](https://lovable.dev/)** - Desenvolvimento por chat com IA
+- ✅ **Bubble** - Plataforma de aplicações visuais
+- ✅ **Webflow** - Design e desenvolvimento web
+- ✅ **Zapier** - Automação de workflows
+- ✅ **Make.com** - Plataforma de integração
+- ✅ **Outras plataformas** que suportem JavaScript
+
+## 🚀 **Integração NO BRAINER**
+
+### **1. Inclusão do SDK**
+
+Adicione o SDK em qualquer plataforma com uma única linha:
+
+```html
+<!-- Cloudflare Pages (Recomendado) -->
+<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
+
+<!-- Ou via jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@latest/dist/easyflow-sdk.min.js"></script>
+```
+
+### **2. Inicialização Automática**
+
+O SDK se inicializa automaticamente e expõe todas as funcionalidades:
+
+```javascript
+// Todas as funcionalidades disponíveis automaticamente
+window.easyflowSDK = {
+    // Clientes
+    createCustomer: function (data) {
+        /* ... */
+    },
+    getCustomer: function (id) {
+        /* ... */
+    },
+    updateCustomer: function (id, data) {
+        /* ... */
+    },
+
+    // Pagamentos
+    placeOrder: function (offerId, data) {
+        /* ... */
+    },
+    charge: function (data) {
+        /* ... */
+    },
+    encrypt: function (data) {
+        /* ... */
+    },
+
+    // Cartões de crédito
+    addCreditCard: function (customerId, token) {
+        /* ... */
+    },
+    getCreditCard: function (customerId, cardId) {
+        /* ... */
+    },
+    removeCreditCard: function (customerId, cardId) {
+        /* ... */
+    },
+
+    // Validação
+    validate: {
+        /* ... */
+    },
+
+    // Sanitização
+    sanitize: {
+        /* ... */
+    },
+}
+```
+
+## 🎨 **Integração por Plataforma**
+
+### **Lovable.dev**
+
+#### **1. Incluir o SDK**
+
+No seu projeto Lovable, adicione o script:
+
+```html
+<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
+```
+
+#### **2. Usar nas Ações**
+
+```javascript
+// Criar cliente
+const customerResult = await easyflowSDK.createCustomer({
+    name: 'João Silva',
+    email: 'joao@exemplo.com',
+    document: {
+        type: 'CPF',
+        number: '12345678909',
+    },
+})
+
+if (customerResult.success) {
+    // Cliente criado com sucesso
+    const customerId = customerResult.data.id
+
+    // Processar pagamento
+    const paymentResult = await easyflowSDK.placeOrder('offer-123', {
+        buyer: customerResult.data,
+        payments: [
+            {
+                method: 'credit-card',
+                creditCard: {
+                    number: '4111111111111111',
+                    holderName: 'João Silva',
+                    month: '12',
+                    year: '2025',
+                    cvv: '123',
+                },
+            },
+        ],
+    })
+}
+```
+
+#### **3. Configurar Callbacks**
+
+```javascript
+// Callbacks para eventos
+easyflowSDK.on('customerCreated', function (customer) {
+    console.log('Cliente criado:', customer)
+    // Atualizar UI do Lovable
+})
+
+easyflowSDK.on('paymentProcessed', function (result) {
+    console.log('Pagamento processado:', result)
+    // Redirecionar ou atualizar status
+})
+```
+
+### **Bubble**
+
+#### **1. Incluir o SDK**
+
+No Bubble, adicione o script no HTML personalizado:
+
+```html
+<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
+```
+
+#### **2. JavaScript Personalizado**
+
+```javascript
+// Configurar callbacks para eventos do Bubble
+easyflowSDK.on('customerCreated', function (customer) {
+    // Atualizar campo no Bubble
+    bubble_fn_updateCustomer(customer)
+})
+
+easyflowSDK.on('paymentProcessed', function (result) {
+    // Atualizar status do pagamento
+    bubble_fn_updatePaymentStatus(result)
+})
+
+// Função para criar cliente no Bubble
+async function bubbleCreateCustomer(customerData) {
+    const result = await easyflowSDK.createCustomer(customerData)
+    return result
+}
+```
+
+#### **3. Usar nas Ações do Bubble**
+
+```javascript
+// No Bubble, chame a função personalizada
+const customerData = {
+    name: CurrentCell's Customer's Name,
+    email: CurrentCell's Customer's Email,
+    document: {
+        type: 'CPF',
+        number: CurrentCell's Customer's CPF
+    }
+};
+
+const result = await bubbleCreateCustomer(customerData);
+```
+
+### **Webflow**
+
+#### **1. Incluir o SDK**
+
+No Webflow, adicione o script no HTML personalizado:
+
+```html
+<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
+```
+
+#### **2. JavaScript Personalizado**
+
+```javascript
+// Configurar formulário de checkout
+document
+    .getElementById('checkout-form')
+    .addEventListener('submit', async function (e) {
+        e.preventDefault()
+
+        const formData = new FormData(this)
+        const customerData = {
+            name: formData.get('name'),
+            email: formData.get('email'),
+            document: {
+                type: 'CPF',
+                number: formData.get('cpf'),
+            },
+        }
+
+        // Validar dados
+        if (easyflowSDK.validate.customer(customerData)) {
+            const result = await easyflowSDK.createCustomer(customerData)
+            if (result.success) {
+                // Redirecionar para pagamento
+                window.location.href = '/checkout?customer=' + result.data.id
+            }
+        }
+    })
+```
+
+### **Zapier**
+
+#### **1. Endpoint Webhook**
+
+Crie um endpoint para receber webhooks do Zapier:
+
+```javascript
+// Endpoint para Zapier webhook
+app.post('/zapier/easyflow', async (req, res) => {
+    try {
+        const { action, data } = req.body
+
+        switch (action) {
+            case 'createCustomer':
+                const customerResult = await easyflowSDK.createCustomer(data)
+                res.json(customerResult)
+                break
+
+            case 'processPayment':
+                const paymentResult = await easyflowSDK.charge(data)
+                res.json(paymentResult)
+                break
+
+            default:
+                res.status(400).json({ error: 'Ação não suportada' })
+        }
+    } catch (error) {
+        res.status(500).json({ error: error.message })
+    }
+})
+```
+
+#### **2. Configurar no Zapier**
+
+1. **Trigger**: Escolha o evento que dispara a ação
+2. **Action**: Configure o webhook para o endpoint
+3. **Data Mapping**: Mapeie os campos necessários
+
+## 🛡️ **Segurança e Validação**
+
+### **Validação Automática**
+
+```javascript
+// Validar dados antes de enviar
+const emailValid = easyflowSDK.validate.email('joao@exemplo.com')
+const cpfValid = easyflowSDK.validate.cpf('12345678909')
+
+if (emailValid && cpfValid) {
+    // Dados válidos, prosseguir
+    const result = await easyflowSDK.createCustomer(customerData)
+} else {
+    // Mostrar erro na UI
+    showError('Dados inválidos')
+}
+```
+
+### **Sanitização Automática**
+
+```javascript
+// Sanitizar dados de entrada
+const sanitizedData = easyflowSDK.sanitize.customer(customerData)
+const result = await easyflowSDK.createCustomer(sanitizedData)
+```
+
+## 📱 **Exemplos de Uso Comum**
+
+### **Formulário de Cadastro**
+
+```javascript
+// Formulário de cadastro de cliente
+async function handleCustomerRegistration(formData) {
+    try {
+        // Validar dados
+        const customerData = {
+            name: formData.get('name'),
+            email: formData.get('email'),
+            document: {
+                type: 'CPF',
+                number: formData.get('cpf'),
+            },
+            phone: {
+                areaCode: '+55',
+                ddd: formData.get('ddd'),
+                number: formData.get('phone'),
+                isMobile: true,
+            },
+        }
+
+        // Validar antes de enviar
+        if (!easyflowSDK.validate.customer(customerData)) {
+            throw new Error('Dados inválidos')
+        }
+
+        // Criar cliente
+        const result = await easyflowSDK.createCustomer(customerData)
+
+        if (result.success) {
+            // Sucesso - redirecionar para checkout
+            window.location.href = `/checkout?customer=${result.data.id}`
+        } else {
+            // Erro
+            showError(result.error.message)
+        }
+    } catch (error) {
+        showError('Erro ao criar cliente: ' + error.message)
+    }
+}
+```
+
+### **Processamento de Pagamento**
+
+```javascript
+// Processar pagamento
+async function processPayment(offerId, customerId, paymentData) {
+    try {
+        // Obter dados do cliente
+        const customerResult = await easyflowSDK.getCustomer(customerId)
+
+        if (!customerResult.success) {
+            throw new Error('Cliente não encontrado')
+        }
+
+        // Criar pedido
+        const orderResult = await easyflowSDK.placeOrder(offerId, {
+            buyer: customerResult.data,
+            payments: [paymentData],
+        })
+
+        if (orderResult.success) {
+            // Pagamento processado com sucesso
+            showSuccess('Pagamento processado com sucesso!')
+
+            // Redirecionar para página de sucesso
+            window.location.href = `/success?order=${orderResult.data.id}`
+        } else {
+            throw new Error(orderResult.error.message)
+        }
+    } catch (error) {
+        showError('Erro ao processar pagamento: ' + error.message)
+    }
+}
+```
+
+## 🔧 **Configuração Avançada**
+
+### **Configurar Callbacks**
+
+```javascript
+// Configurar callbacks para eventos
+easyflowSDK.on('customerCreated', function (customer) {
+    console.log('🎉 Cliente criado:', customer)
+    // Atualizar UI
+})
+
+easyflowSDK.on('paymentProcessed', function (result) {
+    console.log('💳 Pagamento processado:', result)
+    // Atualizar status
+})
+
+easyflowSDK.on('error', function (error) {
+    console.error('❌ Erro:', error)
+    // Mostrar erro na UI
+})
+```
+
+### **Configurações Personalizadas**
+
+```javascript
+// Configurar opções personalizadas
+easyflowSDK.configure({
+    enableDebug: true,
+    globalScope: 'window',
+})
+
+// Verificar status
+const status = easyflowSDK.getStatus()
+console.log('Status:', status)
+```
+
+## 📊 **Monitoramento e Debug**
+
+### **Habilitar Debug**
+
+```javascript
+// Habilitar logs de debug
+easyflowSDK.configure({ enableDebug: true })
+
+// Ver logs no console
+// ✅ Easyflow SDK Integration Wrapper inicializado com sucesso
+// 🌐 Easyflow SDK exposto globalmente como "easyflowSDK"
+```
+
+### **Verificar Status**
+
+```javascript
+// Verificar status do SDK
+const status = easyflowSDK.getStatus()
+console.log('Status:', {
+    initialized: status.initialized,
+    businessId: status.businessId,
+    sdkVersion: status.sdkVersion,
+    wrapperVersion: status.wrapperVersion,
+})
+```
+
+## 🚨 **Tratamento de Erros**
+
+### **Estrutura de Resposta**
+
+```javascript
+// Todas as chamadas retornam a mesma estrutura
+const result = await easyflowSDK.createCustomer(customerData)
+
+if (result.success) {
+    // Sucesso
+    console.log('Dados:', result.data)
+} else {
+    // Erro
+    console.error('Erro:', result.error)
+    console.error('Código:', result.error.code)
+    console.error('Tipo:', result.error.type)
+}
+```
+
+### **Tratamento de Erros Comum**
+
+```javascript
+// Tratar erros específicos
+try {
+    const result = await easyflowSDK.createCustomer(customerData)
+
+    if (!result.success) {
+        switch (result.error.code) {
+            case 'VALIDATION_ERROR':
+                showError('Dados inválidos: ' + result.error.message)
+                break
+            case 'NETWORK_ERROR':
+                showError('Erro de conexão. Tente novamente.')
+                break
+            default:
+                showError('Erro inesperado: ' + result.error.message)
+        }
+    }
+} catch (error) {
+    showError('Erro ao processar: ' + error.message)
+}
+```
+
+## 📚 **Recursos Adicionais**
+
+### **Validação de Dados**
+
+- ✅ **Email**: Validação de formato e segurança
+- ✅ **CPF**: Algoritmo oficial brasileiro
+- ✅ **CNPJ**: Validação empresarial
+- ✅ **Telefone**: Formato brasileiro com DDD
+- ✅ **Endereço**: Validação completa de endereços
+
+### **Sanitização de Dados**
+
+- ✅ **Input**: Remoção de caracteres perigosos
+- ✅ **Headers**: Filtragem de headers maliciosos
+- ✅ **Objetos**: Sanitização recursiva de dados
+
+### **Segurança Integrada**
+
+- ✅ **SRI**: Subresource Integrity para CDNs
+- ✅ **HTTPS**: Forçamento de conexões seguras
+- ✅ **Rate Limiting**: Proteção contra abuso
+- ✅ **Validação**: Verificação de todos os inputs
+
+## 🎯 **Próximos Passos**
+
+1. **Escolha sua plataforma** (Lovable, Bubble, Webflow, etc.)
+2. **Inclua o SDK** com uma linha de código
+3. **Configure callbacks** para eventos importantes
+4. **Implemente validação** antes de enviar dados
+5. **Teste a integração** com dados de exemplo
+6. **Deploy em produção** com confiança
+
+## 📞 **Suporte**
+
+- **Documentação**: [docs.easyflow.digital](https://docs.easyflow.digital)
+- **GitHub**: [Issues](https://github.com/easyflow-cash/easyflow-javascript-sdk/issues)
+- **Email**: [diego@easyflow.digital](mailto:diego@easyflow.digital)
+- **Website**: [easyflow.digital](https://easyflow.digital)
+
+---
+
+**Easyflow SDK** - Transformando integrações de pagamento em experiências **NO BRAINER** 🚀
+
+**Mantenedor**: [Diego Moura](https://github.com/dmourainatel) - Co-Founder/CTO