@easyflow/javascript-sdk 2.1.23 → 2.1.25

package/DATA-STRUCTURES.md

@@ -0,0 +1,457 @@
+# Easyflow SDK - Data Structures Reference
+
+This document provides detailed information about the data structures expected by the Easyflow JavaScript SDK.
+
+## Table of Contents
+
+1. [Customer Data Structure](#customer-data-structure)
+2. [Payment Data Structure](#payment-data-structure)
+3. [Order Data Structure](#order-data-structure)
+4. [Credit Card Data Structure](#credit-card-data-structure)
+5. [Address Data Structure](#address-data-structure)
+6. [Phone Data Structure](#phone-data-structure)
+7. [Document Data Structure](#document-data-structure)
+8. [Item Data Structure](#item-data-structure)
+9. [Metadata Structure](#metadata-structure)
+10. [Error Response Structure](#error-response-structure)
+
+## Customer Data Structure
+
+### Required Fields
+
+```typescript
+interface Customer {
+    name: string // Full name (min: 2, max: 100 characters)
+    email: string // Valid email address
+    document: Document // CPF or CNPJ information
+}
+```
+
+### Optional Fields
+
+```typescript
+interface CustomerExtended extends Customer {
+    phone?: Phone // Phone number information
+    address?: Address // Billing address
+    deliveryAddress?: Address // Delivery address (if different from billing)
+    metadata?: Metadata[] // Additional customer information
+}
+```
+
+### Example
+
+```javascript
+const customer = {
+    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',
+    },
+}
+```
+
+## Payment Data Structure
+
+### Credit Card Payment
+
+```typescript
+interface CreditCardPayment {
+    method: 'credit-card'
+    numberInstallments: number // 1-12 installments
+    valueInCents?: number // Required for charge(), optional for placeOrder()
+    creditCard: {
+        cardId?: string // Saved card ID
+        token?: string // Encrypted card token
+        last4Numbers?: string // Last 4 digits
+        holderName?: string // Card holder name
+        expiresAtMonth?: string // Expiration month (01-12)
+        expiresAtYear?: string // Expiration year (YYYY)
+        flag?: string // Card brand (visa, mastercard, etc.)
+    }
+}
+```
+
+### PIX Payment
+
+```typescript
+interface PixPayment {
+    method: 'pix'
+    numberInstallments: number // Always 1 for PIX
+    valueInCents?: number // Required for charge(), optional for placeOrder()
+}
+```
+
+### Bank Billet Payment
+
+```typescript
+interface BankBilletPayment {
+    method: 'bank-billet'
+    numberInstallments: number // Always 1 for bank billet
+    valueInCents?: number // Required for charge(), optional for placeOrder()
+}
+```
+
+### Example
+
+```javascript
+const payments = [
+    {
+        method: 'credit-card',
+        numberInstallments: 6,
+        creditCard: {
+            cardId: 'saved-card-123',
+            last4Numbers: '1234',
+            holderName: 'JOAO SILVA SANTOS',
+            expiresAtMonth: '12',
+            expiresAtYear: '2025',
+            flag: 'visa',
+        },
+    },
+    {
+        method: 'pix',
+        numberInstallments: 1,
+    },
+]
+```
+
+## Order Data Structure
+
+### Buyer Information
+
+```typescript
+interface Buyer {
+    customerId?: string // Existing customer ID (optional)
+    name: string // Full name
+    email: string // Valid email
+    document: Document // CPF or CNPJ
+    phone: Phone // Phone number
+    address: Address // Billing address
+}
+```
+
+### Complete Order Structure
+
+```typescript
+interface OrderData {
+    buyer: Buyer
+    payments: Payment[]
+    offerItems?: OfferItem[] // For placeOrder()
+    items?: Item[] // For charge()
+    metadata?: Metadata[]
+}
+```
+
+### Example
+
+```javascript
+const orderData = {
+    buyer: {
+        customerId: 'existing-customer-123',
+        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',
+        },
+    },
+    payments: [
+        {
+            method: 'credit-card',
+            numberInstallments: 6,
+            creditCard: {
+                cardId: 'saved-card-123',
+            },
+        },
+    ],
+    offerItems: [
+        {
+            offerItemId: 'offer-item-123',
+            quantity: 1,
+        },
+    ],
+    metadata: [
+        {
+            key: 'source',
+            value: 'website',
+        },
+    ],
+}
+```
+
+## Credit Card Data Structure
+
+### For Encryption
+
+```typescript
+interface CreditCardData {
+    cardNumber: string // 13-19 digits
+    cvv: string // 3-4 digits
+    month: string // 01-12
+    year: string // YYYY format
+    holderName: string // Card holder name
+}
+```
+
+### Example
+
+```javascript
+const creditCardData = {
+    cardNumber: '4111111111111111',
+    cvv: '123',
+    month: '12',
+    year: '2025',
+    holderName: 'JOAO SILVA SANTOS',
+}
+```
+
+## Address Data Structure
+
+```typescript
+interface Address {
+    zipCode: string // Brazilian ZIP code (8 digits)
+    street: string // Street name
+    complement?: string // Apartment, building, etc.
+    neighborhood: string // Neighborhood name
+    city: string // City name
+    state: string // State abbreviation (SP, RJ, MG, etc.)
+    number: string // House/building number
+}
+```
+
+### Example
+
+```javascript
+const address = {
+    zipCode: '01234567',
+    street: 'Rua das Flores',
+    complement: 'Apto 101',
+    neighborhood: 'Centro',
+    city: 'São Paulo',
+    state: 'SP',
+    number: '123',
+}
+```
+
+## Phone Data Structure
+
+```typescript
+interface Phone {
+    areaCode: string // Country code (+55 for Brazil)
+    ddd: string // Area code (11, 21, 31, etc.)
+    number: string // Phone number (8-9 digits)
+    isMobile: boolean // Whether it's a mobile number
+}
+```
+
+### Example
+
+```javascript
+const phone = {
+    areaCode: '+55',
+    ddd: '11',
+    number: '9988776655',
+    isMobile: true,
+}
+```
+
+## Document Data Structure
+
+```typescript
+interface Document {
+    type: 'CPF' | 'CNPJ' // Document type
+    number: string // Document number (CPF: 11 digits, CNPJ: 14 digits)
+}
+```
+
+### Example
+
+```javascript
+const cpfDocument = {
+    type: 'CPF',
+    number: '12345678901',
+}
+
+const cnpjDocument = {
+    type: 'CNPJ',
+    number: '12345678000195',
+}
+```
+
+## Item Data Structure
+
+### For charge() method
+
+```typescript
+interface Item {
+    name: string // Product name
+    description: string // Product description
+    quantity: number // Quantity (positive integer)
+    priceInCents: number // Price in cents (positive integer)
+}
+```
+
+### Example
+
+```javascript
+const items = [
+    {
+        name: 'Carregador de Celular',
+        description: 'Carregador de celular com cabo USB-C',
+        quantity: 1,
+        priceInCents: 5000, // R$ 50,00
+    },
+    {
+        name: 'Cabo USB-C',
+        description: 'Cabo USB-C de alta velocidade',
+        quantity: 2,
+        priceInCents: 1500, // R$ 15,00 cada
+    },
+]
+```
+
+## Metadata Structure
+
+```typescript
+interface Metadata {
+    key: string // Metadata key
+    value: string // Metadata value
+}
+```
+
+### Example
+
+```javascript
+const metadata = [
+    {
+        key: 'source',
+        value: 'website',
+    },
+    {
+        key: 'campaign',
+        value: 'black-friday-2024',
+    },
+    {
+        key: 'user_id',
+        value: 'user-12345',
+    },
+]
+```
+
+## Error Response Structure
+
+### Standard Error Format
+
+```typescript
+interface ErrorResponse {
+    error: {
+        code: string // Error code
+        message: string // Human-readable error message
+        details?: string // Additional error details
+        field?: string // Field that caused the error
+        value?: any // Value that caused the error
+    }
+    timestamp: string // ISO timestamp
+    requestId?: string // Unique request identifier
+}
+```
+
+### Common Error Codes
+
+| Code                     | Description              | HTTP Status |
+| ------------------------ | ------------------------ | ----------- |
+| `VALIDATION_ERROR`       | Data validation failed   | 400         |
+| `SECURITY_ERROR`         | Security violation       | 403         |
+| `RATE_LIMIT_EXCEEDED`    | Too many requests        | 429         |
+| `NETWORK_ERROR`          | Network/API error        | 500+        |
+| `BUSINESS_ID_INVALID`    | Invalid business ID      | 400         |
+| `OFFER_NOT_FOUND`        | Offer not found          | 404         |
+| `CUSTOMER_NOT_FOUND`     | Customer not found       | 404         |
+| `PAYMENT_METHOD_INVALID` | Invalid payment method   | 400         |
+| `CREDIT_CARD_INVALID`    | Invalid credit card data | 400         |
+
+### Example Error Response
+
+```javascript
+{
+    "error": {
+        "code": "VALIDATION_ERROR",
+        "message": "Invalid email format",
+        "details": "Email must be a valid email address",
+        "field": "email",
+        "value": "invalid-email"
+    },
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "requestId": "req-12345-abcde"
+}
+```
+
+## Validation Rules
+
+### String Lengths
+
+- **Name**: 2-100 characters
+- **Email**: 5-254 characters
+- **Street**: 5-200 characters
+- **City**: 2-100 characters
+- **State**: 2 characters (Brazilian states)
+- **ZIP Code**: 8 characters (Brazilian format)
+
+### Numeric Ranges
+
+- **Phone DDD**: 11-99 (Brazilian area codes)
+- **Phone Number**: 8-9 digits
+- **Installments**: 1-12 for credit cards, 1 for PIX/bank billet
+- **Price**: Positive integer in cents
+- **Quantity**: Positive integer
+
+### Required vs Optional
+
+- **Required for all operations**: name, email, document
+- **Required for shipping**: address
+- **Required for contact**: phone
+- **Required for payments**: payment method and details
+- **Optional**: complement, metadata, deliveryAddress
+
+## Best Practices
+
+1. **Always validate data** before sending to the SDK
+2. **Use proper error handling** to catch and display validation errors
+3. **Sanitize user input** to prevent XSS attacks
+4. **Store sensitive data securely** (never log credit card numbers)
+5. **Handle rate limiting** gracefully with exponential backoff
+6. **Use metadata** to track order sources and campaigns
+7. **Implement proper logging** for debugging and monitoring
+8. **Test with real data** in development environment
+9. **Follow Brazilian data regulations** (LGPD compliance)
+10. **Use HTTPS** in production environments

package/INDEX.md

@@ -0,0 +1,123 @@
+# Easyflow JavaScript SDK - Documentation Hub
+
+Welcome to the Easyflow JavaScript SDK documentation hub! This is your central access point to all SDK resources.
+
+## 📚 Core Documentation
+
+### [📖 Complete SDK Guide](README.md)
+
+The main documentation file containing:
+
+- **Quick Start** guide and installation
+- **API Reference** for all methods
+- **Complete Examples** for all use cases
+- **Configuration** and development options
+- **Error Handling** with standardized codes
+- **Security Features** and best practices
+
+### [🔧 Data Structures Reference](DATA-STRUCTURES.md)
+
+Comprehensive guide to all data structures:
+
+- **TypeScript Interfaces** for all data types
+- **Field-by-field documentation** with validation rules
+- **Real-world examples** for each structure
+- **Error codes and messages** reference
+- **Best practices** for data handling
+
+### [🚀 Platform Integration Guide](PLATFORM-INTEGRATION.md)
+
+Complete guide for platform integration:
+
+- **`initializeForPlatform()`** method explanation
+- **Traditional vs Platform** initialization approaches
+- **Low-code/No-code** platform examples
+- **Automatic callbacks** and validation
+- **Performance considerations** and best practices
+
+## 🚀 Examples & Demos
+
+### [🐛 Development Mode Example](examples/development-mode-example.html)
+
+Interactive demo showcasing:
+
+- **Development mode** configuration
+- **Debug features** and logging
+- **Event system** (SDKReady, etc.)
+- **Real-time monitoring** and status
+
+## 📦 Installation & Distribution
+
+### NPM Package (Recommended for Production)
+
+```bash
+npm install @easyflow/javascript-sdk
+```
+
+**What's included:**
+
+- **Production-ready obfuscated code** - Same secure build as CDN
+- **TypeScript definitions** - Full IntelliSense and type safety
+- **Complete documentation** - README, INDEX, DATA-STRUCTURES, PLATFORM-INTEGRATION
+- **Version management** - Easy updates via package.json
+
+**Perfect for:**
+
+- Modern build tools (Webpack, Vite, Rollup)
+- TypeScript projects
+- Node.js applications
+- Offline development
+
+### CDN Scripts (Alternative)
+
+```html
+<!-- Cloudflare Pages (Primary) -->
+<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
+
+<!-- jsDelivr (Alternative) -->
+<script src="https://cdn.jsdelivr.net/npm/@easyflow/javascript-sdk@latest/dist/easyflow-sdk.min.js"></script>
+```
+
+**Perfect for:**
+
+- Quick HTML integration0
+- No build step required
+- Global availability via `window.easyflowSDK`
+- Simple prototyping
+
+### Security & Distribution Strategy
+
+**🔒 Both NPM and CDN contain identical obfuscated code:**
+
+- **Source code is obfuscated** and cannot be reverse-engineered
+- **Security features are identical** in both distributions
+- **Choose based on your workflow** - both are equally secure
+- **NPM provides better developer experience** with TypeScript support
+
+## 🔗 Quick Links
+
+- **[🌐 Official Website](https://www.easyflow.digital)**
+- **[📦 NPM Package](https://www.npmjs.com/package/@easyflow/javascript-sdk)**
+- **[🔧 CDN Scripts](https://easyflow-sdk.pages.dev)**
+- **[📧 Contact Support](mailto:contato@easyflow.digital)**
+
+## 🎯 Getting Started
+
+1. **Choose your installation method** (CDN recommended for production)
+2. **Read the [Quick Start guide](README.md#quick-start)** in the main README
+3. **Reference [DATA-STRUCTURES.md](DATA-STRUCTURES.md)** for detailed field information
+4. **Try the [development example](examples/development-mode-example.html)** for hands-on experience
+
+## 📋 What's New in v2.1.24
+
+- **Development Mode & Debug Features** - Automatic environment detection
+- **SDK Ready Event System** - Proper initialization handling
+- **Enhanced Error Handling** - 50+ standardized error codes
+- **Comprehensive Data Documentation** - Complete structure reference
+- **Interactive Examples** - Hands-on development experience
+
+---
+
+**Built with ❤️ by the Easyflow Team**
+
+_For questions and support, contact [contato@easyflow.digital](mailto:contato@easyflow.digital)_