@easyflow/javascript-sdk 2.1.8 → 2.1.10

package/INTEGRATION-GUIDE.md

@@ -1,521 +0,0 @@
-# 🚀 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