@randstad-uca/aws-sns-publisher

@randstad-uca/aws-sns-publisher

Es una librería ligera desarrollada en Node.js para publicar mensajes a Amazon SNS de forma simple, validada y con logging configurable. Ideal para sistemas desacoplados y orientados a eventos en entornos AWS.

📦 Instalación

npm install @randstad-uca/aws-sns-publisher

🚀 Uso Básico

import { SimpleSNSPublisher } from '@randstad-uca/aws-sns-publisher';

const SNSClient = new SimpleSNSPublisher({
  awsConfig: { region: 'us-east-1' }, // required obj
  logEnabled: true, // optional (default value: true)
  logLevel: 'info', // optional (default value: info)
  throwError: true, // optional (default value: true)
  logHandler: {
    // You can implement your own logging handler here (optional)
    info: (args) =>
      // success case
      console.log('Custom success logging handler logic', args),
    error: (args) =>
      // error case
      console.error('Custom error logging handler logic', args),
  },
});

const payload = {
  eventType: 'sms',
  payload: {
    phone: '[phone]',
    message: 'Hello there!',
  },
};

SNSClient.publish({
  message: JSON.stringify(payload),
  topicARN: 'your-sns-topic-ARN',
  apiName: 'api-name', // If the topic type is FIFO you must define a valid apiName
})
  .then((result) => console.log('Success:', result))
  .catch((err) => console.error('Error:', err));

📘 API

Clase: SimpleSNSPublisher

Constructor

new SimpleSNSPublisher(options: IPublisherOptions)

IPublisherOptions:

• awsConfig: SNSClientConfig – Requerido. Como minimo se debe especificar la región de AWS para instanciar el cliente SNS.

• logEnabled?: boolean – Habilita logs. Default: true.

• logLevel?: 'info' | 'silent' – Nivel de log. Default: 'info'.

• throwError?: boolean – Si lanzar errores o no. Default: true.

• logHandler?: { info: Function; error: Function } – Handler personalizado para logs.

✨ Metodos

Método: publish(options: IPublishOptions): Promise<PublishResponse>

Publica un mensaje en un topic SNS. Antes de enviar el mensaje, se valida su estructura usando la libreria Joi.

IPublishOptions:

• message: string – Debe ser un string que contenga un objeto, y este debe tener las siguientes propiedades:

  • eventType: string – Tipo del evento (ej: "sms", "add-personal-data" o cualquiera que se encuentre dentro del objeto validEventTypes ubicado en el archivo constants.ts).

  • payload: object – Objeto con los datos del evento.

• topicARN: string – ARN del SNS Topic.

• apiName?: string – Nombre de la API emisora, las unicas validas son las que se encuentran dentro del objeto validApiNames ubicado en el archivo constants.ts. Esta se utiliza como bandera para la creación del MessageDeduplicationId y MessageGroupId necesarios en topics FIFO.

• extraOptions?: object – Parámetros adicionales para PublishCommand.

Validaciones automáticas:

• eventType es obligatorio y debe estar en la lista de eventos válidos.

• Se valida el payload según el tipo de evento con esquemas Joi definidos internamente.

• Si se configura throwError: true, lanza error. Si no, devuelve Promise.reject() con el error.

Método: validateSchema(eventType: string, payload: object): boolean

Valida el payload contra el esquema correspondiente según eventType.

📎 Ejemplo de payload válido

{
  "eventType": "email",
  "payload": {
    "to": "[e-mail]",
    "subject": "Hello!",
    "body": "This is an example email."
  }
}

📄 Schema Documentation

See schema-doc.md for a full list of event types and their schema fields

🧩 Características

• ✅ Compatible con múltiples regiones AWS.

• ✅ Validación automática con Joi.

• ✅ Logging personalizable (info y error).

• ✅ Ideal para arquitectura orientada a eventos.

📌 Consideraciones

• Se espera que los topics estén previamente creados en SNS.

• Esta librería no crea los topics automáticamente.

• En caso de usar topics FIFO, es importante pasar un apiName valido para deduplicación.