@areumtecnologia/unitychat-client-api

Biblioteca client oficial em Node.js para integração com a API do UnityChat.

Esta biblioteca facilita a autenticação, gerenciamento de sessões do WhatsApp, envio de mensagens (incluindo mensagens estruturadas/customizadas e tipos de dados flexíveis), envio de arquivos (através de Streams, Buffers, caminhos locais ou strings Base64), além de fornecer um middleware integrado para Express e um gerenciador de sessões em memória.

Para garantir robustez e evitar erros de digitação pelo desenvolvedor, a biblioteca fornece Enumeradores Estáticos (tipos estáticos congelados) para todas as opções de configuração e tipos de dados de strings repetitivas da API.

Instalação

Instale a biblioteca em seu projeto utilizando o npm ou yarn:

npm install @areumtecnologia/unitychat-client-api

Importação

const { 
    UnityChatService, 
    UnityChatSession, 
    UnityChatSessionsManager,
    DisconnectAction,
    QRCodeFormat,
    MessageType,
    FileType,
    MessageMode,
    Platform
} = require('@areumtecnologia/unitychat-client-api');

Enumeradores Estáticos (Evitando Strings Mágicas)

Utilize estes enumeradores para evitar o uso de strings brutas (strings mágicas) que podem ser escritas incorretamente. Todos os objetos são congelados (Object.freeze) para evitar modificações acidentais:

• Platform: Plataformas suportadas para inicializar sessões de WhatsApp.
  • Platform.ANDROID ('android')
  • Platform.CHROME ('chrome')
• DisconnectAction: Tipos de ação ao desconectar uma sessão.
  • DisconnectAction.LOGOUT ('logout') - Faz logout completo da conta do WhatsApp da sessão atual.
  • DisconnectAction.DISCONNECT ('disconnect') - Desconecta a sessão temporariamente no serviço sem remover a credencial.
• QRCodeFormat: Opções de retorno do QR Code.
  • QRCodeFormat.RAW (true) - Retorna os dados em string limpa.
  • QRCodeFormat.RENDER ('render') - Retorna os dados prontos para renderização em tela.
  • QRCodeFormat.NONE (false) - Desativa a geração de QR Code.
• MessageType: Tipos de mensagens a serem enviadas por sendMessage.
  • MessageType.TEXT ('text')
  • MessageType.LINK ('link')
  • MessageType.LOCATION ('location')
  • MessageType.RAW ('raw')
• FileType: Tipos de arquivos para envio de mídias por sendFiles.
  • FileType.FILES ('files')
  • FileType.IMAGE ('image')
  • FileType.VIDEO ('video')
  • FileType.AUDIO ('audio')
• MessageMode: Filtros de tipos de chats para buscas de mensagens.
  • MessageMode.CHAT ('chat')
  • MessageMode.GROUPS ('groups')

Guia Rápido de Uso

1. Autenticação e Status do Serviço (UnityChatService)

O UnityChatService é responsável por autenticar suas credenciais (API Key) e obter o token temporário necessário para interagir com as sessões do WhatsApp. Ele também gerencia o status geral dos serviços e sessões da conta.

// O segundo parâmetro (apiVersion) é opcional e tem como padrão 1
const unityChatService = new UnityChatService('SUA_API_KEY', 1);

async function iniciar() {
    // 1. Autenticar para obter o token de acesso
    const authData = await unityChatService.authenticate();
    if (!authData) {
        console.error('Falha na autenticação. Verifique sua API Key.');
        return;
    }
    console.log('Autenticado com sucesso! Token:', unityChatService.token);

    // 2. Verificar o status dos serviços do UnityChat
    const status = await unityChatService.getServicesStatus();
    console.log('Status do serviço:', status);

    // 3. Obter a lista de todas as sessões ativas da conta
    const sessions = await unityChatService.getSessions();
    console.log('Sessões ativas:', sessions);

    // 4. Revogar o token quando não for mais necessário
    // await unityChatService.revoke();
}

iniciar();

Middleware para Express (merger)

Se você estiver usando Express, pode usar o método .merger() como um middleware para injetar automaticamente os dados de autenticação nas requisições:

const express = require('express');
const app = express();

app.use(unityChatService.merger());

app.get('/minha-rota', (req, res) => {
    // Os dados autenticados estarão disponíveis em req.services.unityChatService.data
    const authData = req.services.unityChatService.data;
    res.json({ status: 'OK', authData });
});

2. Gerenciamento de Sessões do WhatsApp (UnityChatSession)

Uma vez autenticado, você pode criar instâncias de UnityChatSession usando o token gerado para interagir com instâncias individuais do WhatsApp.

