core-services-sdk 1.3.7 → 1.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
@@ -19,16 +19,17 @@
   "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",
+    "@sendgrid/mail": "^8.1.5",
     "amqplib": "^0.10.8",
-    "aws-sdk": "^2.1692.0",
     "crypto": "^1.0.1",
     "dot": "^1.1.3",
     "fastify": "^5.4.0",
     "http-status": "^2.1.0",
-    "mongodb": "^6.17.0",
+    "mongodb": "^6.18.0",
     "node-fetch": "^3.3.2",
     "nodemailer": "^7.0.5",
-    "nodemailer-sendgrid-transport": "^0.2.0",
     "pino": "^9.7.0",
     "uuid": "^11.1.0",
     "xml2js": "^0.6.2"
@@ -39,4 +40,4 @@
     "url": "^0.11.4",
     "vitest": "^3.2.4"
   }
-}
+}

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,9 +1,10 @@
-import aws from 'aws-sdk'
 import nodemailer from 'nodemailer'
-import sgTransport from 'nodemailer-sendgrid-transport'
+import sgMail from '@sendgrid/mail'
+import { defaultProvider } from '@aws-sdk/credential-provider-node'
+import { SESClient, SendRawEmailCommand } from '@aws-sdk/client-ses'
 
 /**
- * Factory for creating Nodemailer transporters based on configuration.
+ * Factory for creating email transporters based on configuration.
  */
 export class TransportFactory {
   /**
@@ -29,8 +30,9 @@ export class TransportFactory {
    * @param {string} config.secretAccessKey - AWS secret
    * @param {string} config.region - AWS region
    *
-   * @returns {import('nodemailer').Transporter}
+   * @returns {import('nodemailer').Transporter | typeof import('@sendgrid/mail')}
    */
+
   static create(config) {
     switch (config.type) {
       case 'smtp':
@@ -48,19 +50,31 @@ export class TransportFactory {
         })
 
       case 'sendgrid':
-        return nodemailer.createTransport(
-          sgTransport({
-            auth: { api_key: config.apiKey },
-          }),
-        )
+        if (!config.apiKey) {
+          throw new Error('Missing SendGrid API key')
+        }
+        sgMail.setApiKey(config.apiKey)
+        return sgMail // Not a Nodemailer transport, but SendGrid's mail API
 
-      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: sesClient,
+            aws: { SendRawEmailCommand },
+          },
         })
-        return nodemailer.createTransport({ SES: { ses, aws } })
+      }
 
       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
     }
   }