npm package: @leguas-mail/leguas-mail-sdk
Description: SDK Node.js para integração com a API Leguas Mail (envio de e-mail). Compatível com Lambda e Node 18+.
Author: Leguas Mail Team
Latest version: 1.0.6

# 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](https://github.com/leguas/leguas-mail-sdk-java).

- **Node:** 18+
- **Lambda:** compatível (sem filesystem persistente; use env vars para `baseUrl` e API Key).

## Instalação

```bash
npm install leguas-mail-sdk
```

## Uso rápido

```javascript
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: 'noreply@seudominio.com',
  to: 'cliente@email.com',
  subject: 'Assunto',
  body: '<p>Olá!</p>',
  contentType: 'text/html',
});
console.log('Enviado:', emailId);
```

### Apenas API Key (usa URL padrão)

```javascript
const client = new LeguasMailClient('sua-api-key');
const emailId = await client.sendEmail({ from: '...', to: '...', subject: '...', body: '...' });
```

### Envio com anexos

```javascript
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: 'noreply@example.com',
    to: 'user@example.com',
    subject: 'Seu anexo',
    body: 'Segue em anexo.',
  },
  [
    { fileName: 'doc.pdf', contentType: 'application/pdf', content: pdfBuffer },
  ]
);
```

### Envio confiável (retry automático)

```javascript
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:**

```javascript
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

```javascript
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):

```json
{
  "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.