acq-sdk

v1.2.1

Published

a year ago

SDK oficial para a API da ACQ

Downloads

0High
0Medium
0Low

ct02_

acq api sdk email render html image temporary-email mail websocket socket real-time notification

ACQ SDK

SDK oficial em Node.js para a API da ACQ. Oferece funcionalidades para renderização de HTML em imagens, gerenciamento de emails temporários e monitoramento em tempo real via WebSocket.

📦 Instalação

npm install acq-sdk

yarn add acq-sdk

pnpm add acq-sdk

🔑 Configuração

Cliente HTTP

import { AcqClient } from "acq-sdk";

const client = new AcqClient({
  apiKey: "sua-api-key-aqui",
  // Opcionais:
  baseUrl: "https://api.acq.lat", // URL base customizada
  timeout: 30000, // Timeout em milissegundos
});

Cliente WebSocket

import { AcqSocketClient, SocketEvents } from "acq-sdk";

const socketClient = new AcqSocketClient({
  apiKey: "sua-api-key-aqui",
  // Opcionais:
  email: "[email protected]", // Email para monitorar, se não informado, todos os emails serão monitorados.
  // email: ["[email protected]", "[email protected]"] para monitorar múltiplos emails
  baseUrl: "wss://ws.acq.lat", // URL base customizada
  timeout: 30000, // Timeout em milissegundos
});

📧 Gerenciamento de Emails

Listar emails

const emails = await client.mails.list();
console.log("Seus emails:", emails);
// Retorna: [{ email: '[email protected]', expiraEm: '2025-07-16T23:37:29.111Z' }]

Criar novo email

// Email com domínio padrão
const novoEmail = await client.mails.create();
console.log("Novo email:", novoEmail.mail);

// Email com domínio específico
const emailCustom = await client.mails.create({
  domain: "acq.lat",
});
console.log("Email customizado:", emailCustom.mail);

Verificar mensagens

const mensagens = await client.mails.getMessages({
  mail: "[email protected]",
});

console.log(`Email: ${mensagens.email}`);
console.log(`Total de mensagens: ${mensagens.total}`);
console.log("Mensagens:", mensagens.messages);

Deletar email

const resultado = await client.mails.delete("[email protected]");
console.log("Email deletado:", resultado.deleted_email);

Deletar mensagens

const resultado = await client.mails.deleteMessages("[email protected]");
console.log(`${resultado.deleted_count} mensagens deletadas`);

🔌 WebSocket - Monitoramento em Tempo Real

Conectar e ouvir eventos

import { AcqSocketClient, SocketEvents } from "acq-sdk";

const socketClient = new AcqSocketClient({
  apiKey: "sua-api-key-aqui",
  email: "[email protected]",
});

// Conectar ao WebSocket
await socketClient.connect();
console.log("Conectado ao WebSocket!");

// Ouvir novos emails
socketClient.on(SocketEvents.NEW, data => {
  console.log("Nova mensagem recebida:", data);
  // data contém informações da nova mensagem
});

// Ouvir eventos de conexão
socketClient.on(SocketEvents.CONNECT, () => {
  console.log("WebSocket conectado!");
});

// Ouvir eventos de desconexão
socketClient.on(SocketEvents.DISCONNECT, () => {
  console.log("WebSocket desconectado!");
});

Gerenciar conexão

// Conectar
await socketClient.connect();

// Desconectar quando necessário
await socketClient.disconnect();

Exemplo prático - Monitor de emails

import { AcqClient, AcqSocketClient, SocketEvents } from "acq-sdk";