// O terceiro parâmetro (apiVersion) é opcional e tem como padrão 2
const session = new UnityChatSession(unityChatService.token, 'nome_da_sessao', 2);

// Opcional: callback para capturar erros de requisições da sessão
session.onError = (error) => {
    console.error('Erro na sessão:', error.message || error);
};

Conectar uma Sessão

Inicia ou conecta a sessão do WhatsApp. Você pode passar opções de configuração adicionais.

async function conectarSessao() {
    const response = await session.connect({
        platform: Platform.ANDROID, // Usando Platform enum em vez de 'android'
        blockIncomingCalls: true // Opcional (bloquear chamadas recebidas no WhatsApp)
    });
    console.log('Conexão iniciada:', response);
}

Desconectar ou Deslogar Sessão

// Logout da sessão (faz logout no WhatsApp da sessão atual)
await session.disconnect(DisconnectAction.LOGOUT);

// Desconexão temporária (apenas desconecta o serviço sem deslogar o WhatsApp)
await session.disconnect(DisconnectAction.DISCONNECT);

Obter Status e QR Code

// Verificar status atual do serviço da sessão
const status = await session.getStatus();
console.log('Status da sessão:', status);

// Obter o QR Code para pareamento
const qrData = await session.getQRcode(QRCodeFormat.RENDER);
console.log('QR Code:', qrData);

3. Envio de Mensagens e Arquivos

Enviar Mensagens (Texto, Links, Localização ou Raw/Custom)

// 1. Mensagem de Texto Simples
await session.sendMessage({
    to: '5591999999999', // Número com DDI + DDD + Telefone
    type: MessageType.TEXT,
    body: 'Olá! Esta é uma mensagem de teste.'
});

// 2. Link com pré-visualização
await session.sendMessage({
    to: '5591999999999',
    type: MessageType.LINK,
    title: 'Áreum Tecnologia',
    subtitle: 'Visite nosso site',
    url: 'https://unitychat.areum.com.br',
    body: 'Opcional: texto que acompanha o link'
});

// 3. Localização geográfica
await session.sendMessage({
    to: '5591999999999',
    type: MessageType.LOCATION,
    title: 'Nossa Localização',
    lat: -1.455833,
    long: -48.503889
});

// 4. Mensagem customizada/estruturada (Type 'raw')
// Útil para enviar botões interativos, templates complexos ou estruturas específicas da API
await session.sendMessage({
    to: '5591999999999',
    type: MessageType.RAW,
    body: {
        title: '📣 Lembrete de Pagamento',
        text: 'Olá!\n\nSua fatura com vencimento está disponível para pagamento!',
        footer: 'Efetue o pagamento de sua mensalidade usando o link copia e cola abaixo:',
        interactiveButtons: [
            // Definição dos botões interativos suportados pela API
        ]
    }
});

Enviar Arquivos (Imagens, Vídeos, PDFs, etc.)

O método sendFiles suporta o envio de múltiplos arquivos a partir de caminhos locais, Buffers, Streams ou strings Base64 de forma transparente:

// Enviar arquivo a partir de um caminho no sistema de arquivos local
await session.sendFiles({
    to: '5591999999999',
    type: FileType.FILES,
    caption: 'Segue o relatório em anexo',
    files: [
        {
            filename: 'relatorio.pdf',
            path: './caminho/para/o/relatorio.pdf'
        }
    ]
});

// Enviar arquivo a partir de uma String Base64
await session.sendFiles({
    to: '5591999999999',
    type: FileType.IMAGE,
    caption: 'Foto de perfil',
    files: [
        {
            filename: 'imagem.png',
            base64: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
        }
    ]
});

Referência Completa da API

Esta seção descreve exaustivamente todas as classes, suas propriedades, construtores e métodos públicos disponíveis na biblioteca.

1. Classe UnityChatService

Classe principal responsável pela autenticação geral da conta, controle de tokens globais de acesso e verificação do status dos serviços.

Construtor

• new UnityChatService(apiKey, apiVersion = 1)
  • apiKey (string, Obrigatório): Chave de acesso fornecida pelo UnityChat.
  • apiVersion (number, Opcional): Versão da API global de autenticação (padrão: 1).

Propriedades Públicas

• apiKey (string): A chave de API fornecida.
• apiVersion (number): A versão de API em uso.
• token (string | null): O token JWT temporário gerado e gerenciado após a autenticação bem-sucedida. Inicia como null.
• sessions (Array): Array de sessões (inicialmente vazio).
• urls (Object): Lista de endpoints mapeados da API correspondentes à versão selecionada.

Métodos Públicos

async authenticate()

Autentica as credenciais na API do UnityChat para gerar e guardar o token JWT temporário.

