Package Exports

@easyflow/javascript-sdk
@easyflow/javascript-sdk/package.json

Readme

Easyflow JavaScript SDK

Freedom to sell more, better and longer

Enterprise-grade JavaScript SDK for integration with the Easyflow payment processing platform with robust validation, comprehensive security and Brazilian compliance

About Easyflow

Easyflow is a payment platform that facilitates the sales process of digital products and services in a simple and intuitive way. Our mission is to transform Digital Commerce by offering a complete sales structure to maximize your LTV.

Why Choose Easyflow?

Outstanding approval rate: 95% to 98% credit card approval rate
High conversion checkout: Fastest loading in the market
Simplified recurrence: Recurring payments with your own rules
Bank-level security: PCI Compliance and advanced encryption
Same-day withdrawal: Same day, no bureaucracy
Simple integrations: Webhooks and API with few clicks

Payment Methods

Credit Card: Highest approval rate in the market
PIX: Instant Brazilian payment
Bank Billet: For those who prefer to pay via bank

Main Features

Optimized checkout for maximum conversion
AI-powered sales recovery (up to 40% increase)
Upsell, downsell and cross-sell to increase average ticket
Automated payment splitting for co-producers
Smart metrics and insights in real time
Integration with CRM, ERPs and third-party platforms

Plans and Fees

Clear and fair rate: 6.99% + R$2.50

Revenue +100k per month? Click here for special conditions
You only pay when you generate results
No hidden fees or surprises

Try It Now

Experience the Easyflow SDK in action with our interactive demo

What is the Easyflow JavaScript SDK?

The Easyflow JavaScript SDK is the official tool for developers to integrate their applications with the Easyflow platform. With this SDK, you can:

Process payments securely and reliably
Manage customers with complete Brazilian data validation
Create offers and process orders automatically
Implement recurrence with custom rules
Integrate with any system via REST API

SDK Advantages

100% Plug & Play: Works with any type of business
Brazilian Compliance: CPF/CNPJ, phone, address validation
Enterprise Security: Multiple layers of protection
High Performance: Optimized for production
Complete Documentation: Practical examples for all use cases

What's New in v2.1.19

Complete Implementation Examples

Full Data Models: Comprehensive examples for placeOrder, charge, createCustomer, and addCreditCard
Real-World Scenarios: Complete workflows with all available data fields
Brazilian Data: Realistic Brazilian addresses, phone numbers, and document formats
End-to-End Workflows: Complete customer → credit card → order examples
Code Quality: Improved formatting and consistency across all examples

Credit Card Token Validation Fix

Real Token Support: Now accepts real encrypted/ciphered credit card tokens
Flexible Format: Supports Base64, URL-safe, and mixed character tokens
Variable Length: Accepts tokens from 16 to 2048 characters
Enhanced Security: Maintains security while accepting real-world tokens
Backward Compatibility: Works with all existing token formats

Workflow Corrections

GitHub Actions Fixed: Resolved release workflow permissions and SRI hash generation
CDN Deployment: Automated deployment to Cloudflare Pages working correctly
Release Automation: GitHub releases created automatically with proper SRI hashes
Build Process: Streamlined build and deployment pipeline

Hybrid Distribution Strategy

NPM Package: Contains only documentation and TypeScript definitions
CDN Scripts: Production-ready obfuscated builds via Cloudflare Pages and jsDelivr
Enhanced Security: Code source protected while maintaining accessibility
Better UX: Easy discovery via NPM, secure usage via CDN

Security & Privacy Improvements

README Anonymization: Removed all personal information and sensitive data
Privacy Protection: No personal emails, URLs, or contact information exposed
Professional Documentation: Clean, business-focused documentation
NPM Safety: Safe for public NPM publication

Test Suite Improvements

Test Coverage Optimization: Fixed all failing unit tests for complete 250 test coverage
Mock Structure Corrections: Updated test mocks to align with actual API response patterns
Customer Management Tests: Corrected mock structures for createCustomer and getCustomer methods
Credit Card Tests: Fixed mock data structures for addCreditCard and getCreditCard methods
Consistent Test Patterns: Standardized mock response structures across all endpoints

API Response Pattern Standardization

Customer Methods: Properly handle response.data.customer structure
Credit Card Methods: Correctly process response.data.creditCard structure
Order Methods: Maintain existing response.data pattern
Improved Reliability: Enhanced test reliability and maintainability

