@eclass/api-notifications-sdk

SDK para proyectos Node.js + Express que necesiten enviar notificaciones a la API eClass mediante:

• POST /notifications/queue

Requisitos

• Node.js >= 18

Instalacion

npm i @eclass/api-notifications-sdk

Uso rapido (Express)

const express = require('express')
const { NotificationsQueueClient } = require('@eclass/api-notifications-sdk')

const app = express()
app.use(express.json())

const notificationsClient = new NotificationsQueueClient({
  baseUrl: process.env.ECLASS_NOTIFICATIONS_BASE_URL,
  apiKey: process.env.ECLASS_NOTIFICATIONS_API_KEY,
  timeoutMs: 15000
})

app.post('/notifications/queue', async (req, res) => {
  try {
    const response = await notificationsClient.queue(req.body)
    res.status(200).json(response)
  } catch (error) {
    res.status(error.status || 500).json({
      message: error.message,
      code: error.code || 'UNEXPECTED_ERROR',
      details: error.details || null
    })
  }
})

app.listen(3000)

Formato de payload compatible con API

{
  "setting_notification": "recordatorio-clase",
  "branding_id": "34",
  "scheduled_at": "2026-03-01T14:30:00.000Z",
  "receivers": [
    {
      "email": "[email protected]",
      "external_id": 12345,
      "data": {
        "nombre": "Ana Pérez",
        "curso": "Matemáticas 101",
        "fecha": "2026-03-01"
      },
      "ical": [
        {
          "uid": "evt-001@api-notificaciones",
          "title": "Clase en vivo",
          "description": "Sesión de repaso",
          "status": "CONFIRMED",
          "start": "2026-03-01T15:00:00.000Z",
          "duration": 60,
          "time_zone": "America/Santiago",
          "organizer": "[email protected]"
        }
      ]
    }
  ]
}

API del cliente

new NotificationsQueueClient(options)

options disponibles:

• baseUrl (string, requerido)
• apiKey (string, recomendado al construir, tambien puede setearse despues)
• timeoutMs (number, default 15000)
• endpointPath (string, default /notifications/queue)
• defaultHeaders (object)
• validatePayloadByDefault (boolean, default true)

client.queue(payload, options?)

Envia el payload al endpoint configurado.

options:

• validatePayload (boolean)
• idempotencyKey (string) -> se envia como header x-idempotency-key
• headers (object) -> headers adicionales

Validacion incluida

Antes de enviar la solicitud, el SDK valida por defecto:

• setting_notification obligatorio y string no vacio
• receivers obligatorio y arreglo no vacio
• cada receiver debe incluir email valido
• cada receiver debe incluir data (object)
• cada receiver puede incluir external_id (número entero). Si no se envía, el SDK lo completa con 0.
• scheduled_at validado si viene (opcional: formato ISO UTC, por ejemplo 2022-08-13T12:15:00.000Z)
• branding_id validado si viene (opcional: string no vacio)
• si viene ical, se valida estructura de cada evento (uid, title, status, start, duration, time_zone)

Si no quieres validar en el SDK:

await notificationsClient.queue(payload, { validatePayload: false })

Errores

Todas las fallas del SDK lanzan errores tipados:

• NotificationsQueueConfigError
• NotificationsQueueAuthError
• NotificationsQueueValidationError
• NotificationsQueueError (errores HTTP/network)

Todos incluyen:

• message
• status
• code
• details

Ejemplos de respuestas de error de la API

Los siguientes JSON son ejemplos de respuestas que la API podria retornar ante distintos escenarios:

400 - Payload invalido

{
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "issues": [
      "receivers[0].email is required and must be a valid email"
    ]
  }
}

401 - API key invalida o faltante

{
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "details": null
}

404 - Configuracion de notificacion no encontrada

{
  "message": "setting_notification not found",
  "code": "SETTING_NOTIFICATION_NOT_FOUND",
  "details": {
    "setting_notification": "recordatorio-clase"
  }
}

429 - Limite de tasa excedido

{
  "message": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "retry_after_seconds": 60
  }
}

500 - Error interno del servicio

{
  "message": "Internal server error",
  "code": "INTERNAL_ERROR",
  "details": null
}

Error de red/timeout (sin respuesta HTTP de API)

Cuando no existe respuesta HTTP (timeout, DNS, conexion rechazada), el SDK lanza:

{
  "message": "connect ETIMEDOUT",
  "code": "SDK-NETWORK-001",
  "status": 500,
  "details": null
}

Respuesta esperada

La respuesta depende de la API, por ejemplo:

{
  "message": "Notificacion encolada correctamente",
  "statusCode": 200,
  "data": {
    "queue_notification_id": 12345,
    "request_id": "md5..."
  }
}

Ejemplo completo

Revisa examples/express/README.md.