• Retorno: Promise<Object | null>
  • Retorna os dados brutos da autenticação (que contém o campo token) se for bem-sucedido.
  • Atualiza a propriedade pública this.token automaticamente.
  • Retorna null e exibe logs de erro em caso de falha de conexão ou credencial inválida.

async revoke()

Invalida/revoga o token JWT temporário ativo no momento.

• Retorno: Promise<Object | null>
  • Retorna a confirmação da revogação pela API ou null se houver falha.
  • Limpa a propriedade pública this.token definindo-a como null.

async getServicesStatus()

Verifica o status atual e funcionamento do serviço global do UnityChat.

• Retorno: Promise<Object | null>
  • Retorna os dados de status do sistema ou null se houver erro.

async getSessions()

Retorna a lista de todas as sessões ativas associadas à conta.

• Retorno: Promise<Object | null>
  • Retorna um objeto com a relação das sessões do WhatsApp do usuário ou null em caso de erro.

merger()

Gera um middleware padrão para o framework Express.

• Retorno: Function - Função de middleware do Express (req, res, next) que executa authenticate() de forma assíncrona antes de chamar a próxima etapa da requisição.
  • Injeta o resultado da autenticação em req.services.unityChatService.data.
  • Em caso de erro na autenticação, o middleware define req.services.unityChatService.data como null e prossegue com a execução normalmente.

2. Classe UnityChatSession

Representa uma sessão ativa do WhatsApp. É utilizada para enviar mensagens, arquivos e realizar pesquisas de dados na sessão vinculada.

Construtor

• new UnityChatSession(token, sessionName, apiVersion = 2)
  • token (string, Obrigatório): O token JWT de acesso gerado por UnityChatService.authenticate().
  • sessionName (string, Obrigatório): Identificador único da sessão (geralmente o número do WhatsApp com DDI e DDD).
  • apiVersion (number, Opcional): Versão da API utilizada para as operações da sessão (padrão: 2).

Propriedades Públicas

• token (string): O token JWT de autenticação atual.
• apiVersion (number): A versão da API da sessão.
• sessionName (string): O nome identificador da sessão.
• urls (Object): Os endpoints de comunicação para as operações de WhatsApp.
• onError (Function | undefined): Callback de erro opcional. Se definido como uma função, será acionado passando o objeto de exceção capturado em falhas HTTP.

Métodos Públicos

async connect(options = {})

Dispara o processo de conexão para iniciar a sessão do WhatsApp.

• Parâmetros:
  • options (Object, Opcional):
    • platform (Platform | string): Plataforma que a sessão utilizará (Platform.ANDROID ou Platform.CHROME).
    • blockIncomingCalls (boolean): Habilita o bloqueio automático de chamadas de voz e vídeo recebidas no WhatsApp da sessão.
• Retorno: Promise<Object>
  • Retorna os dados da conexão gerados pela API, ou a exceção lançada se houver erro (acionando onError se configurado).

async disconnect(action = 'logout')

Desconecta ou remove a sessão atual de acordo com a ação selecionada.

• Parâmetros:
  • action (DisconnectAction | string, Opcional): O tipo da desconexão (DisconnectAction.LOGOUT ou DisconnectAction.DISCONNECT). Padrão: 'logout'.
• Retorno: Promise<Object>
  • Retorna a confirmação da operação pela API ou a exceção lançada em caso de falha.

async getStatus()

Obtém informações e status atualizado do WhatsApp (conectado, aguardando QR Code, etc.) para esta sessão.

• Retorno: Promise<Object>
  • Retorna o status detalhado da sessão pela API ou a exceção de erro.

async getQRcode(qrCode = true)

Gera/recupera o código QR necessário para vincular o WhatsApp à sessão criada.

• Parâmetros:
  • qrCode (QRCodeFormat | boolean | string, Opcional): Formato do QR code a ser retornado.
    • QRCodeFormat.RAW (true) - String bruta.
    • QRCodeFormat.RENDER ('render') - Retorna pronto para exibição visual.
    • QRCodeFormat.NONE (false) - Desativa geração.
• Retorno: Promise<Object>
  • Estrutura contendo a string ou renderização do código QR ou a exceção de erro.

async sendMessage(message = { type: 'text' })

Envia mensagens de diversos tipos para um contato.

