Integrar el SDK JavaScript y TypeScript

Summit Notify SDK simplifica el uso de la API JSON desde JavaScript y TypeScript. Incluye tipos, JSDoc, seguimiento asíncrono, errores estructurados y distribuciones para ES Modules, CommonJS y navegadores. El mismo cliente permite enviar correo y WhatsApp y administrar los recursos públicos de la API.

Requisitos

Una cuenta SMTP configurada para correo o una cuenta WhatsApp configurada para ese canal.
Una API key de Summit Notify.
Node.js con fetch o un navegador moderno.

La API key es un secreto. Guárdala en una variable de entorno o un gestor de secretos y realiza los envíos desde un servidor. No la incluyas en repositorios ni en JavaScript público.

Elegir una distribución

Los archivos se publican individualmente en el CDN. La URL del directorio no muestra un índice; utiliza una de las rutas completas siguientes:

Entorno	Archivo recomendado	Declaraciones TypeScript
ES Modules	`index.min.mjs`	`index.min.d.mts`
CommonJS	`index.min.cjs`	`index.min.d.cts`
Script clásico	`index.min.js`	`index.min.d.ts`

Usa las variantes sin .min durante depuración si necesitas código legible. Todas exponen la misma API.

Autocompletado con JSDoc y TypeScript

Las variantes legibles index.js e index.cjs incluyen JSDoc para mostrar en el editor las opciones del cliente, los parámetros de los métodos y el estado devuelto. En un archivo JavaScript local puedes activar comprobaciones adicionales sin migrarlo a TypeScript:

// @ts-check
const { createClient } = require("./summit-notify.cjs");

const notify = createClient({
  apiKey: process.env.SUMMIT_NOTIFY_API_KEY
});

Las declaraciones .d.ts, .d.mts y .d.cts ofrecen el contrato más preciso. Por ejemplo, distinguen entre correo y WhatsApp y comprueban que un adjunto de WhatsApp use exactamente una fuente: id o link. Conserva la declaración correspondiente junto al archivo JavaScript descargado para obtener esa ayuda.

Crear un cliente con ES Modules

En un navegador puedes importar el módulo directamente desde su URL real:

import {
  createClient,
  SummitNotifyError,
  type NotificationInput
} from "https://cdn.summitexplorerjd.ec/package/summit-notify@1.0.0/index.min.mjs";

const notify = createClient({
  apiKey: process.env.SUMMIT_NOTIFY_API_KEY
});

Node.js y el compilador estándar de TypeScript normalmente no importan módulos ni declaraciones desde URLs HTTPS. En esos entornos, descarga index.min.mjs y index.min.d.mts, consérvalos juntos dentro del proyecto e importa el archivo local.

Crear un cliente con CommonJS

Descarga el archivo CommonJS desde su URL real y guárdalo en el proyecto:

curl -o summit-notify.cjs https://cdn.summitexplorerjd.ec/package/summit-notify@1.0.0/index.min.cjs

Después impórtalo desde la ruta donde lo guardaste:

const { createClient } = require("./summit-notify.cjs");

const notify = createClient({
  apiKey: process.env.SUMMIT_NOTIFY_API_KEY
});

index.min.cjs funciona con require(). Para obtener tipos, descarga también index.min.d.cts y consérvalo junto al módulo.

Enviar un correo

const message: NotificationInput = {
  recipient: "cliente@example.com",
  cc: ["supervisor@example.com"],
  bcc: ["auditoria@example.com"],
  from_name: "Equipo de soporte",
  subject: "Actualización del caso",
  body: "Tu solicitud fue actualizada.",
  body_type: "text"
};

const notification = await notify.send(message);
console.log(notification.id, notification.status);

La API responde cuando el mensaje entra en la cola. Un estado inicial pending no confirma todavía que el proveedor haya aceptado el correo.

Se admiten hasta 50 direcciones entre destinatario principal, CC y CCO. Todas deben cumplir las restricciones trusted_domains de la cuenta seleccionada.

Enviar HTML