async function monitorarEmail() {
  const client = new AcqClient({
    apiKey: "sua-api-key-aqui",
  });

  // Criar um novo email
  const novoEmail = await client.mails.create();
  console.log("Email criado:", novoEmail.mail);

  // Conectar ao WebSocket para monitorar
  const socketClient = new AcqSocketClient({
    apiKey: "sua-api-key-aqui",
    email: novoEmail.mail,
  });

  await socketClient.connect();

  // Ouvir novos emails
  socketClient.on(SocketEvents.NEW, mensagem => {
    console.log("Nova mensagem:", {
      from: mensagem.from,
      subject: mensagem.subject,
      body: mensagem.body,
    });
  });

  console.log("Monitorando emails em tempo real...");

  // Manter ativo por 5 minutos
  setTimeout(
    async () => {
      await socketClient.disconnect();
      console.log("Monitoramento finalizado");
    },
    5 * 60 * 1000
  );
}

monitorarEmail().catch(console.error);

🎨 Renderização de HTML

Renderizar HTML em imagem

import { writeFileSync } from "fs";

const html = `
  <!DOCTYPE html>
  <html>
    <head>
      <style>
        body {
          font-family: Arial, sans-serif;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          color: white;
          padding: 40px;
          text-align: center;
        }
        .card {
          background: rgba(255, 255, 255, 0.1);
          border-radius: 15px;
          padding: 30px;
          backdrop-filter: blur(10px);
        }
      </style>
    </head>
    <body>
      <div class="card">
        <h1>🚀 Minha Imagem</h1>
        <p>Gerada com ACQ SDK!</p>
      </div>
    </body>
  </html>
`;

const imagemBuffer = await client.render.htmlToImage({ html });

// Salvar como arquivo
writeFileSync("minha-imagem.png", imagemBuffer);

// Ou usar em uma aplicação web
// res.set('Content-Type', 'image/png');
// res.send(imagemBuffer);

🛡️ Tratamento de Erros

O SDK fornece tipos específicos de erro para diferentes situações:

import { AcqApiError, AcqValidationError, AcqConfigError } from "acq-sdk";

try {
  await client.mails.create();
} catch (error) {
  if (error instanceof AcqApiError) {
    console.error("Erro da API:", error.message);
    console.error("Código:", error.code);
    console.error("Status HTTP:", error.status);
  } else if (error instanceof AcqValidationError) {
    console.error("Erro de validação:", error.message);
  } else if (error instanceof AcqConfigError) {
    console.error("Erro de configuração:", error.message);
  }
}

Erros específicos do WebSocket

import { AcqSocketClient, SocketEvents } from "acq-sdk";

const socketClient = new AcqSocketClient({
  apiKey: "sua-api-key-aqui",
  email: "[email protected]",
});

try {
  await socketClient.connect();
} catch (error) {
  console.error("Erro ao conectar WebSocket:", error);
}

// Ouvir erros de conexão
socketClient.on("connect_error", error => {
  console.error("Erro de conexão:", error);
});

📚 Tipos e Interfaces

Tipos principais

import type {
  AcqClientConfig,
  AcqSocketConfig,
  EmailInfo,
  EmailMessage,
  MailboxResponse,
  CreateEmailResponse,
  DeleteEmailResponse,
  DeleteMessagesResponse,
  RenderOptions,
  CreateEmailOptions,
  GetMessagesOptions,
  AcqSocket,
  SocketEvents,
} from "acq-sdk";

// Configuração do cliente HTTP
const config: AcqClientConfig = {
  apiKey: "sua-chave",
  baseUrl: "https://api.acq.lat", // opcional
  timeout: 30000, // opcional
};

// Configuração do cliente WebSocket
const socketConfig: AcqSocketConfig = {
  apiKey: "sua-chave",
  email: "[email protected]",
  baseUrl: "wss://ws.acq.lat", // opcional
  timeout: 30000, // opcional
};

// Eventos disponíveis
const eventos = {
  CONNECT: SocketEvents.CONNECT,
  DISCONNECT: SocketEvents.DISCONNECT,
  NEW: SocketEvents.NEW,
};

📄 Licença

MIT © ACQ Team

🆘 Suporte

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Documentação: docs.acq.lat

Feito com ❤️ pela equipe ACQ