core-services-sdk 1.3.7 → 1.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
@@ -19,8 +19,9 @@
   "homepage": "https://github.com/haim-rubin/core-services-sdk#readme",
   "description": "",
   "dependencies": {
+    "@aws-sdk/client-ses": "^3.862.0",
+    "@aws-sdk/credential-provider-node": "^3.862.0",
     "amqplib": "^0.10.8",
-    "aws-sdk": "^2.1692.0",
     "crypto": "^1.0.1",
     "dot": "^1.1.3",
     "fastify": "^5.4.0",

package/src/fastify/error-codes.js

@@ -1,5 +1,16 @@
 import httpStatus from 'http-status'
 
+/**
+ * A reusable generic error object representing a server-side failure (HTTP 500).
+ * Useful as a fallback error descriptor for unhandled or unexpected failures.
+ *
+ * @typedef {Object} GeneralError
+ * @property {number} httpStatusCode - The HTTP status code (500).
+ * @property {string} httpStatusText - The human-readable status text ("Internal Server Error").
+ * @property {string} code - An application-specific error code in the format "GENERAL.<StatusText>".
+ */
+
+/** @type {GeneralError} */
 export const GENERAL_ERROR = {
   httpStatusCode: httpStatus.INTERNAL_SERVER_ERROR,
   httpStatusText: httpStatus[httpStatus.INTERNAL_SERVER_ERROR],

package/src/http/HttpError.js

@@ -1,24 +1,46 @@
 import httpStatus from 'http-status'
 
+/**
+ * Represents a custom HTTP error with optional status code, status text, error code, and extra metadata.
+ * Useful for consistent error handling across services.
+ */
 export class HttpError extends Error {
-  /** @type {string|undefined} */
+  /**
+   * @type {string | number | undefined}
+   * A short application-specific error code (e.g., "INVALID_INPUT" or a numeric code).
+   */
   code
 
-  /** @type {number|undefined} */
+  /**
+   * @type {number | undefined}
+   * HTTP status code associated with the error (e.g., 400, 500).
+   */
   httpStatusCode
 
-  /** @type {string|undefined} */
+  /**
+   * @type {string | undefined}
+   * Human-readable HTTP status text (e.g., "Bad Request").
+   */
   httpStatusText
 
   /**
-   * @param {object} [error]
-   * @param {string} [error.code]
-   * @param {string} [error.message]
-   * @param {number} [error.httpStatusCode]
-   * @param {string} [error.httpStatusText]
+   * @type {object | undefined}
+   * Optional metadata for debugging/logging (e.g., request ID, user ID, retryAfter).
+   */
+  extendInfo
+
+  /**
+   * Creates an instance of HttpError.
+   *
+   * @param {Object} [error] - Optional error object.
+   * @param {string | number} [error.code] - Application-specific error code.
+   * @param {string} [error.message] - Custom error message.
+   * @param {number} [error.httpStatusCode] - HTTP status code (e.g., 404, 500).
+   * @param {string} [error.httpStatusText] - Optional human-readable HTTP status text.
+   * @param {object} [error.extendInfo] - Optional extended metadata for diagnostics.
    */
   constructor(error = {}) {
-    const { code, message, httpStatusCode, httpStatusText } = error
+    const { code, message, httpStatusCode, httpStatusText, extendInfo } = error
 
     super(
       message ||
@@ -31,16 +53,29 @@ export class HttpError extends Error {
     this.httpStatusCode = httpStatusCode
     this.httpStatusText =
       httpStatusText || (httpStatusCode && httpStatus[httpStatusCode])
+    this.extendInfo = extendInfo
 
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor)
     }
   }
 
+  /**
+   * Checks if a given object is an instance of `HttpError`.
+   *
+   * @param {*} instance - The object to check.
+   * @returns {boolean} True if `instance` is an instance of `HttpError`.
+   */
   static isInstanceOf(instance) {
     return instance instanceof HttpError
   }
 
+  /**
+   * Custom implementation for `instanceof` checks.
+   *
+   * @param {*} instance - The object to check.
+   * @returns {boolean} True if it has HttpError-like structure.
+   */
   static [Symbol.hasInstance](instance) {
     return (
       instance &&
@@ -51,18 +86,57 @@ export class HttpError extends Error {
     )
   }
 
+  /**
+   * Converts the error to a plain object (useful for logging or sending as JSON).
+   *
+   * @returns {{
+   *   code: string | number | undefined,
+   *   message: string,
+   *   httpStatusCode: number | undefined,
+   *   httpStatusText: string | undefined,
+   *   extendInfo?: object
+   * }}
+   */
   toJSON() {
     return {
       code: this.code,
       message: this.message,
       httpStatusCode: this.httpStatusCode,
       httpStatusText: this.httpStatusText,
+      ...(this.extendInfo ? { extendInfo: this.extendInfo } : {}),
     }
   }
 
+  /**
+   * Checks if the error is an instance of `HttpError` or has similar shape.
+   *
+   * @param {object} error
+   * @returns {error is HttpError}
+   */
+  static isHttpError(error) {
+    return (
+      error instanceof HttpError ||
+      (error &&
+        typeof error === 'object' &&
+        'httpStatusCode' in error &&
+        'httpStatusText' in error &&
+        'toJSON' in error)
+    )
+  }
+
+  /**
+   * Creates an HttpError from a generic Error instance or returns it if already an HttpError.
+   *
+   * @param {Error | HttpError} error
+   * @returns {HttpError}
+   */
   static FromError(error) {
+    if (HttpError.isHttpError(error)) {
+      return error
+    }
+
     const httpError = new HttpError({
-      code: error.code || 'UNHANDLED_ERROR',
+      code: 'UNHANDLED_ERROR',
       message: error.message || 'An unexpected error occurred',
       httpStatusCode: httpStatus.INTERNAL_SERVER_ERROR,
       httpStatusText: httpStatus[httpStatus.INTERNAL_SERVER_ERROR],

package/src/http/http.js

@@ -1,3 +1,10 @@
+/**
+ * A lightweight HTTP client wrapper around `node-fetch` supporting JSON, XML, and plain text responses.
+ * Provides simplified helper methods for GET, POST, PUT, PATCH, and DELETE with automatic error handling.
+ *
+ * @module http
+ */
+
 import fetch from 'node-fetch'
 import httpStatus from 'http-status'
 import { parseStringPromise } from 'xml2js'
@@ -13,40 +20,36 @@ const JSON_HEADER = {
 /**
  * Checks if the HTTP status is considered successful (2xx).
  *
- * @param {Response} res - The fetch response object.
- * @returns {boolean} `true` if status code is between 200-299.
+ * @param {import('node-fetch').Response} response
+ * @returns {boolean}
  */
 const isOkStatus = ({ status }) =>
   status >= httpStatus.OK && status < httpStatus.MULTIPLE_CHOICES
 
 /**
- * Verifies response status and throws a structured HttpError if not OK.
- *
- * @param {Response} res - The fetch response object.
- * @throws {HttpError} When the response status is not OK.
- * @returns {Response} The response if status is OK.
+ * @param {import('node-fetch').Response} response
+ * @returns {Promise<import('node-fetch').Response>}
  */
-const checkStatus = async (res) => {
-  if (!isOkStatus(res)) {
-    const text = await res.text()
+const checkStatus = async (response) => {
+  if (!isOkStatus(response)) {
+    const text = await response.text()
     const info = tryConvertJsonResponse(text)
-    const { status, statusText } = res
+    const { status, statusText } = response
 
     throw new HttpError({
       code: status,
       httpStatusCode: status,
       httpStatusText: statusText,
-      details: info,
     })
   }
-  return res
+  return response
 }
 
 /**
  * Reads the raw text from a fetch response.
  *
- * @param {Response} response - The fetch response.
- * @returns {Promise<string>} The text body.
+ * @param {import('node-fetch').Response} response
+ * @returns {Promise<string>} The plain text body.
  */
 const getTextResponse = async (response) => {
   return await response.text()
@@ -71,8 +74,8 @@ const tryConvertJsonResponse = (responseText) => {
 /**
  * Attempts to extract a JSON object from a fetch response.
  *
- * @param {Response} response - The fetch response.
- * @returns {Promise<Object|string>} Parsed object or raw string on failure.
+ * @param {import('node-fetch').Response} response
+ * @returns {Promise<Object|string>} Parsed JSON or raw string if parsing fails.
  */
 const tryGetJsonResponse = async (response) => {
   let jsonText
@@ -88,8 +91,8 @@ const tryGetJsonResponse = async (response) => {
 /**
  * Attempts to extract an XML object from a fetch response.
  *
- * @param {Response} response - The fetch response.
- * @returns {Promise<Object|string>} Parsed XML object or raw string.
+ * @param {import('node-fetch').Response} response
+ * @returns {Promise<Object|string>} Parsed XML object or raw string if parsing fails.
  */
 const tryGetXmlResponse = async (response) => {
   let xmlText
@@ -105,8 +108,8 @@ const tryGetXmlResponse = async (response) => {
 /**
  * Extracts and parses the fetch response body based on expected type.
  *
- * @param {Response} response - The fetch response.
- * @param {string} responseType - The expected response type ('json', 'xml', 'text').
+ * @param {import('node-fetch').Response} response
+ * @param {string} responseType - Expected type: 'json', 'xml', or 'text'.
  * @returns {Promise<any>} The parsed response payload.
  */
 const getResponsePayload = async (response, responseType) => {
@@ -125,10 +128,10 @@ const getResponsePayload = async (response, responseType) => {
  * Sends an HTTP GET request.
  *
  * @param {Object} params
- * @param {string} params.url - The target URL.
- * @param {Object} [params.headers] - Optional custom headers.
- * @param {string} [params.credentials='include'] - Credential mode.
- * @param {string} [params.expectedType='json'] - Response type.
+ * @param {string} params.url - Target URL.
+ * @param {Object} [params.headers] - Optional request headers.
+ * @param {string} [params.credentials='include'] - Credential policy.
+ * @param {string} [params.expectedType='json'] - Expected response format.
  * @returns {Promise<any>} Parsed response data.
  */
 export const get = async ({
@@ -137,11 +140,13 @@ export const get = async ({
   credentials = 'include',
   expectedType = ResponseType.json,
 }) => {
+  /** @type {import('node-fetch').Response} */
   const response = await fetch(url, {
     method: HTTP_METHODS.GET,
     headers: { ...JSON_HEADER, ...headers },
     ...(credentials ? { credentials } : {}),
   })
+
   await checkStatus(response)
   return await getResponsePayload(response, expectedType)
 }
@@ -150,11 +155,11 @@ export const get = async ({
  * Sends an HTTP POST request.
  *
  * @param {Object} params
- * @param {string} params.url - The target URL.
- * @param {Object} params.body - Body data to send.
- * @param {Object} [params.headers] - Optional custom headers.
- * @param {string} [params.credentials='include'] - Credential mode.
- * @param {string} [params.expectedType='json'] - Response type.
+ * @param {string} params.url - Target URL.
+ * @param {Object} params.body - Request body (will be JSON.stringify-ed).
+ * @param {Object} [params.headers] - Optional request headers.
+ * @param {string} [params.credentials='include'] - Credential policy.
+ * @param {string} [params.expectedType='json'] - Expected response format.
  * @returns {Promise<any>} Parsed response data.
  */
 export const post = async ({
@@ -177,7 +182,12 @@ export const post = async ({
 /**
  * Sends an HTTP PUT request.
  *
- * @param {Object} params - Same as `post`.
+ * @param {Object} params
+ * @param {string} params.url
+ * @param {Object} params.body
+ * @param {Object} [params.headers]
+ * @param {string} [params.credentials='include']
+ * @param {string} [params.expectedType='json']
  * @returns {Promise<any>} Parsed response data.
  */
 export const put = async ({

package/src/http/index.js

@@ -0,0 +1,4 @@
+export * from './http.js'
+export * from './HttpError.js'
+export * from './http-method.js'
+export * from './responseType.js'

package/src/http/responseType.js

@@ -1,3 +1,13 @@
+/**
+ * Enum representing supported response types for HTTP client parsing.
+ *
+ * @readonly
+ * @enum {string}
+ * @property {string} xml  - XML response (parsed using xml2js).
+ * @property {string} json - JSON response (parsed via JSON.parse).
+ * @property {string} text - Plain text response.
+ * @property {string} file - Binary file or blob (not automatically parsed).
+ */
 export const ResponseType = Object.freeze({
   xml: 'xml',
   json: 'json',

package/src/ids/index.js

@@ -0,0 +1,2 @@
+export * from './prefixes.js'
+export * from './generators.js'

package/src/index.js

@@ -1,24 +1,10 @@
-export * from './ids/prefixes.js'
+export * from './core/index.js'
+export * from './crypto/index.js'
 export * from './fastify/index.js'
+export * from './http/index.js'
+export * from './ids/index.js'
 export * from './mongodb/index.js'
-export * from './crypto/crypto.js'
-export * from './ids/generators.js'
+export * from './logger/index.js'
+export * from './mailer/index.js'
 export * from './rabbit-mq/index.js'
-export * from './core/regex-utils.js'
-export * from './logger/get-logger.js'
-export * as http from './http/http.js'
-export * from './http/responseType.js'
-export * from './crypto/encryption.js'
-export * from './core/otp-generators.js'
-export * from './core/sanitize-objects.js'
-export * from './core/normalize-to-array.js'
-export { initMailer } from './mailer/index.js'
-export * from './core/combine-unique-arrays.js'
-export { HttpError } from './http/HttpError.js'
-export { Mailer } from './mailer/mailer.service.js'
-export { TransportFactory } from './mailer/transport.factory.js'
-export {
-  isItFile,
-  loadTemplates,
-  getTemplateContent,
-} from './templates/template-loader.js'
+export * from './templates/index.js'

package/src/mailer/transport.factory.js

@@ -1,6 +1,7 @@
-import aws from 'aws-sdk'
 import nodemailer from 'nodemailer'
 import sgTransport from 'nodemailer-sendgrid-transport'
+import { SESClient, SendRawEmailCommand } from '@aws-sdk/client-ses'
+import { defaultProvider } from '@aws-sdk/credential-provider-node'
 
 /**
  * Factory for creating Nodemailer transporters based on configuration.
@@ -54,13 +55,25 @@ export class TransportFactory {
           }),
         )
 
-      case 'ses':
-        const ses = new aws.SES({
-          accessKeyId: config.accessKeyId,
-          secretAccessKey: config.secretAccessKey,
+      case 'ses': {
+        const sesClient = new SESClient({
           region: config.region,
+          credentials:
+            config.accessKeyId && config.secretAccessKey
+              ? {
+                  accessKeyId: config.accessKeyId,
+                  secretAccessKey: config.secretAccessKey,
+                }
+              : defaultProvider(),
         })
-        return nodemailer.createTransport({ SES: { ses, aws } })
+
+        return nodemailer.createTransport({
+          SES: {
+            ses: sesClient,
+            aws: { SendRawEmailCommand },
+          },
+        })
+      }
 
       default:
         throw new Error(`Unsupported transport type: ${config.type}`)

package/src/mongodb/initialize-mongodb.js

@@ -2,15 +2,18 @@
 import { mongoConnect } from './connect.js'
 
 /**
- * Initializes MongoDB collections and provides a transaction wrapper and read-only client accessor.
+ * Initializes MongoDB collections and provides:
+ * - Named collection references
+ * - A transaction wrapper (`withTransaction`)
+ * - A read-only MongoDB client accessor
  *
  * @param {Object} options
  * @param {{ uri: string, options: { dbName: string } }} options.config - MongoDB connection config
- * @param {Record<string, string>} options.collectionNames - Map of collection keys to MongoDB collection names
+ * @param {Record<string, string>} options.collectionNames - Map of keys to actual MongoDB collection names
  *
  * @returns {Promise<
  *   Record<string, import('mongodb').Collection> & {
- *     withTransaction: (action: ({ session: import('mongodb').ClientSession }) => Promise<void>) => Promise<void>,
+ *     withTransaction: <T>(action: ({ session: import('mongodb').ClientSession }) => Promise<T>) => Promise<T>,
  *     readonly client: import('mongodb').MongoClient
  *   }
  * >}
@@ -32,7 +35,7 @@ import { mongoConnect } from './connect.js'
  *   await logs.insertOne({ event: 'UserCreated', user: 'Alice' }, { session });
  * });
  *
- * await client.close(); // Close connection manually
+ * await client.close(); // Close connection manually when done
  */
 export const initializeMongoDb = async ({ config, collectionNames = {} }) => {
   const client = await mongoConnect(config)
@@ -48,17 +51,16 @@ export const initializeMongoDb = async ({ config, collectionNames = {} }) => {
 
   const withTransaction = async (action) => {
     const session = client.startSession()
-    let actionResponse
     try {
       session.startTransaction()
-      actionResponse = await action({ session })
+      const actionResponse = await action({ session })
       await session.commitTransaction()
+      return actionResponse
     } catch (error) {
       await session.abortTransaction()
       throw error
     } finally {
       await session.endSession()
-      return actionResponse
     }
   }
 

package/src/rabbit-mq/index.js

@@ -1,186 +1 @@
-import amqp from 'amqplib'
-import { v4 as uuidv4 } from 'uuid'
-
-/**
- * @typedef {Object} Log
- * @property {(msg: string) => void} info
- * @property {(msg: string, ...args: any[]) => void} error
- */
-
-/**
- * Connects to RabbitMQ server.
- * @param {{ host: string }} options
- * @returns {Promise<import('amqplib').Connection>}
- */
-export const connectQueueService = async ({ host }) => {
-  try {
-    return await amqp.connect(host)
-  } catch (error) {
-    console.error('Failed to connect to RabbitMQ:', error)
-    throw error
-  }
-}
-
-/**
- * Creates a channel from RabbitMQ connection.
- * @param {{ host: string }} options
- * @returns {Promise<amqp.Channel>}
- */
-export const createChannel = async ({ host }) => {
-  try {
-    const connection = await connectQueueService({ host })
-    return await connection.createChannel()
-  } catch (error) {
-    console.error('Failed to create channel:', error)
-    throw error
-  }
-}
-
-/**
- * Parses a RabbitMQ message.
- * @param {amqp.ConsumeMessage} msgInfo
- * @returns {{ msgId: string, data: any }}
- */
-const parseMessage = (msgInfo) => {
-  return JSON.parse(msgInfo.content.toString())
-}
-
-/**
- * Subscribes to a queue to receive messages.
- *
- * @param {Object} options
- * @param {import('amqplib').Channel} options.channel - RabbitMQ channel
- * @param {string} options.queue - Queue name to subscribe to
- * @param {(data: any) => Promise<void>} options.onReceive - Async handler for incoming message
- * @param {Log} options.log - Logging utility
- * @param {boolean} [options.nackOnError=false] - Whether to nack the message on error (default: false)
- * @param {number} [options.prefetch=1] - Max unacked messages per consumer (default: 1)
- *
- * @returns {Promise<void>}
- */
-export const subscribeToQueue = async ({
-  log,
-  queue,
-  channel,
-  prefetch = 1,
-  onReceive,
-  nackOnError = false,
-}) => {
-  try {
-    await channel.assertQueue(queue, { durable: true })
-
-    !!prefetch && (await channel.prefetch(prefetch))
-
-    channel.consume(queue, async (msgInfo) => {
-      if (!msgInfo) return
-
-      try {
-        const { msgId, data } = parseMessage(msgInfo)
-        log.info(`Handling message from '${queue}' msgId: ${msgId}`)
-        await onReceive(data)
-        channel.ack(msgInfo)
-      } catch (error) {
-        const { msgId } = parseMessage(msgInfo)
-        log.error(`Error handling message: ${msgId} on queue '${queue}'`)
-        log.error(error)
-        nackOnError ? channel.nack(msgInfo) : channel.ack(msgInfo)
-      }
-    })
-  } catch (error) {
-    console.error('Failed to subscribe to queue:', error)
-    throw error
-  }
-}
-
-/**
- * Initializes RabbitMQ integration with publish and subscribe support.
- *
- * @param {Object} options
- * @param {string} options.host - RabbitMQ connection URI (e.g., 'amqp://user:pass@localhost:5672')
- * @param {Log} options.log - Logging utility with `info()` and `error()` methods
- *
- * @returns {Promise<{
- *   publish: (queue: string, data: any) => Promise<boolean>,
- *   subscribe: (options: {
- *     queue: string,
- *     onReceive: (data: any) => Promise<void>,
- *     nackOnError?: boolean
- *   }) => Promise<void>,
- *   channel: amqp.Channel
- * }>}
- *
- * @example
- * const rabbit = await initializeQueue({ host, log });
- * await rabbit.publish('jobs', { task: 'sendEmail' });
- * await rabbit.subscribe({
- *   queue: 'jobs',
- *   onReceive: async (data) => { console.log(data); },
- * });
- */
-export const initializeQueue = async ({ host, log }) => {
-  const channel = await createChannel({ host })
-
-  /**
-   * Publishes a message to a queue.
-   * @param {string} queue
-   * @param {any} data
-   * @returns {Promise<boolean>}
-   */
-  const publish = async (queue, data) => {
-    const msgId = uuidv4()
-    try {
-      await channel.assertQueue(queue, { durable: true })
-      log.info(`Publishing to '${queue}' msgId: ${msgId}`)
-      return channel.sendToQueue(
-        queue,
-        Buffer.from(JSON.stringify({ msgId, data })),
-      )
-    } catch (error) {
-      log.error(`Error publishing to '${queue}' msgId: ${msgId}`)
-      log.error(error)
-      throw error
-    }
-  }
-
-  /**
-   * Subscribes to a queue.
-   * @param {{
-   *   queue: string,
-   *   onReceive: (data: any) => Promise<void>,
-   *   nackOnError?: boolean
-   * }} options
-   * @returns {Promise<void>}
-   */
-  const subscribe = async ({ queue, onReceive, nackOnError = false }) => {
-    return subscribeToQueue({ channel, queue, onReceive, log, nackOnError })
-  }
-
-  return {
-    channel,
-    publish,
-    subscribe,
-  }
-}
-
-/**
- * Builds RabbitMQ URI from environment variables.
- * @param {{
- *   RABBIT_HOST: string,
- *   RABBIT_PORT: string | number,
- *   RABBIT_USERNAME: string,
- *   RABBIT_PASSWORD: string,
- *   RABBIT_PROTOCOL?: string
- * }} env
- * @returns {string}
- */
-export const rabbitUriFromEnv = (env) => {
-  const {
-    RABBIT_HOST,
-    RABBIT_PORT,
-    RABBIT_USERNAME,
-    RABBIT_PASSWORD,
-    RABBIT_PROTOCOL = 'amqp',
-  } = env
-
-  return `${RABBIT_PROTOCOL}://${RABBIT_USERNAME}:${RABBIT_PASSWORD}@${RABBIT_HOST}:${RABBIT_PORT}`
-}
+export * from './rabbit-mq.js'