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.10

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
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

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

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.10.min.js"></script>

Option 2: NPM Package (Documentation Only)

npm install @easyflow/javascript-sdk

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

Option 3: Direct Download

Download the latest obfuscated build from GitHub Releases.

Basic Usage

import { EasyflowSDK } from '@easyflow/javascript-sdk'

// Initialize SDK
const sdk = new EasyflowSDK({
    businessId: 'your-business-id',
})

// Process a payment
const orderId = await sdk.placeOrder('offer-id', {
    customer: {
        name: 'John Doe',
        email: 'john@example.com',
        document: {
            type: 'CPF',
            number: '12345678901',
        },
    },
    payments: [
        {
            method: 'credit-card',
            numberInstallments: 1,
        },
    ],
})

console.log('Order created:', orderId)

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 and GitHub Releases

API Reference

Core Methods

`placeOrder(offerId, data, headers)`

Creates an order using an existing offer.

const orderId = await sdk.placeOrder('offer-id', {
    customer: {
        /* customer data */
    },
    payments: [
        /* payment methods */
    ],
})

`charge(data, headers)`

Processes a direct charge without using an offer.

const orderId = await sdk.charge({
    items: [{ name: 'Product', price: 1000 }],
    payments: [{ method: 'pix', numberInstallments: 1 }],
})

`encrypt(creditCardData, headers)`

Encrypts credit card data for secure processing.

const token = await sdk.encrypt({
    number: '4111111111111111',
    holderName: 'John Doe',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

Customer Management

`createCustomer(customerData, headers)`

Creates a new customer.

const customer = await sdk.createCustomer({
    name: 'John Doe',
    email: 'john@example.com',
    document: { type: 'CPF', number: '12345678901' },
})

`getCustomer(customerId, headers)`

Retrieves customer information.

const customer = await sdk.getCustomer('customer-id')

`updateCustomer(customerId, updateData, headers)`

Updates existing customer information.

const result = await sdk.updateCustomer('customer-id', {
    name: 'John Updated',
    email: 'john.updated@example.com',
})

Credit Card Management

`addCreditCard(customerId, creditCardToken, headers)`

Adds a credit card to a customer.

const result = await sdk.addCreditCard('customer-id', 'encrypted-token')

`getCreditCard(customerId, creditCardId, headers)`

Retrieves credit card information.

const creditCard = await sdk.getCreditCard('customer-id', 'credit-card-id')

`removeCreditCard(customerId, creditCardId, headers)`

Removes a credit card from a customer.

const result = await sdk.removeCreditCard('customer-id', 'credit-card-id')

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
sdk.on('customerCreated', (data) => {
    console.log('Customer created:', data)
})

sdk.on('orderPlaced', (data) => {
    console.log('Order placed:', data)
})

sdk.on('paymentProcessed', (data) => {
    console.log('Payment processed:', data)
})

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

Error Handling

The SDK provides comprehensive error handling:

try {
    const result = await sdk.placeOrder('offer-id', orderData)
} catch (error) {
    if (error.name === 'ValidationError') {
        console.log('Validation failed:', error.message)
    } else if (error.name === 'NetworkError') {
        console.log('Network error:', error.message)
    } else if (error.name === 'SecurityError') {
        console.log('Security violation:', error.message)
    }
}

Configuration

SDK Options

const sdk = new EasyflowSDK({
    businessId: 'your-business-id',
    environment: 'production', // 'production' or 'sandbox'
    debug: false, // Enable debug logging
    timeout: 30000, // Request timeout in milliseconds
})

Environment Variables

EASYFLOW_BUSINESS_ID=your-business-id
EASYFLOW_ENVIRONMENT=production
EASYFLOW_DEBUG=false

Examples

Complete Checkout Flow

// 1. Create customer
const customer = await sdk.createCustomer({
    name: 'John Doe',
    email: 'john@example.com',
    document: { type: 'CPF', number: '12345678901' },
})

// 2. Encrypt credit card
const token = await sdk.encrypt({
    number: '4111111111111111',
    holderName: 'John Doe',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

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

// 4. Place order
const orderId = await sdk.placeOrder('offer-id', {
    customer: customer,
    payments: [
        {
            method: 'credit-card',
            creditCardId: creditCard.creditCardId,
            numberInstallments: 1,
        },
    ],
})

PIX Payment

const orderId = await sdk.placeOrder('offer-id', {
    customer: {
        /* customer data */
    },
    payments: [
        {
            method: 'pix',
            numberInstallments: 1,
        },
    ],
})

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

Bank Billet Payment

const orderId = await sdk.placeOrder('offer-id', {
    customer: {
        /* customer data */
    },
    payments: [
        {
            method: 'bank-billet',
            numberInstallments: 1,
        },
    ],
})

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

Distribution & Security

Why CDN Scripts?

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

Available CDN URLs

<!-- 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.8.min.js"></script>

<!-- With SRI (Subresource Integrity) -->
<script
    src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.10.min.js"
    integrity="sha384-[hash]"
    crossorigin="anonymous"
></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
GitHub Issues: https://github.com/easyflow-cash/easyflow-javascript-sdk/issues
Website: https://www.easyflow.digital

License

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

Changelog

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