Enhanced ID Validation Support

Multiple ID Format Support: Now accepts UUID v4, UUID v7, and MongoDB ObjectId formats
UUID v4: Standard format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
UUID v7: Modern format xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
MongoDB ObjectId: 24-character hexadecimal format 507f1f77bcf86cd799439011
Strict Validation: Rejects any other formats for enhanced security

Lovable Integration Fixes

Event System Implementation: Complete event system with on() and off() methods
Iframe Compatibility: Fixed iframe blocking issues for low-code platforms
Global Instance: window.easyflowSDK instance with all methods and events
Event Emissions: Automatic events for customerCreated, orderPlaced, and paymentProcessed

Quick Start

Installation

Option 1: CDN Script (Recommended)

Add this script tag to your HTML:

<!-- Latest version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<!-- Specific version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.12.min.js"></script>

Option 2: CDN jsDelivr (Alternative)

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@latest/dist/easyflow-sdk.min.js"></script>

<!-- Specific version -->
<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@2.1.20/dist/easyflow-sdk.min.js"></script>

Option 3: NPM Package (Documentation Only)

npm install @easyflow/javascript-sdk

Note: The NPM package contains only documentation. For production use, use the CDN scripts above.

Basic Usage

Method 1: CDN Script (Recommended for Production)

<!-- Load SDK via script tag -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

Method 2: CDN jsDelivr (Alternative)

<!-- Load SDK via jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@latest/dist/easyflow-sdk.min.js"></script>

// Configure the global instance
easyflowSDK.configure({
    businessId: 'demo-business-12345',
})

// Process a payment
easyflowSDK
    .placeOrder('demo-offer-67890', {
        customer: {
            name: 'João Silva',
            email: 'joao@exemplo.com',
            document: {
                type: 'CPF',
                number: '12345678901',
            },
        },
        payments: [
            {
                method: 'credit-card',
                numberInstallments: 1,
            },
        ],
    })
    .then((orderId) => {
        console.log('Pedido criado:', orderId)
    })
    .catch((error) => {
        console.error('Erro ao criar pedido:', error.message)
    })

Method 3: Global Instance (For Low-Code Platforms & Simple HTML)

<!-- Load SDK via script tag -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

// Configure the global instance
easyflowSDK.configure({
    businessId: 'demo-business-12345',
})

// Now you can use all methods directly
easyflowSDK
    .createCustomer({
        name: 'Maria Silva',
        email: 'maria@exemplo.com',
        document: { type: 'CPF', number: '12345678901' },
    })
    .then((customer) => {
        console.log('Cliente criado:', customer)
    })
    .catch((error) => {
        console.error('Erro ao criar cliente:', error.message)
    })

// Validation methods are always available
if (easyflowSDK.validate.email('teste@exemplo.com')) {
    console.log('Email válido!')
}

// Listen to events
easyflowSDK.on('customerCreated', (data) => {
    console.log('Evento cliente criado:', data)
})

Features

Payment Processing

Credit Card: Highest approval rate with advanced fraud detection
PIX: Instant Brazilian payment method
Bank Billet: Traditional bank payment option
Recurring Payments: Custom subscription rules

Customer Management

Complete Validation: CPF/CNPJ, phone, address validation
Data Sanitization: XSS protection and input cleaning
Secure Storage: Encrypted sensitive data handling

Security Features

PCI Compliance: Bank-level security standards
Fingerprinting: Advanced fraud detection
Rate Limiting: Protection against abuse
Input Validation: Comprehensive data validation
Obfuscated Builds: Production builds are obfuscated for enhanced security
Controlled Distribution: Secure distribution via CDN (Cloudflare Pages + jsDelivr)

Low-Code Platform Support

Lovable Integration: Full compatibility with Lovable platform
Global Instance: window.easyflowSDK for easy integration
Event System: Built-in event handling for on() and off()
Validation Methods: Always available validation functions
Configuration: Simple setup with easyflowSDK.configure()

API Reference

Core Methods

`placeOrder(offerId, data, headers)`

