Package Exports

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

Readme

Easyflow JavaScript SDK

Enterprise-grade JavaScript SDK for Easyflow payment processing platform - Documentation and TypeScript definitions only

📊 Project Status & Quality

🔗 Quick Links

📖 Documentation Hub | 📋 Data Structures | 🔧 API Reference | 📦 NPM Package

What's New in v2.2.3

🆕 New Features

Enhanced Buyer Validation: Comprehensive validation for buyer data in orders, including phone and document number format validation
Items Validation for Charge Method: Rigorous validation of items array with support for name, priceInCents, quantity, and optional description
Integer Validation: New isInteger() method for validating integer values (no decimals allowed)
Numeric String Validation: Enhanced validation for phone numbers and document numbers (only digits allowed)
Payload Cleaning: New cleanPayload() function that automatically removes null, undefined, and empty values before API calls

🔧 Improvements

Better Error Messages: More specific error messages with field context (e.g., items[0].name)
Comprehensive Testing: 298 test cases across 9 test suites ensuring robust validation and functionality
Type Safety: Enhanced validation for all data structures with clear error reporting
Code Quality: 100% test coverage for all core modules and functions

🛡️ Security & Validation

Phone Number Format: Enforces clean numeric format (e.g., "984762782" not "98-476-2782")
Document Number Format: Ensures clean numeric format (e.g., "11039630669" not "110.396.306-69")
Items Validation: Strict validation for charge items with required fields and optional description (max 200 chars)
Boolean Validation: Enhanced validation for boolean fields like isMobile
Address Validation: Rigorous validation for zipCode (exactly 8 digits) and all required address fields

📚 Documentation

Updated Examples: All examples now include complete data structures
Validation Rules: Clear documentation of validation requirements for each field
Error Handling: Comprehensive error handling examples and best practices

🧪 Testing & Quality Assurance

Test Coverage

The SDK maintains 100% test coverage across all core modules:

298 tests passing ✅
9 test suites covering all functionality
0 test failures ensuring reliability
Comprehensive validation testing for all data structures

Test Suites

Validator Tests: 79 tests covering all validation logic
SDK Core Tests: 35 tests covering main SDK functionality
Sanitizer Tests: 33 tests covering input sanitization
Error Handling Tests: 21 tests covering error scenarios
HTTP Module Tests: 16 tests covering API communication
Utils Tests: 15 tests covering utility functions
Constants Tests: 14 tests covering configuration
Logger Tests: 13 tests covering logging functionality
Exception Handler Tests: 22 tests covering error throwing

Quality Metrics

Zero critical bugs in production
Comprehensive error handling for all edge cases
Input validation for all user-provided data
Security-first approach with built-in protection mechanisms
Performance optimized with efficient algorithms and data structures

Quick Start

Via CDN

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

TypeScript Integration

For TypeScript projects, the SDK is exposed globally when loaded via CDN. Add the following declarations to your project:

// O SDK está sendo carregado via CDN e exposto globalmente como window.easyflowSDK
declare global {
    interface Window {
        easyflowSDK: any
        EasyflowSDK: any
    }
}

Usage Example with TypeScript

// Configurar o SDK
window.easyflowSDK.configure({ businessId: 'your-business-id' })

// Usar métodos do SDK
const customer = await window.easyflowSDK.createCustomer(customerData)
const payment = await window.easyflowSDK.charge(paymentData)

Usage

Basic Configuration

// Configure the SDK with your business ID
window.easyflowSDK.configure({
    businessId: 'your-business-id',
})

Customer Management

// Create a customer
const customer = await window.easyflowSDK.createCustomer({
    name: 'John Doe',
    email: 'john@example.com',
    document: {
        type: 'CPF',
        number: '12345678901',
    },
    phone: {
        areaCode: '+55',
        ddd: '11',
        number: '999999999',
        isMobile: true,
    },
    address: {
        zipCode: '01234567',
        street: 'Rua das Flores',
        number: '123',
        complement: 'Apto 45',
        neighborhood: 'Centro',
        city: 'São Paulo',
        state: 'SP',
    },
})

// Get customer by ID
const customerData = await window.easyflowSDK.getCustomer(customer.id)

// Update customer
const updatedCustomer = await window.easyflowSDK.updateCustomer(customer.id, {
    name: 'John Updated',
})

Payment Processing

// Process a charge - with PIX method
const orderId = await window.easyflowSDK.charge({
    buyer: customerData,
    payments: [
        {
            method: 'pix',
            valueInCents: 10000,
            numberInstallments: 1,
        },
    ],
    items: [
        {
            description: 'Product Description',
            name: 'Product',
            priceInCents: 10000, // Price in cents - R$100,00
            quantity: 1,
        },
    ],
})

// Process a charge - with Credit Card method [One-time payment]
const encryptedCard = await window.easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'JOHN DOE',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

const orderId = await window.easyflowSDK.charge({
    buyer: customerData,
    payments: [
        {
            method: 'credit-card',
            valueInCents: 10000,
            numberInstallments: 1,
            creditCard: {
                token: encryptedCard,
                last4Numbers: '1234',
                holderName: 'JOHN DOE',
                expiresAtMonth: '12',
                expiresAtYear: '2025',
                flag: 'visa',
            },
        },
    ],
    items: [
        {
            description: 'Product Description',
            name: 'Product',
            priceInCents: 10000, // Price in cents - R$100,00
            quantity: 1,
        },
    ],
})

