@alateamtech/notifuse-client

Cliente TypeScript tipado para la API de Notifuse (cloud o self-hosted). Pensado para enviar correos transaccionales desde cualquier aplicación de AlaTeamTech y cubrir APIs satélite (contactos, listas, templates, webhooks, custom events).

Características

• Envío transaccional con externalId (idempotencia), metadata y adjuntos (base64)
• Contactos: list / get / upsert / batch import / delete / count
• Listas: subscribe autenticado y update de status
• Templates: list / get / compile
• Webhooks: CRUD, toggle, regenerate secret, delivery history, event types
• Custom events: import en batch (máx. 50)
• Validación con Zod, errores tipados, retry con backoff exponencial
• Dual package ESM + CJS

Instalación

npm install @alateamtech/notifuse-client

Configuración

NOTIFUSE_URL=https://mail.tu-dominio.com
NOTIFUSE_API_KEY=...
NOTIFUSE_WORKSPACE_ID=ws_...

import { createNotifuseClient } from '@alateamtech/notifuse-client';

const client = createNotifuseClient({
  baseUrl: process.env.NOTIFUSE_URL!,
  apiKey: process.env.NOTIFUSE_API_KEY!,
  workspaceId: process.env.NOTIFUSE_WORKSPACE_ID!,
  timeout: 30_000,
  retries: 3,
});

Uso rápido

Enviar correo transaccional

await client.transactional.send({
  notificationId: 'password_reset',
  contact: { email: '[email protected]', firstName: 'Ana' },
  data: { reset_token: 'abc123' },
  externalId: 'pwd-reset-user123',
  emailOptions: {
    replyTo: '[email protected]',
    attachments: [
      {
        filename: 'guide.pdf',
        content: base64Pdf,
        contentType: 'application/pdf',
      },
    ],
  },
});

Límites de adjuntos (validados en el cliente): máx. 20 archivos, 3MB por archivo, 10MB total. Soporta disposition: 'inline' + contentId para imágenes embebidas.

Contactos

await client.contacts.upsert({
  email: '[email protected]',
  firstName: 'Carlos',
  externalId: 'user_123',
});

const { contacts, nextCursor } = await client.contacts.list({ limit: 20 });
const { totalContacts } = await client.contacts.count();

Listas

await client.lists.subscribe({
  contact: { email: '[email protected]' },
  listIds: ['newsletter'],
});

await client.lists.updateSubscription({
  email: '[email protected]',
  listId: 'newsletter',
  status: 'unsubscribed',
});

Templates

const { templates } = await client.templates.list({
  category: 'transactional',
  channel: 'email',
});

const compiled = await client.templates.compile({
  messageId: 'preview_1',
  visualEditorTree: { type: 'mjml', children: [] },
  testData: { user_name: 'Ana' },
  subject: 'Hola {{ user_name }}',
});

Webhooks

const { subscription } = await client.webhooks.create({
  name: 'Production',
  url: 'https://api.example.com/webhooks/notifuse',
  eventTypes: ['email.sent', 'email.delivered'],
});

Custom events

await client.customEvents.import({
  events: [
    {
      eventName: 'orders/fulfilled',
      externalId: 'order_123',
      email: '[email protected]',
      properties: { total: 99.99 },
      goalType: 'purchase',
      goalValue: 99.99,
    },
  ],
});

Errores

import {
  ValidationError,
  AuthenticationError,
  PermissionError,
  NotFoundError,
  isRetryableError,
} from '@alateamtech/notifuse-client';

try {
  await client.transactional.send({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // API key inválida
  } else if (error instanceof PermissionError) {
    // Falta transactional:write / contacts:read, etc.
  } else if (isRetryableError(error)) {
    // network / timeout / 5xx
  }
}

Migración desde @alateamtech/email-template-client

Ambos packages coexisten. Mapeo orientativo:

| Antes (email-template-client) | Después (notifuse-client) | | ----------------------------------------- | -------------------------------------------------------------------------------------- | | sendEmail('verification', { to, data }) | transactional.send({ notificationId: 'verification', contact: { email: to }, data }) | | sendEmailWithAttachments(...) | emailOptions.attachments (base64) | | renderTemplate(...) | templates.compile(...) | | Templates hardcodeados en el cliente | IDs de notification definidos en Notifuse |

Desarrollo

npm install
npm run test --workspace=@alateamtech/notifuse-client
npm run build --workspace=@alateamtech/notifuse-client

License

MIT