Creates an order using an existing offer.

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    buyer: {
        customerId: customer.id,
        name: 'E. R.',
        email: 'e***o@gmail.com',
        document: {
            number: '***202266**',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '92',
            number: '*****2191',
            isMobile: true,
        },
        address: {
            zipCode: '37537***',
            street: 'Rua R. C. M. de A.',
            complement: '',
            neighborhood: 'M. do S.',
            city: 'Santa Rita do Sapucaí',
            state: 'MG',
            number: '***',
        },
    },
    payments: [
        {
            method: 'credit-card',
            creditCard: {
                token: 'valid token here',
            },
            numberInstallments: 1,
        },
    ],
    metadata: [],
})

`charge(data, headers)`

Processes a direct charge without using an offer.

const orderId = await easyflowSDK.charge({
    buyer: {
        name: 'João Silva Santos',
        email: 'joao.silva@exemplo.com',
        document: {
            number: '12345678901',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '11',
            number: '9988776655',
            isMobile: true,
        },
        address: {
            zipCode: '01234567',
            street: 'Rua das Flores',
            complement: 'Apto 101',
            neighborhood: 'Centro',
            city: 'São Paulo',
            state: 'SP',
            number: '123',
        },
        customerId: 'demo-customer-12345', // ID do cliente existente (opcional)
    },
    payments: [
        {
            method: 'credit-card',
            numberInstallments: 1,
            valueInCents: 500,
            creditCard: {
                cardId: 'demo-card-id-here', // cardId e token são opcionais, mas pelo menos 1 deve ser fornecido
                token: 'demo-token-credit-card-here',
            },
        },
    ],
    items: [
        {
            description: 'Carregador de celular com cabo USB-C',
            name: 'Carregador de Celular',
            quantity: 1,
            priceInCents: 500,
        },
    ],
})

`encrypt(creditCardData, headers)`

Encrypts credit card data for secure processing.

const token = await easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'João Silva',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

Customer Management

`createCustomer(customerData, headers)`

Creates a new customer.

const customer = await easyflowSDK.createCustomer({
    name: 'João Silva',
    email: 'joao@exemplo.com',
    document: { type: 'CPF', number: '12345678901' },
})

`getCustomer(customerId, headers)`

Retrieves customer information.

const customer = await easyflowSDK.getCustomer('demo-customer-12345')

`updateCustomer(customerId, updateData, headers)`

Updates existing customer information.

const result = await easyflowSDK.updateCustomer('demo-customer-12345', {
    name: 'João Atualizado',
    email: 'joao.atualizado@exemplo.com',
})

Credit Card Management

`addCreditCard(customerId, creditCardToken, headers)`

Adds a credit card to a customer.

const result = await easyflowSDK.addCreditCard(
    'demo-customer-12345',
    'encrypted-token-demo'
)

`getCreditCard(customerId, creditCardId, headers)`

Retrieves credit card information.

const creditCard = await easyflowSDK.getCreditCard(
    'demo-customer-12345',
    'demo-card-67890'
)

`removeCreditCard(customerId, creditCardId, headers)`

Removes a credit card from a customer.

const result = await easyflowSDK.removeCreditCard(
    'demo-customer-12345',
    'demo-card-67890'
)

Validation

ID Validation

All entity IDs must follow specific formats:

UUID v4: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
UUID v7: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
MongoDB ObjectId: 24-character hexadecimal format

// Valid IDs
Validator.validateOrderId('f47ac10b-58cc-4372-a567-0e02b2c3d479') // UUID v4
Validator.validateOrderId('01890b24-2d7f-7c3f-8f1a-123456789abc') // UUID v7
Validator.validateOrderId('507f1f77bcf86cd799439011') // MongoDB ObjectId

Data Validation

Comprehensive validation for all input data:

// Customer validation
Validator.validateCustomer({
    name: 'John Doe',
    email: 'john@example.com',
    document: { type: 'CPF', number: '12345678901' },
})

// Payment validation
Validator.validateOrderData({
    items: [{ name: 'Product', price: 1000 }],
    payments: [{ method: 'credit-card', numberInstallments: 1 }],
})

Events

The SDK provides an event system for monitoring operations:

// Listen to events
easyflowSDK.on('customerCreated', (data) => {
    console.log('Cliente criado:', data)
})

easyflowSDK.on('orderPlaced', (data) => {
    console.log('Pedido criado:', data)
})

easyflowSDK.on('paymentProcessed', (data) => {
    console.log('Pagamento processado:', data)
})

// Remove event listeners
easyflowSDK.off('customerCreated', callback)

Error Handling

The SDK provides comprehensive error handling:

