Leguas Mail SDK – Node.js

https://www.npmjs.com/package/@leguas-mail/leguas-mail-sdk

SDK oficial em Node.js para integração com a API Leguas Mail (envio de e-mail).
Segue o mesmo padrão de uso do SDK Java.

• Node: 18+
• Lambda: compatível (sem filesystem persistente; use env vars para baseUrl e API Key).

Instalação

npm install leguas-mail-sdk

Uso rápido

const { LeguasMailClient } = require('leguas-mail-sdk');

const client = new LeguasMailClient(
  'https://leguas-api.mlacelerator.com.br',
  'sua-api-key'
);

// Envio simples (sem anexos)
const emailId = await client.sendEmail({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Assunto',
  body: '<p>Olá!</p>',
  contentType: 'text/html',
});
console.log('Enviado:', emailId);

Apenas API Key (usa URL padrão)

const client = new LeguasMailClient('sua-api-key');
const emailId = await client.sendEmail({ from: '...', to: '...', subject: '...', body: '...' });

Envio com anexos

const { LeguasMailClient } = require('leguas-mail-sdk');

const client = new LeguasMailClient(process.env.LEGUAS_MAIL_BASE_URL, process.env.LEGUAS_MAIL_API_KEY);

const emailId = await client.sendEmail(
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Seu anexo',
    body: 'Segue em anexo.',
  },
  [
    { fileName: 'doc.pdf', contentType: 'application/pdf', content: pdfBuffer },
  ]
);

Envio confiável (retry automático)

const result = await client.sendEmailReliable(request, null);

switch (result.status) {
  case 'SENT':
    console.log('Enviado:', result.emailId);
    break;
  case 'QUEUED':
    console.log('Enfileirado:', result.messageId);
    break;
  case 'FAILED':
    console.error('Falha:', result.error);
    break;
}

Nota: No SDK Node não há outbox em disco (inadequado para Lambda). O método sendEmailReliable faz apenas retry com backoff; não enfileira em arquivo local.

Uso em AWS Lambda

1. Variáveis de ambiente (recomendado):

   • LEGUAS_MAIL_DEFAULT_BASE_URL – URL da API (opcional; há default).
   • Guarde a API Key em Secrets Manager ou SSM e injete no handler (ou use env com cuidado).

2. Exemplo de handler:

const { LeguasMailClient } = require('leguas-mail-sdk');

let client;

function getClient() {
  if (!client) {
    client = new LeguasMailClient(
      process.env.LEGUAS_MAIL_BASE_URL || 'https://leguas-api.mlacelerator.com.br',
      process.env.LEGUAS_MAIL_API_KEY
    );
  }
  return client;
}

exports.handler = async (event) => {
  const c = getClient();
  const emailId = await c.sendEmail({
    from: event.from,
    to: event.to,
    subject: event.subject,
    body: event.body,
  });
  return { emailId };
};

3. Timeout: Configure o timeout da Lambda (ex.: 30 s) para dar tempo do retry do SDK.

Opções

const { LeguasMailClient } = require('leguas-mail-sdk');

const client = new LeguasMailClient(baseUrl, apiKey, {
  defaultBaseUrl: 'https://leguas-api.mlacelerator.com.br',
  maxAttempts: 3,
  initialBackoffMs: 250,
  maxBackoffMs: 5000,
  connectTimeoutMs: 30_000,
  readTimeoutMs: 60_000,
  writeTimeoutMs: 60_000,
});

API (espelho do SDK Java)

| Método | Descrição | |--------|-----------| | sendEmail(request [, attachments]) | Envia e-mail. Retorna emailId ou null. | | sendEmailReliable(request, attachments) | Envio com retry. Retorna { status, emailId?, messageId, error? }. |

Request: from, to, subject, body?, contentType?, fromName?, replyTo?, tenantId?, templateId?, templateVariables?.

Routing remoto e cache de IP (LB)

O SDK busca um JSON de roteamento (igual ao SDK Java) para:

• Atualizar a URL base da API (se não tiver sido fixada no construtor).
• Usar IPs do load balancer em cache, evitando depender de DNS a cada request.

Formato do JSON (ex.: routing.json no OCI ou em qualquer URL pública):

{
  "apiBaseUrl": "https://leguas-api.mlacelerator.com.br",
  "apiLbIps": ["216.238.117.206", "216.238.107.38"],
  "ttlSeconds": 1800
}

• Variável de ambiente: LEGUAS_MAIL_ROUTING_URLS – URLs separadas por vírgula (ex.: https://..../routing.json). Se não definir, usa uma URL padrão (OCI).
• Opções: remoteConfigUrls, allowRemoteBaseUrlOverride, routingConfigCacheTtlMs, ipCacheTtlMs.

Assim você deixa o domínio e os IPs do LB dinâmicos: basta atualizar o JSON no bucket/URL.

Limitações (Node / Lambda)

• Outbox em disco: não implementada (Lambda não tem filesystem persistente). Apenas retry em memória.

Licença

MIT.