// Process a payment - with Credit Card method [Saving card for future use]
const encryptedCard = await window.easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'JOHN DOE',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

// Add credit card
const creditCard = await window.easyflowSDK.addCreditCard(
    customer.id,
    encryptedCard
)

const orderId = await window.easyflowSDK.charge({
    buyer: { customerId: customer.id, ...customerData },
    payments: [
        {
            method: 'credit-card',
            valueInCents: 10000,
            numberInstallments: 1,
            creditCard: {
                cardId: creditCard.id,
            },
        },
    ],
    items: [
        {
            description: 'Product Description',
            name: 'Product',
            priceInCents: 10000, // Price in cents - R$100,00
            quantity: 1,
        },
    ],
})

Order Management

// Place an order
const orderId = await window.easyflowSDK.placeOrder('offer-id', {
    buyer: customerData,
    payments: [
        {
            method: 'pix',
            numberInstallments: 1,
        },
    ],
})

// Get order by ID
const orderData = await window.easyflowSDK.getOrder(orderId)

Credit Card Management

// Encrypt credit card data
const encryptedCard = await window.easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'JOHN DOE',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

// Add credit card
const creditCard = await window.easyflowSDK.addCreditCard(
    'customer-id',
    'encrypted-token'
)

// Get credit card
const cardData = await window.easyflowSDK.getCreditCard(
    'customer-id',
    'card-id'
)

// Remove credit card
const result = await window.easyflowSDK.removeCreditCard(
    'customer-id',
    'card-id'
)

Utility Methods

// Get SDK status
const status = window.easyflowSDK.getStatus()

Events

// SDK Ready
window.easyflowSDK.on('SDKReady', (data) => {
    console.log('SDK loaded:', data)
})

// Customer created
window.easyflowSDK.on('customerCreated', (customer) => {
    console.log('Customer created:', customer)
})

// Payment processed
window.easyflowSDK.on('paymentProcessed', (payment) => {
    console.log('Payment processed:', payment)
})

// Order placed
window.easyflowSDK.on('orderPlaced', (order) => {
    console.log('Order placed:', order)
})

// Error
window.easyflowSDK.on('error', (error) => {
    console.error('Error:', error)
})

Security Features

HTTPS/SSL Strict - All communications are encrypted
CORS with domain validation - Strict cross-origin protection
Rate limiting - Protection against abuse
Input validation - Comprehensive data validation
Replay protection - Protection against replay attacks
Iframe protection - Protection against clickjacking
XSS protection - Protection against cross-site scripting

Authentication

ECDSA (P-256) - Elliptic curve digital signature algorithm
SHA256 - Secure hash algorithm
Browser fingerprinting - Device identification
Domain validation - Origin verification

Compliance

PCI-DSS - Payment Card Industry Data Security Standard
LGPD - Brazilian General Data Protection Law
GDPR - General Data Protection Regulation

Compatibility

Browsers: Chrome, Firefox, Safari, Edge
Frameworks: React, Vue, Angular, vanilla JS
Mobile: Web, PWA, Hybrid apps
TypeScript: Full support
NPM: Installation via package manager
CDN: Direct loading

Performance

Size: ~97KB (minified and obfuscated)
Loading: Asynchronous and non-blocking
Cache: CDN optimized
Bundle: Compatible with modern bundlers

Support

Email: contato@easyflow.digital
Documentation: https://docs.easyflow.digital
NPM: https://www.npmjs.com/package/@easyflow/javascript-sdk

Documentation

Documentation Hub - Central documentation access
Main README - Complete SDK documentation
DATA-STRUCTURES.md - Complete data structure reference

E2E Testing

This project includes a complete E2E application in e2e/react-ts-e2e/ that demonstrates SDK integration via NPM in a React + TypeScript project.

This E2E project proves that the Easyflow SDK works perfectly via NPM in TypeScript/React projects with a complete and functional interface! 🚀✨

Installation

Via CDN

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

Quick Integration

// Load SDK
const sdk = new EasyflowSDK('your-business-id')

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

sdk.on('error', (error) => {
    console.log('Error on payment process:', error)
})

// Process charge with charge using PIX method
const orderId = await sdk.charge({
    buyer: {
        name: 'John Doe',
        email: 'john@example.com',
        document: {
            type: 'CPF',
            number: '12345678901',
        },
        phone: {
            areaCode: '+55',
            ddd: '11',
            number: '999999999',
            isMobile: true,
        },
        address: {
            zipCode: '01234567',
            street: 'Rua das Flores',
            number: '123',
            complement: 'Apto 45',
            neighborhood: 'Centro',
            city: 'São Paulo',
            state: 'SP',
        },
    },
    payments: [{ method: 'pix', valueInCents: 10000, numberInstallments: 1 }],
    items: [
        {
            description: 'Product Description',
            name: 'Product',
            priceInCents: 10000, // Price in cents - R$100,00
            quantity: 1,
        },
    ],
})

License

ISC License - see LICENSE file for details.

Contributing

For contributions, please visit our GitHub repository.

Built with ❤️ by the Easyflow Team