try {
    const result = await easyflowSDK.placeOrder('demo-offer-67890', orderData)
} catch (error) {
    if (error.name === 'ValidationError') {
        console.log('Falha na validação:', error.message)
    } else if (error.name === 'NetworkError') {
        console.log('Erro de rede:', error.message)
    } else if (error.name === 'SecurityError') {
        console.log('Violação de segurança:', error.message)
    }
}

Configuration

Business ID

The businessId parameter is a required configuration that identifies your business within the Easyflow platform. You can find this value in your business configuration at https://app.easyflow.digital/.

Important: Never share your business ID publicly. Keep it secure and use it only in your application code.

SDK Options (CDN Implementation)

// Configure the global instance
easyflowSDK.configure({
    businessId: 'demo-business-12345',
    environment: 'production', // 'production' or 'sandbox'
    debug: false, // Enable debug logging
    timeout: 30000, // Request timeout in milliseconds
})

Environment Variables

EASYFLOW_BUSINESS_ID=demo-business-12345
EASYFLOW_ENVIRONMENT=production
EASYFLOW_DEBUG=false

Examples

Complete Checkout Flow

// 1. Create customer
const customer = await easyflowSDK.createCustomer({
    name: 'João Silva',
    email: 'joao@exemplo.com',
    document: { type: 'CPF', number: '12345678901' },
})

// 2. Encrypt credit card
const token = await easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'João Silva',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

// 3. Add credit card to customer
const creditCard = await easyflowSDK.addCreditCard(customer.id, token)

// 4. Place order
const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    buyer: {
        customerId: customer.id,
        name: 'E. R.',
        email: 'e***o@gmail.com',
        document: {
            number: '***202266**',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '92',
            number: '*****2191',
            isMobile: true,
        },
        address: {
            zipCode: '37537***',
            street: 'Rua R. C. M. de A.',
            complement: '',
            neighborhood: 'M. do S.',
            city: 'Santa Rita do Sapucaí',
            state: 'MG',
            number: '***',
        },
    },
    payments: [
        {
            method: 'credit-card',
            creditCard: {
                cardId: creditCard.id,
            },
            numberInstallments: 1,
        },
    ],
    metadata: [],
})

PIX Payment

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    buyer: {
        name: 'E. R.',
        email: 'e***o@gmail.com',
        document: {
            number: '***202266**',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '92',
            number: '*****2191',
            isMobile: true,
        },
        address: {
            zipCode: '37537***',
            street: 'Rua R. C. M. de A.',
            complement: '',
            neighborhood: 'M. do S.',
            city: 'Santa Rita do Sapucaí',
            state: 'MG',
            number: '***',
        },
    },
    payments: [
        {
            method: 'pix',
            numberInstallments: 1,
        },
    ],
})

// Get PIX data
const pixData = await easyflowSDK.getPix(orderId)
console.log('PIX QR Code:', pixData.qrCode)

Bank Billet Payment

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    buyer: {
        name: 'E. R.',
        email: 'e***o@gmail.com',
        document: {
            number: '***202266**',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '92',
            number: '*****2191',
            isMobile: true,
        },
        address: {
            zipCode: '37537***',
            street: 'Rua R. C. M. de A.',
            complement: '',
            neighborhood: 'M. do S.',
            city: 'Santa Rita do Sapucaí',
            state: 'MG',
            number: '***',
        },
    },
    metadata: [],
    payments: [
        {
            method: 'bank-billet',
            numberInstallments: 1,
        },
    ],
})

// Get bank billet data
const bankBillet = await easyflowSDK.getBankBillet(orderId)
console.log('Bank Billet Link:', bankBillet.link)

Complete Implementation Examples

1. placeOrder - Complete Data Model

placeOrder com PIX

// Configure SDK
easyflowSDK.configure({
    businessId: 'demo-business-12345',
})

// Complete placeOrder example with PIX payment
const orderId = await easyflowSDK.placeOrder(
    '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
    {
        buyer: {
            name: 'João Silva Santos',
            email: 'joao.silva@exemplo.com',
            document: {
                number: '12345678901',
                type: 'CPF',
            },
            phone: {
                areaCode: '+55',
                ddd: '11',
                number: '9988776655',
                isMobile: true,
            },
            address: {
                zipCode: '01234567',
                street: 'Rua das Flores',
                complement: 'Apto 101',
                neighborhood: 'Centro',
                city: 'São Paulo',
                state: 'SP',
                number: '123',
            },
        },
        payments: [
            {
                method: 'pix',
                numberInstallments: 1,
            },
        ],
        metadata: [],
    }
)

