npm package: @geovannev/evolution-whatsapp-sdk
Description: SDK oficial para Evolution API WhatsApp - Envie mensagens WhatsApp facilmente em qualquer aplicação JavaScript/TypeScript
Author: Evolution API
Latest version: 1.0.0

# Evolution API WhatsApp SDK

[![npm version](https://img.shields.io/npm/v/@geovannev/evolution-whatsapp-sdk.svg)](https://www.npmjs.com/package/@geovannev/evolution-whatsapp-sdk)
[![npm downloads](https://img.shields.io/npm/dm/@geovannev/evolution-whatsapp-sdk.svg)](https://www.npmjs.com/package/@geovannev/evolution-whatsapp-sdk)
[![license](https://img.shields.io/npm/l/@geovannev/evolution-whatsapp-sdk.svg)](https://github.com/geovannev/evolution-whatsapp-sdk/blob/main/LICENSE)

SDK oficial para integração com Evolution API WhatsApp. Envie mensagens WhatsApp facilmente em qualquer aplicação JavaScript/TypeScript.

## 🚀 Instalação

```bash
npm install @geovannev/evolution-whatsapp-sdk
```

## 📖 Uso Rápido

### Configuração Inicial

```javascript
const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'seu-tenant-id',
  apiKey: 'sua-api-key'
});
```

### Enviar Mensagem

```javascript
// Enviar mensagem simples
const message = await whatsapp.sendMessage({
  to: '5583998057011',
  message: 'Olá! Esta é uma mensagem de teste.'
});

console.log('Mensagem enviada:', message.id);
```

### Criar Sessão com QR Code

```javascript
// Criar nova sessão
const session = await whatsapp.createSession({
  name: 'Minha Sessão'
});

// Obter QR Code
const qrCode = await whatsapp.getQRCode(session.id);
console.log('QR Code:', qrCode); // Data URL base64
```

### Criar Sessão com Pairing Code

```javascript
// Criar sessão com pairing code
const session = await whatsapp.createSession({
  name: 'Minha Sessão',
  usePairingCode: true,
  phoneNumber: '5583998057011'
});

console.log('Código de pareamento:', session.pairingCode);
```

### Listar Sessões

```javascript
const sessions = await whatsapp.listSessions();

sessions.forEach(session => {
  console.log(`${session.name}: ${session.status}`);
});
```

### Verificar Status da Sessão

```javascript
const session = await whatsapp.getSession('session-id');

if (session.status === 'CONNECTED') {
  console.log('Sessão conectada!');
} else {
  console.log('Status:', session.status);
}
```

### Listar Mensagens

```javascript
const messages = await whatsapp.listMessages('session-id');

messages.forEach(msg => {
  console.log(`${msg.from}: ${msg.body}`);
});
```

### Deletar Sessão

```javascript
await whatsapp.deleteSession('session-id');
console.log('Sessão deletada');
```

## 🎯 Exemplos Completos

### Sistema de Agendamento

```javascript
const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

async function enviarLembrete(cliente) {
  try {
    await whatsapp.sendMessage({
      to: cliente.telefone,
      message: `Olá ${cliente.nome}! Lembrete: você tem consulta amanhã às ${cliente.horario}.`
    });
    console.log(`Lembrete enviado para ${cliente.nome}`);
  } catch (error) {
    console.error('Erro ao enviar lembrete:', error.message);
  }
}

// Enviar lembretes
const clientes = [
  { nome: 'João', telefone: '5583998057011', horario: '14:00' },
  { nome: 'Maria', telefone: '5583998057012', horario: '15:30' }
];

for (const cliente of clientes) {
  await enviarLembrete(cliente);
}
```

### Sistema de Prospecção

```javascript
const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

async function enviarProspeccao(leads) {
  for (const lead of leads) {
    try {
      await whatsapp.sendMessage({
        to: lead.telefone,
        message: `Olá! Temos uma oferta especial para você: ${lead.oferta}`
      });
      
      console.log(`Mensagem enviada para ${lead.nome}`);
      
      // Aguardar 2 segundos entre mensagens
      await new Promise(resolve => setTimeout(resolve, 2000));
    } catch (error) {
      console.error(`Erro ao enviar para ${lead.nome}:`, error.message);
    }
  }
}

const leads = [
  { nome: 'Cliente 1', telefone: '5583998057011', oferta: '50% de desconto' },
  { nome: 'Cliente 2', telefone: '5583998057012', oferta: 'Frete grátis' }
];

enviarProspeccao(leads);
```

### Integração com Express

```javascript
const express = require('express');
const { EvolutionAPI } = require('evolution-whatsapp-sdk');

const app = express();
app.use(express.json());

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

// Endpoint para enviar mensagem
app.post('/send-message', async (req, res) => {
  try {
    const { to, message } = req.body;
    
    const result = await whatsapp.sendMessage({ to, message });
    
    res.json({ success: true, messageId: result.id });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// Endpoint para criar sessão
app.post('/create-session', async (req, res) => {
  try {
    const { name } = req.body;
    
    const session = await whatsapp.createSession({ name });
    const qrCode = await whatsapp.getQRCode(session.id);
    
    res.json({ success: true, sessionId: session.id, qrCode });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(4000, () => {
  console.log('Servidor rodando na porta 4000');
});
```

## 📚 API Reference

### `new EvolutionAPI(config)`

Cria uma nova instância do SDK.

**Parâmetros:**
- `config.baseURL` (string): URL base da API
- `config.tenantId` (string): ID do tenant
- `config.apiKey` (string): Chave de API

### `sendMessage(options)`

Envia uma mensagem de texto.

**Parâmetros:**
- `options.to` (string): Número do destinatário (formato: 5583998057011)
- `options.message` (string): Texto da mensagem
- `options.sessionId` (string, opcional): ID da sessão específica

**Retorna:** `Promise<Message>`

### `createSession(options)`

Cria uma nova sessão WhatsApp.

**Parâmetros:**
- `options.name` (string): Nome da sessão
- `options.usePairingCode` (boolean, opcional): Usar pairing code
- `options.phoneNumber` (string, opcional): Número para pairing code

**Retorna:** `Promise<Session>`

### `listSessions()`

Lista todas as sessões.

**Retorna:** `Promise<Session[]>`

### `getSession(sessionId)`

Obtém uma sessão específica.

**Parâmetros:**
- `sessionId` (string): ID da sessão

**Retorna:** `Promise<Session>`

### `getQRCode(sessionId)`

Obtém o QR Code de uma sessão.

**Parâmetros:**
- `sessionId` (string): ID da sessão

**Retorna:** `Promise<string>` (Data URL base64)

### `deleteSession(sessionId)`

Deleta uma sessão.

**Parâmetros:**
- `sessionId` (string): ID da sessão

**Retorna:** `Promise<void>`

### `listMessages(sessionId)`

Lista mensagens de uma sessão.

**Parâmetros:**
- `sessionId` (string): ID da sessão

**Retorna:** `Promise<Message[]>`

## 🔧 TypeScript

O SDK inclui definições de tipos TypeScript:

```typescript
import { EvolutionAPI, SendMessageOptions, Session } from 'evolution-whatsapp-sdk';

const whatsapp = new EvolutionAPI({
  baseURL: 'http://localhost:3000',
  tenantId: 'meu-tenant',
  apiKey: 'minha-api-key'
});

const options: SendMessageOptions = {
  to: '5583998057011',
  message: 'Olá!'
};

const message = await whatsapp.sendMessage(options);
```

## 💡 Dicas Importantes

- Aguarde 1-2 segundos entre mensagens para evitar bloqueios
- Use variáveis de ambiente para armazenar credenciais
- Implemente tratamento de erros adequado
- Monitore o status das sessões regularmente

## 📝 Licença

MIT

## 🤝 Suporte

Para suporte, abra uma issue no GitHub ou entre em contato.

## 🔗 Links

- [NPM Package](https://www.npmjs.com/package/evolution-whatsapp-sdk)
- [GitHub Repository](https://github.com/evolution-api/whatsapp-sdk)
- [Documentation](https://github.com/evolution-api/whatsapp-sdk#readme)