acq-sdk

ACQ SDK

npm version TypeScript License: MIT

SDK oficial em Node.js para a Mail & Render API da ACQ. Oferece funcionalidades para renderização de HTML em imagens e gerenciamento de emails temporários.

🚀 Características

  • ✅ TypeScript nativo - Tipagem completa e suporte total ao IntelliSense
  • 🎨 Renderização HTML - Converta HTML em imagens PNG de alta qualidade
  • 📧 Emails temporários - Crie, gerencie e monitore emails temporários
  • 🛡️ Tratamento de erros - Sistema robusto de tratamento de erros
  • 📦 Leve e rápido - Apenas uma dependência (axios)
  • 🔧 Configurável - Timeouts, URLs base e mais opções
  • ✨ Fácil de usar - API intuitiva e bem documentada

📦 Instalação

npm install acq-sdk

ou

yarn add acq-sdk

ou

pnpm add acq-sdk

🔑 Configuração

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
});

📧 Gerenciamento de Emails

Listar emails

const emails = await client.mails.list();
console.log("Seus emails:", emails);
// Retorna: [{ email: 'test@acq.lat', 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: "seu-email@acq.lat",
});

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@acq.lat");
console.log("Email deletado:", resultado.deleted_email);

Deletar mensagens

const resultado = await client.mails.deleteMessages("email@acq.lat");
console.log(`${resultado.deleted_count} mensagens deletadas`);

🎨 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);
  }
}

📝 Exemplos Completos

Aplicação Express.js

import express from "express";
import { AcqClient } from "acq-sdk";

const app = express();
const client = new AcqClient({ apiKey: process.env.ACQ_API_KEY! });

app.use(express.json());

// Endpoint para gerar imagem
app.post("/gerar-imagem", async (req, res) => {
  try {
    const { html } = req.body;
    const imagem = await client.render.htmlToImage({ html });

    res.set("Content-Type", "image/png");
    res.send(imagem);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

// Endpoint para criar email temporário
app.post("/criar-email", async (req, res) => {
  try {
    const email = await client.mails.create();
    res.json(email);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log("Servidor rodando na porta 3000");
});

Script de automação

import { AcqClient } from "acq-sdk";
import { writeFileSync } from "fs";

async function gerarRelatorio() {
  const client = new AcqClient({ apiKey: process.env.ACQ_API_KEY! });

  // Buscar dados
  const emails = await client.mails.list();

  // Gerar HTML do relatório
  const html = `
    <!DOCTYPE html>
    <html>
      <head>
        <style>
          body { font-family: Arial; padding: 20px; }
          table { width: 100%; border-collapse: collapse; }
          th, td { padding: 10px; border: 1px solid #ddd; text-align: left; }
          th { background-color: #f4f4f4; }
        </style>
      </head>
      <body>
        <h1>Relatório de Emails</h1>
        <table>
          <tr><th>Email</th><th>Expira em</th></tr>
          ${emails
            .map(
              email => `
            <tr>
              <td>${email.email}</td>
              <td>${new Date(email.expiraEm).toLocaleString()}</td>
            </tr>
          `
            )
            .join("")}
        </table>
        <p>Total: ${emails.length} emails</p>
      </body>
    </html>
  `;

  // Gerar imagem do relatório
  const imagem = await client.render.htmlToImage({ html });
  writeFileSync(`relatorio-${Date.now()}.png`, imagem);

  console.log("Relatório gerado com sucesso!");
}

gerarRelatorio().catch(console.error);

🔧 Configuração Avançada

Configuração com variáveis de ambiente

// .env
ACQ_API_KEY=sua-api-key
ACQ_BASE_URL=https://api.acq.lat
ACQ_TIMEOUT=30000

// app.ts
import { AcqClient } from 'acq-sdk';

const client = new AcqClient({
  apiKey: process.env.ACQ_API_KEY!,
  baseUrl: process.env.ACQ_BASE_URL,
  timeout: parseInt(process.env.ACQ_TIMEOUT || '30000')
});

Usando com diferentes ambientes

import { AcqClient } from "acq-sdk";

const config = {
  development: {
    apiKey: process.env.ACQ_DEV_API_KEY!,
    baseUrl: "https://dev-api.acq.lat",
  },
  production: {
    apiKey: process.env.ACQ_PROD_API_KEY!,
    baseUrl: "https://api.acq.lat",
  },
};

const client = new AcqClient(config[process.env.NODE_ENV || "development"]);

📚 Tipos TypeScript

O SDK é totalmente tipado. Principais interfaces:

interface AcqClientConfig {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
}

interface EmailInfo {
  email: string;
  expiraEm: string;
}

interface EmailMessage {
  id: string;
  from: string;
  to: string;
  subject: string;
  body: string;
  html_body?: string;
  attachments?: EmailAttachment[];
  received_at: string;
}

interface RenderOptions {
  html: string;
}

🤝 Contribuindo

  1. Fork o repositório
  2. Crie uma branch: git checkout -b feature/nova-funcionalidade
  3. Commit suas mudanças: git commit -m 'Adiciona nova funcionalidade'
  4. Push para a branch: git push origin feature/nova-funcionalidade
  5. Abra um Pull Request

📄 Licença

MIT © ACQ Team

🆘 Suporte

Feito com ❤️ pela equipe ACQ

Settings

Member Visibility

Theme

On This Page

ACQ SDK