console.log('Order created with PIX payment:', orderId)

placeOrder com Cartão de Crédito

// Complete placeOrder example with credit card payment
const orderId = await easyflowSDK.placeOrder(
    '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
    {
        buyer: {
            name: 'João Silva Santos',
            email: 'joao.silva@exemplo.com',
            document: {
                number: '12345678901',
                type: 'CPF',
            },
            phone: {
                areaCode: '+55',
                ddd: '11',
                number: '9988776655',
                isMobile: true,
            },
            address: {
                zipCode: '01234567',
                street: 'Rua das Flores',
                complement: 'Apto 101',
                neighborhood: 'Centro',
                city: 'São Paulo',
                state: 'SP',
                number: '123',
            },
        },
        payments: [
            {
                method: 'credit-card',
                numberInstallments: 1,
                creditCard: {
                    cardId: 'demo-credit-card-67890', // cardId e token são opcionais, mas pelo menos 1 deve ser fornecido
                    token: 'demo-credit-card-token-here',
                    last4Numbers: '1234',
                    holderName: 'JOAO SILVA SANTOS',
                    expiresAtMonth: '12',
                    expiresAtYear: '2025',
                    flag: 'visa',
                },
            },
        ],
        metadata: [],
    }
)

console.log('Order created with credit card payment:', orderId)

2. charge - Complete Data Model

charge com Cartão de Crédito

// Complete charge example with credit card payment
const orderId = await easyflowSDK.charge({
    buyer: {
        name: 'João Silva Santos',
        email: 'joao.silva@exemplo.com',
        document: {
            number: '12345678901',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '11',
            number: '9988776655',
            isMobile: true,
        },
        address: {
            zipCode: '01234567',
            street: 'Rua das Flores',
            complement: 'Apto 101',
            neighborhood: 'Centro',
            city: 'São Paulo',
            state: 'SP',
            number: '123',
        },
        customerId: 'demo-customer-12345', // ID do cliente existente (opcional)
    },
    payments: [
        {
            method: 'credit-card',
            numberInstallments: 1,
            valueInCents: 500,
            creditCard: {
                cardId: 'demo-card-id-here', // cardId e token são opcionais, mas pelo menos 1 deve ser fornecido
                token: 'demo-token-credit-card-here',
            },
        },
    ],
    items: [
        {
            description: 'Carregador de celular com cabo USB-C',
            name: 'Carregador de Celular',
            quantity: 1,
            priceInCents: 500,
        },
    ],
})

console.log('Charge processed with credit card:', orderId)

charge com PIX

// Complete charge example with PIX payment
const orderId = await easyflowSDK.charge({
    buyer: {
        name: 'João Silva Santos',
        email: 'joao.silva@exemplo.com',
        document: {
            number: '12345678901',
            type: 'CPF',
        },
        phone: {
            areaCode: '+55',
            ddd: '11',
            number: '9988776655',
            isMobile: true,
        },
        address: {
            zipCode: '01234567',
            street: 'Rua das Flores',
            complement: 'Apto 101',
            neighborhood: 'Centro',
            city: 'São Paulo',
            state: 'SP',
            number: '123',
        },
        customerId: 'demo-customer-12345', // ID do cliente existente (opcional)
    },
    payments: [
        {
            method: 'pix',
            numberInstallments: 1,
            valueInCents: 500,
        },
    ],
    items: [
        {
            description: 'Carregador de celular com cabo USB-C',
            name: 'Carregador de Celular',
            quantity: 1,
            priceInCents: 500,
        },
    ],
    businessId: 'demo-business-12345',
})

console.log('Charge processed with PIX:', orderId)

3. createCustomer - Complete Data Model

// Complete createCustomer example with all available fields
const customer = await easyflowSDK.createCustomer({
    name: 'João Silva Santos',
    email: 'joao.silva@exemplo.com',
    document: {
        type: 'CPF',
        number: '12345678901',
    },
    phone: {
        areaCode: '+55',
        ddd: '11',
        number: '9988776655',
        isMobile: true,
    },
    address: {
        zipCode: '01234567',
        street: 'Rua das Flores',
        complement: 'Apto 101',
        neighborhood: 'Centro',
        city: 'São Paulo',
        state: 'SP',
        number: '123',
    },
    deliveryAddress: {
        zipCode: '01234567',
        street: 'Rua das Flores',
        complement: 'Apto 101',
        neighborhood: 'Centro',
        city: 'São Paulo',
        state: 'SP',
        number: '123',
    },
})