• Parâmetros:
  • message (Object, Obrigatório): Objeto contendo os dados da mensagem.
    • to (string, Obrigatório): Destinatário (DDI + DDD + Número, ex: '5591999999999').
    • type (MessageType | string, Opcional): O tipo da mensagem. Padrão: MessageType.TEXT.
    • body (string | Object): Conteúdo de texto da mensagem. Se o tipo for MessageType.RAW, aceita um objeto contendo a estrutura customizada da mensagem a ser enviada.
    • title (string, Opcional): Título (usado em mensagens de link e localização).
    • subtitle (string, Opcional): Subtítulo da mensagem (usado em mensagens de link).
    • url (string, Opcional): URL do link (usado em mensagens de link).
    • lat (number, Opcional): Coordenada de latitude (usada em localização).
    • long (number, Opcional): Coordenada de longitude (usada em localização).
    • buttons (Array, Opcional): Array de botões interativos suportados pela API.
• Retorno: Promise<Object>
  • Dados da mensagem enviada ou { error: exc } caso ocorra uma falha de envio.
  • Nota: Este método não joga códigos de erro HTTP (4xx/5xx) no catch; ele intercepta e retorna as respostas de erro da API diretamente.

async sendFiles(message = { type: 'files' })

Envia um ou múltiplos arquivos para um destinatário. Suporta automaticamente caminhos locais, Buffers, Streams ou Strings Base64.

• Parâmetros:
  • message (Object, Obrigatório):
    • to (string, Obrigatório): Destinatário (DDI + DDD + Número).
    • type (FileType | string, Opcional): Tipo do arquivo (ex: FileType.FILES, FileType.IMAGE, etc.). Padrão: 'files'.
    • caption (string, Opcional): Texto de legenda da mensagem.
    • files (Array<Object>, Obrigatório): Array contendo os objetos de mídia para envio. Cada objeto do array deve possuir opcionalmente apenas um dos seguintes formatos de dados:
      • filename (string, Opcional): O nome a ser atribuído ao arquivo enviado.
      • path (string): Caminho relativo ou absoluto do arquivo no sistema de arquivos local.
      • base64 (string): String codificada em Base64 contendo os dados do arquivo.
      • stream (Readable): Instância de Stream de leitura contendo o arquivo.
      • buffer (Buffer): Instância de Buffer contendo os bytes crus do arquivo.
• Retorno: Promise<Object>
  • Retorna a resposta de sucesso de envio de arquivos da API ou lança uma exceção.

async getMessages(options = {})

Consulta o histórico ou busca mensagens recebidas/enviadas na sessão atual.

• Parâmetros:
  • options (Object, Opcional):
    • from (string, Opcional): Número de telefone para filtrar mensagens de uma conversa específica.
    • mode (MessageMode | string, Opcional): Filtro de busca (MessageMode.CHAT ou MessageMode.GROUPS).
• Retorno: Promise<Object | undefined>
  • Retorna a lista de mensagens correspondentes ou undefined em caso de erro.

async getConversations(options = {})

Lista os chats e conversas ativas da sessão atual.

• Parâmetros:
  • options (Object, Opcional):
    • from (string, Opcional): Número de telefone do contato para obter detalhes de uma conversa específica.
• Retorno: Promise<Object | undefined>
  • Lista das conversas retornada pelo endpoint ou undefined em caso de erro.

3. Classe UnityChatSessionsManager

Utilitário em memória para ajudar sistemas multitenant ou aplicações a gerenciarem várias instâncias de UnityChatSession simultaneamente.

Construtor

• new UnityChatSessionsManager()

Propriedades Públicas

• sessions (Object): Dicionário contendo as sessões registradas onde a chave é o sessionName.

Métodos Públicos

add(unityChatSession)

Registra uma nova sessão de WhatsApp no gerenciador.

• unityChatSession (UnityChatSession, Obrigatório): Instância de sessão a ser registrada.

get(sessionName)

Recupera uma instância de sessão registrada a partir do seu nome identificador.

• sessionName (string, Obrigatório): Nome único da sessão.
• Retorno: UnityChatSession | undefined

getAll()

Retorna o dicionário completo com todas as sessões registradas na memória.

• Retorno: Object - Relação de sessões estruturadas no formato { [sessionName]: UnityChatSession }.

remove(sessionName)

Remove o registro de uma sessão do gerenciador pelo seu identificador.

• sessionName (string, Obrigatório): Nome da sessão a ser excluída.

Desenvolvimento e Testes

Se desejar contribuir ou executar os testes locais do projeto:

1. Clone o repositório.
2. Crie um arquivo .env na raiz do projeto com sua API Key de testes:

   UNITYCHAT_API_KEY=sua_api_key_aqui

3. Instale as dependências locais:

   npm install

4. Execute os testes automatizados da biblioteca:

   # Executa os testes de integridade e importações locais das classes e enums
   node tests/test-import.js
   
   # Executa os testes de integração reais com a API usando a chave informada no .env
   npm test

Licença

Distribuído sob a licença ISC. Veja o arquivo package.json para mais detalhes.