npm package: @silapay/transparent-checkout
Description: A Vue.js library for transparent checkout with multiple payment methods
Author: SilaPay
Latest version: 1.0.0

# @silapay/transparent-checkout

[![npm version](https://badge.fury.io/js/@silapay%2Ftransparent-checkout.svg)](https://badge.fury.io/js/@silapay%2Ftransparent-checkout)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Uma biblioteca Vue.js moderna para checkout transparente com múltiplos métodos de pagamento, incluindo **PIX**, **Cartão de Crédito** e **Boleto Bancário**.

## ✨ Características

- 🚀 **Componente Vue 3** pronto para uso
- 💳 **Múltiplos métodos de pagamento** (PIX, Cartão, Boleto)
- 📱 **Totalmente responsivo** e otimizado para mobile
- 🎨 **Personalizável** com cores e logo da sua marca
- 🔒 **Seguro** com validações integradas
- 📦 **TypeScript** com tipagem completa
- 🌐 **Fácil integração** em HTML puro ou Vue.js

## 🚀 Instalação

```bash
# npm
npm install @silapay/transparent-checkout

# yarn
yarn add @silapay/transparent-checkout

# pnpm
pnpm add @silapay/transparent-checkout
```

## 📦 Importação dos Estilos

⚠️ **Importante**: A biblioteca inclui estilos CSS que **devem** ser importados:

```javascript
import '@silapay/transparent-checkout/style.css'
```

## ⚡ Início Rápido

1. **Instale a biblioteca**:

   ```bash
   npm install @silapay/transparent-checkout
   ```

2. **Use diretamente no HTML** (via CDN):

   ```html
   <script src="https://unpkg.com/@silapay/transparent-checkout@latest/dist/index.umd.js"></script>
   <link rel="stylesheet" href="https://unpkg.com/@silapay/transparent-checkout@latest/dist/style.css">
   ```

3. **Configure seu checkout**:

   ```javascript
   const config = {
     cart: {
       id: 'cart-123',
       amountTotal: 99.99,
       currency: 'BRL',
       items: [{ id: '1', name: 'Produto', price: 99.99, quantity: 1 }],
       paymentMethods: ['pix', 'creditCard', 'billet']
     },
     backendUrl: 'https://api.seubackend.com'
   }
   ```

4. **Veja os exemplos completos** na pasta [`example/`](./example/) deste repositório!

## 🎯 Guia de Uso

### 🔧 Integração em HTML Puro (Recomendado para iniciantes)

```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Checkout SilaPay</title>
    <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
    <script src="https://unpkg.com/@silapay/transparent-checkout@latest/dist/index.umd.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@silapay/transparent-checkout@latest/dist/style.css">
</head>
<body>
    <div id="checkout"></div>

    <script>
        const checkoutConfig = {
            cart: {
                id: 'cart-123',
                amountTotal: 99.99,
                currency: 'BRL',
                items: [{
                    id: '1',
                    name: 'Produto Exemplo',
                    price: 99.99,
                    quantity: 1,
                    description: 'Descrição do produto'
                }],
                paymentMethods: ['pix', 'creditCard', 'billet']
            },
            backendUrl: 'https://api.seubackend.com',
            onPaymentSuccess: (data) => {
                console.log('Pagamento aprovado:', data)
                alert('Pagamento realizado com sucesso!')
            },
            onPaymentError: (error) => {
                console.error('Erro no pagamento:', error)
                alert('Erro no pagamento: ' + error.message)
            }
        }

        SilaPayTransparentCheckout.createTransparentCheckout('#checkout', checkoutConfig)
    </script>
</body>
</html>
```

### 🔧 Como Plugin Vue.js

```javascript
import { createApp } from 'vue'
import TransparentCheckout from '@silapay/transparent-checkout'
import '@silapay/transparent-checkout/style.css'

const app = createApp(App)
app.use(TransparentCheckout)
```

### 🔧 Importação Direta do Componente

```vue
<template>
  <TransparentCheckout :config="checkoutConfig" />
</template>

<script setup>
import { TransparentCheckout } from '@silapay/transparent-checkout'
import '@silapay/transparent-checkout/style.css'

const checkoutConfig = {
  cart: {
    id: 'cart-123',
    amountTotal: 99.99,
    currency: 'BRL',
    items: [
      {
        id: '1',
        name: 'Produto Exemplo',
        price: 99.99,
        quantity: 1,
        description: 'Descrição do produto'
      }
    ],
    paymentMethods: ['pix', 'creditCard', 'billet']
  },
  backendUrl: 'https://api.seubackend.com',
  onPaymentSuccess: (data) => {
    console.log('Pagamento realizado com sucesso:', data)
  },
  onPaymentError: (error) => {
    console.error('Erro no pagamento:', error)
  }
}
</script>
```

### 🔧 Factory Function (Integração Dinâmica)

```javascript
import { createTransparentCheckout } from '@silapay/transparent-checkout'

// Cria e monta o checkout em um elemento específico
const checkout = await createTransparentCheckout('#checkout-container', {
  cart: {
    id: 'cart-123',
    amountTotal: 99.99,
    currency: 'BRL',
    items: [/* seus produtos */],
    paymentMethods: ['pix', 'creditCard', 'billet']
  },
  backendUrl: 'https://api.seubackend.com'
})
```

## ⚙️ Configuração

### CheckoutConfig

```typescript
interface CheckoutConfig {
  cart: Cart
  customization?: CheckoutCustomization
  maxInstallments?: number
  backendUrl: string
  onPaymentSuccess?: (data: PaymentResponse) => void
  onPaymentError?: (error: any) => void
  isEmbedded?: boolean
  devMode?: {
    apiKey: string
    secretKey: string
    postbackUrl: string
    apiEndpoint?: string
    proxyUrl?: string
  }
}
```

### Cart

```typescript
interface Cart {
  id: string
  amountTotal: number
  shippingCost?: number
  tax?: Tax
  discount?: number
  currency: string
  items: CartItem[]
  paymentMethods: string[]
}

interface CartItem {
  id: string
  name: string
  price: number
  quantity: number
  description?: string
  image?: string
}
```

### Customização

```typescript
interface CheckoutCustomization {
  isDarkMode?: boolean
  identityColorLight?: string
  identityColorDark?: string
  logoUrl?: string
  identityUrl?: string
  isTimerActive?: boolean
  acceptPayments?: PaymentMethod[]
}
```

## 🎨 Personalização

### Cores e Tema

```javascript
const customization = {
  isDarkMode: false,
  identityColorLight: '#007bff',
  identityColorDark: '#0056b3',
  logoUrl: 'https://example.com/logo.png',
  identityUrl: 'https://example.com'
}
```

### Métodos de Pagamento

```javascript
const acceptPayments = [
  { id: 'pix', label: 'PIX', active: true },
  { id: 'creditCard', label: 'Cartão de Crédito', active: true },
  { id: 'billet', label: 'Boleto', active: false }
]
```

## 🔐 Segurança

### Configuração de Produção (Recomendada)

Para uso em produção, configure apenas a URL do seu backend:

```javascript
const config = {
  backendUrl: 'https://api.seubackend.com',
  cart: {
    // dados do carrinho
  }
}
```

### Modo de Desenvolvimento (Apenas para Testes)

⚠️ **ATENÇÃO**: Nunca use em produção!

```javascript
const config = {
  backendUrl: 'https://api.seubackend.com',
  devMode: {
    apiKey: 'sua-api-key',
    secretKey: 'sua-secret-key',
    postbackUrl: 'https://seu-webhook.com/postback',
    proxyUrl: 'http://localhost:3001' // para contornar CORS
  },
  cart: {
    // dados do carrinho
  }
}
```

## 📱 Responsividade

O componente é totalmente responsivo e se adapta automaticamente a diferentes tamanhos de tela:

- **Desktop**: Layout em duas colunas (produtos + formulários)
- **Mobile**: Layout empilhado com navegação por etapas
- **Embedded**: Modo otimizado para iframe

## 🛠 Métodos de Pagamento Suportados

- **PIX**: Pagamento instantâneo via QR Code
- **Cartão de Crédito**: Visa, Mastercard, Elo, etc.
- **Boleto Bancário**: Tradicional boleto brasileiro

## 📋 Callbacks

### onPaymentSuccess

Chamado quando o pagamento é processado com sucesso:

```javascript
onPaymentSuccess: (data) => {
  console.log('Transaction ID:', data.txId)
  console.log('Payment Method:', data.method)
  console.log('Amount:', data.amount)

  // Redirecionar usuário ou mostrar confirmação
  window.location.href = '/success'
}
```

### onPaymentError

Chamado quando ocorre erro no pagamento:

```javascript
onPaymentError: (error) => {
  console.error('Erro:', error.message)

  // Mostrar mensagem de erro ao usuário
  alert('Erro no pagamento: ' + error.message)
}
```

## 🔧 Composables

A biblioteca exporta composables úteis para validação e pagamento:

```javascript
import { useValidation, usePayment } from '@silapay/transparent-checkout'

// Validação de documentos
const { validateCPF, validateCNPJ, validateEmail } = useValidation()

// Processamento de pagamentos
const { processPayment, isLoading } = usePayment()
```

## 🌐 Compatibilidade

- **Vue**: 3.0+
- **TypeScript**: Suporte completo
- **Navegadores**: Modernos (ES2015+)
- **Node.js**: 14+

## 📄 Licença

MIT

## 🤝 Contribuição

Contribuições são bem-vindas! Consulte o repositório no GitHub para mais informações.

## � Exemplos Práticos

Na pasta [`example/`](./example/) você encontra exemplos completos:

- **🚀 Exemplo Simples** (`simple.html`) - Integração básica em 5 minutos
- **🎯 Exemplo Completo** (`index.html`) - Demo interativa com todas as funcionalidades
- **📖 Documentação** (`README.md`) - Guia detalhado dos exemplos

```bash
# Para testar os exemplos localmente
git clone https://github.com/silabank/sdk-npm.git
cd sdk-npm/example
npx serve .  # ou abra index.html diretamente no navegador
```

## �📞 Suporte

Para dúvidas ou suporte, entre em contato:

- 📧 Email: suporte@silapay.com
- 🐛 Issues: [GitHub Issues](https://github.com/silabank/sdk-npm/issues)
- 💬 Discussões: [GitHub Discussions](https://github.com/silabank/sdk-npm/discussions)