console.log('Customer created with complete data:', customer)

4. addCreditCard - Complete Data Model

// First, encrypt the credit card data
const encryptedToken = await easyflowSDK.encrypt({
    cardNumber: '4111111111111111',
    cvv: '123',
    month: '12',
    year: '2025',
    holderName: 'PEDRO OLIVEIRA LIMA',
})

console.log('Credit card encrypted:', encryptedToken)

// Then add the encrypted token to the customer
const creditCard = await easyflowSDK.addCreditCard(
    customer.id, // customer ID from createCustomer
    encryptedToken
)

console.log('Credit card added successfully:', creditCard)

// Now you can use the credit card for payments
const orderWithSavedCard = await easyflowSDK.placeOrder(
    '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
    {
        buyer: {
            customerId: customer.id, // Use existing customer
            name: 'João Silva Santos',
            email: 'joao.silva@exemplo.com',
            document: {
                number: '12345678901',
                type: 'CPF',
            },
        },
        payments: [
            {
                method: 'credit-card',
                numberInstallments: 6,
                creditCard: {
                    cardId: creditCard.id, // Use saved credit card
                },
            },
        ],
        offerItems: [
            {
                offerItemId: '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
                quantity: 1,
            },
        ],
        metadata: [],
    }
)

console.log('Order with saved credit card:', orderWithSavedCard)

5. Complete Workflow Example

// Complete workflow: Customer → Credit Card → Order
async function completeWorkflow() {
    try {
        // 1. Configure SDK
        easyflowSDK.configure({
            businessId: 'demo-business-12345',
        })

        // 2. Create customer with complete data
        const customer = await easyflowSDK.createCustomer({
            name: 'Ana Silva Costa',
            email: 'ana.silva@exemplo.com',
            document: { type: 'CPF', number: '55566677788' },
            phone: {
                areaCode: '+55',
                ddd: '41',
                number: '765432109',
                isMobile: true,
            },
            address: {
                zipCode: '80000000',
                street: 'Rua das Palmeiras',
                complement: 'Apto 202',
                neighborhood: 'Batel',
                city: 'Curitiba',
                state: 'PR',
                number: '321',
            },
        })

        // 3. Encrypt and add credit card
        const token = await easyflowSDK.encrypt({
            cardNumber: '5555555555554444',
            cvv: '321',
            month: '10',
            year: '2026',
            holderName: 'ANA SILVA COSTA',
        })

        const creditCard = await easyflowSDK.addCreditCard(customer.id, token)

        // 4. Create order using saved customer and credit card
        const orderId = await easyflowSDK.placeOrder(
            '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
            {
                buyer: {
                    customerId: customer.id,
                    name: customer.name,
                    email: customer.email,
                    document: customer.document,
                },
                payments: [
                    {
                        method: 'credit-card',
                        numberInstallments: 12,
                        creditCard: { cardId: creditCard.id },
                    },
                ],
                offerItems: [
                    {
                        offerItemId: '3df92ac7-9d7f-4948-b54f-7e082492f6d2',
                        quantity: 1,
                    },
                ],
                metadata: [],
            }
        )

        console.log('Complete workflow successful:', {
            customer: customer.id,
            creditCard: creditCard.id,
            order: orderId,
        })
    } catch (error) {
        console.error('Workflow failed:', error.message)
    }
}

// Execute the complete workflow
completeWorkflow()

Distribution & Security

Why CDN Scripts?

Obfuscated Builds: Production code is obfuscated for security
Controlled Access: Secure distribution via Cloudflare Pages and jsDelivr
Version Control: Specific versions available for stability
Performance: Global CDN for fast loading

Available CDN URLs

Cloudflare Pages (Primary)

<!-- Latest version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<!-- Versioned (recommended for production) -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.19.min.js"></script>

<!-- With SRI (Subresource Integrity) -->
<script
    src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.19.min.js"
    integrity="sha384-[hash]"
    crossorigin="anonymous"
></script>

jsDelivr (Alternative)

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@latest/dist/easyflow-sdk.min.js"></script>