await notify.send({
  recipient: "destinatario@example.com",
  subject: "Resumen semanal",
  body_type: "html",
  body: "<h1>Resumen</h1><p>Tienes <strong>3 novedades</strong>.</p>"
});

Summit Notify envía el contenido tal como se recibe. Usa HTML compatible con clientes de correo y no dependas de JavaScript.

Usar una plantilla

const notification = await notify.send({
  recipient: "ana@example.com",
  template_id: "c7a4e210-9d2b-4f6a-8e1c-3b5d7f9a0c2e",
  variables: {
    Nombre: "Ana",
    Pedido: "PED-1042"
  }
});

Los nombres de variables distinguen mayúsculas y minúsculas. Consulta Crear y usar plantillas para definir y probar el contenido.

Enviar una notificación de WhatsApp

Usa channel: "whatsapp", un teléfono E.164 y el payload específico del canal. La cuenta debe configurarse previamente desde el panel porque no existe un CRUD público para cuentas WhatsApp.

const message: NotificationInput = {
  channel: "whatsapp",
  recipient: "+593999999999",
  whatsapp_account_id: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  whatsapp: {
    type: "template",
    template_id: "c7a4e210-9d2b-4f6a-8e1c-3b5d7f9a0c2e",
    values: {
      parameter_1: "Ana"
    }
  }
};

const notification = await notify.send(message);

También se admiten text, image, video, audio, document, location y reaction. Un mensaje libre requiere una ventana de servicio abierta de 24 horas. Puedes incluir fallback_template para que el worker use una plantilla aprobada si la ventana se cierra antes de procesarlo.

Los objetos image, video, audio y document aceptan exactamente uno de:

id: identificador de un archivo cargado previamente.
link: URL HTTPS pública accesible para WhatsApp.

Consulta la referencia del canal WhatsApp para conocer los payloads y las reglas de la ventana de servicio.

Esperar el resultado

const result = await notify.notifications.wait(notification.id, {
  interval: 1000,
  backoff: 1.5,
  maxInterval: 5000,
  timeout: 30000
});

console.log(result.status, result.last_error);

wait() consulta con intervalos crecientes y termina en sent o failed. Durante un envío de WhatsApp también puede observar submitted: AWS aceptó la solicitud y Summit Notify espera eventos posteriores. El SDK continúa consultando porque submitted no es terminal.

El estado sent significa que SMTP aceptó el correo o WhatsApp confirmó el envío. No confirma lectura ni descarta un rebote posterior. Los eventos delivered y read de WhatsApp no se exponen como estados independientes.

Para cancelar la espera:

const controller = new AbortController();
const resultPromise = notify.notifications.wait(notification.id, {
  signal: controller.signal
});
controller.abort();

Manejar errores y rate limiting

try {
  await notify.send(message);
} catch (error) {
  if (error instanceof SummitNotifyError) {
    console.error(error.status, error.message, error.data);

    if (error.status === 429) {
      console.error(`Espera ${error.retryAfter} segundos`);
    }
  }
}

SummitNotifyError incluye status, statusText, method, url, data y, cuando existe, retryAfter. Los errores de red y cancelaciones conservan el error nativo de fetch.

Administrar cuentas y plantillas

Los endpoints administrativos requieren un access token OpenID Connect, no la API key de notificaciones:

const admin = createClient({
  accessToken: process.env.SUMMIT_NOTIFY_OIDC_TOKEN
});

const accounts = await admin.smtpAccounts.list();
const templates = await admin.templates.list();
const whatsappTemplates = await admin.whatsappTemplates.list();

El cliente expone:

smtpAccounts.list/get/create/update/remove/test
templates.list/get/create/update/remove
whatsappTemplates.list/get/create/sync/remove
health.live/ready/status

Las actualizaciones de cuentas y plantillas usan PUT: reemplazan el objeto completo, no aplican un patch parcial. Las plantillas WhatsApp se crean en AWS/Meta; solo los estados remotos APPROVED o ACTIVE establecen can_send: true.

Verificar la integración

Envía una notificación y guarda el id devuelto.
Espera su resultado con notifications.wait().
Confirma que termina en sent.
Si termina en failed, revisa last_error y consulta Supervisar entregas.