Evolution SDK

SDK TypeScript oficial para integrar aplicações com a Evolution GO.

O pacote @quejiin/evolution-sdk foi criado para facilitar o consumo da API com uma interface simples, autenticação centralizada e acesso aos principais recursos da plataforma sem precisar montar requests manualmente.

Compatibilidade: este SDK foi atualizado em relação ao OpenAPI em docs/swagger.json do repositório e corresponde à API do Evolution GO v0.7.0 (rotas novas como resultados de enquete, modelo de licença/core no servidor, etc.). Use a mesma versão major/minor do servidor ou verifique o CHANGELOG.md na raiz do projeto Go se misturar versões.

Instalação

npm install @quejiin/evolution-sdk

Requisitos

• Node.js 18+
• Uma instância da Evolution GO acessível por HTTP ou HTTPS
• Uma chave de API válida no header apikey

Configuração

EVO_BASE_URL=http://localhost:4000
EVO_API_KEY=sua-chave

PowerShell:

$env:EVO_BASE_URL="http://localhost:4000"
$env:EVO_API_KEY="sua-chave"

Uso rápido

import { EvolutionSdk, createEvolutionClient } from "@quejiin/evolution-sdk";

const baseUrl = process.env.EVO_BASE_URL!;
const apiKey = process.env.EVO_API_KEY!;

const api = createEvolutionClient({ baseUrl, apiKey });
const raw = await api.instance.getAllInstances();

const sdk = new EvolutionSdk({ baseUrl, apiKey });
const instances = await sdk.listInstances();

O que o pacote oferece

• Cliente principal para acessar grupos da API como instance, send, message, group, community, label, newsletter, polls e user
• Camada simplificada com métodos de alto nível para fluxos comuns
• Requisições autenticadas automaticamente com apikey
• Tipos úteis exportados junto com o cliente

Métodos de alto nível disponíveis hoje

• listInstances(params?)
• createInstance(payload, params?)
• sendText(payload, params?)
• getPollResults(pollMessageId, params?) — resultados de votação (GET /polls/{pollMessageId}/results), v0.7.0+

Documentação narrativa no repositório do servidor (mensagens interativas, botões, listas, carrossel): docs/wiki/guias-api/api-interactive.md.

Exemplo:

import { EvolutionSdk } from "@quejiin/evolution-sdk";

const sdk = new EvolutionSdk({
  baseUrl: process.env.EVO_BASE_URL!,
  apiKey: process.env.EVO_API_KEY!,
});

await sdk.sendText({
  number: "5511999999999",
  text: "Olá! Sua integração está funcionando.",
});

Respostas da API

Os métodos retornam Promise<HttpResponse<D, E>>.

Na prática:

• response.status contém o status HTTP
• response.data contém o payload de sucesso
• response.error contém o payload de erro, quando houver

Eventos

O pacote não implementa um event emitter local em memória.

Ele é usado para configurar a Evolution GO e consumir a API HTTP. A entrega de eventos acontece pelos canais do servidor, como:

• Webhook
• WebSocket
• RabbitMQ
• NATS

Exemplo de configuração de subscribe:

import { createEvolutionClient } from "@quejiin/evolution-sdk";

const api = createEvolutionClient({
  baseUrl: process.env.EVO_BASE_URL!,
  apiKey: process.env.EVO_API_KEY!,
});

await api.instance.connectCreate({
  webhookUrl: "https://seu-dominio.com/webhook",
  subscribe: ["MESSAGE", "CALL", "CONNECTION"],
});

Quando usar este pacote

Use este SDK se você precisa:

• Integrar aplicações Node.js ou TypeScript com Evolution GO
• Reduzir código manual de integração HTTP
• Configurar entrega de eventos pela API
• Trabalhar com uma interface mais previsível para integração

Limites atuais

• Nem todas as respostas estão rigidamente tipadas
• A camada simplificada ainda cobre apenas os fluxos mais essenciais
• Eventos não são consumidos diretamente pelo pacote em memória