<!-- Specific version -->
<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@2.1.20/dist/easyflow-sdk.min.js"></script>

Browser Support

Node.js Support

Node.js: 18+
npm: 8+
yarn: 1.22+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

Documentation: https://docs.easyflow.digital
Website: https://www.easyflow.digital
Contact: contato@easyflow.digital

License

This project is licensed under the ISC License - see the LICENSE file for details.

Author

Diego Moura - Co-Found & CTO at Easyflow

Email: diego@easyflow.digital
Website: https://diegomoura.pro
GitHub: https://github.com/dmourainatel

Changelog

v2.1.20

jsDelivr CDN Fix: Fixed npm package to include easyflow-sdk.min.js for proper jsDelivr CDN support
Package Structure: Corrected package.json files field to include JavaScript build files
CDN Availability: jsDelivr now properly serves the SDK at specific version URLs
Homepage Redirect: Added automatic redirect from SDK homepage to NPM package for better discoverability

v2.1.19

Documentation Updates: Removed all references to private repository
Business ID Information: Added clear guidance on where to find BUSINESS_ID parameter
Contact Information: Added official contact email for support
Author Information: Updated author details and role information
Repository Cleanup: Cleaned up all private repository references
CDN Options: Added jsDelivr as alternative CDN option for installation

v2.1.18

Version Update: Patch release for latest improvements
Documentation: Updated version references and CDN URLs
Consistency: All version references aligned to v2.1.18

v2.1.17

Complete Implementation Examples: Added comprehensive examples for all major methods
Full Data Models: Examples showing all available fields for placeOrder, charge, createCustomer, addCreditCard
Brazilian Data Examples: Realistic Brazilian addresses, phone
Version Update: Patch release for latest improvements
Documentation: Updated version references and CDN URLs
Consistency: All version references aligned to v2.1.17

v2.1.14

Version Update: Patch release for latest improvements
Documentation: Updated version references and CDN URLs
Consistency: All version references aligned to v2.1.14

v2.1.13

Code Formatting: Improved readability of placeOrder examples with better line breaks
Documentation: Enhanced formatting for complex method calls
Examples: Better visual structure for placeOrder, charge, and workflow examples
Consistency: Unified formatting across all code examples

v2.1.12

Complete Implementation Examples: Added comprehensive examples for all major methods
Full Data Models: Examples showing all available fields for placeOrder, charge, createCustomer, addCreditCard
Brazilian Data Examples: Realistic Brazilian addresses, phone numbers, and document formats
End-to-End Workflows: Complete customer → credit card → order workflow examples
Code Quality: Improved formatting, consistency, and readability across all examples
Documentation: Fixed duplicate sections and improved overall structure

v2.1.11

Credit Card Token Fix: Accepts real encrypted/ciphered tokens from vault services
Flexible Validation: Supports Base64, URL-safe, and mixed character formats
Variable Length: Accepts tokens from 16 to 2048 characters
Enhanced Security: Maintains security while accepting real-world tokens
Backward Compatibility: Works with all existing token formats

v2.1.10

Workflow Fixed: Resolved GitHub Actions permissions and SRI hash generation
CDN Automation: Automated deployment to Cloudflare Pages working correctly
Release Process: GitHub releases created automatically with proper SRI hashes
Build Pipeline: Streamlined build and deployment process

v2.1.9

Hybrid Distribution: NPM for docs, CDN for secure obfuscated code
Enhanced Security: Code source protected while maintaining accessibility
Better UX: Easy discovery via NPM, secure usage via CDN
Documentation: Complete setup and usage instructions

v2.1.8

Security & Privacy: Anonymized README.md for safe NPM publication
Documentation: Removed all personal information and sensitive data
Professional: Clean, business-focused documentation

v2.1.7

Fixed all failing unit tests for complete 250 test coverage
Corrected mock structures for customer and credit card management
Standardized API response patterns across all endpoints
Enhanced test reliability and maintainability

v2.1.6

Enhanced ID validation with UUID v4, UUID v7, and MongoDB ObjectId support
Fixed iframe compatibility issues for low-code platforms
Implemented complete event system with on() and off() methods
Added global SDK instance for easier integration

v2.1.5

Added browser fingerprinting for enhanced security
Implemented automatic x-fingerprint-id header generation
Enhanced security validation and error handling
Improved documentation and examples

Built with ❤️ by the Easyflow Team