core-services-sdk 1.3.2 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
@@ -21,12 +21,15 @@
   "dependencies": {
     "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",
     "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"
   },

package/src/core/combine-unique-arrays.js

@@ -0,0 +1,15 @@
+/**
+ * Combines multiple arrays into a single flat array with unique values.
+ *
+ * Removes duplicate entries and preserves the order of first appearance.
+ *
+ * @param {...Array<any>} lists - One or more arrays to combine.
+ * @returns {Array<any>} A new array containing unique values from all input arrays.
+ *
+ * @example
+ * combineUniqueArrays([1, 2, 3], [3, 4], [5]) // [1, 2, 3, 4, 5]
+ * combineUniqueArrays(['a', 'b'], ['b', 'c']) // ['a', 'b', 'c']
+ */
+export const combineUniqueArrays = (...lists) => {
+  return Array.from(new Set(lists.flat()))
+}

package/src/core/index.js

@@ -0,0 +1,5 @@
+export * from './regex-utils.js'
+export * from './otp-generators.js'
+export * from './sanitize-objects.js'
+export * from './normalize-to-array.js'
+export * from './combine-unique-arrays.js'

package/src/core/normalize-to-array.js

@@ -0,0 +1,31 @@
+/**
+ * Normalizes an input value to an array of trimmed, non-empty strings.
+ *
+ * - If the input is `undefined` or `null`, returns an empty array.
+ * - If the input is an array, it trims each string element and filters out empty values.
+ * - If the input is a string (or coercible to string), it splits it by commas,
+ *   trims each item, and filters out empty values.
+ *
+ * @param {any} value - The value to normalize. Can be a string, array, or any other type.
+ * @returns {string[]} An array of trimmed, non-empty strings.
+ *
+ * @example
+ * normalizeToArray('a,b, c , ,d') // ['a', 'b', 'c', 'd']
+ * normalizeToArray([' a ', 'b', '', '   ']) // ['a', 'b']
+ * normalizeToArray(null) // []
+ * normalizeToArray(123) // ['123']
+ */
+export const normalizeToArray = (value) => {
+  if (value === undefined || value === null) {
+    return []
+  }
+
+  const isArray = Array.isArray(value)
+  const rawArray = isArray ? value : String(value).split(',')
+
+  const arrayFiltered = rawArray
+    .map((item) => (typeof item === 'string' ? item.trim() : ''))
+    .filter(Boolean)
+
+  return arrayFiltered
+}

package/src/core/otp-generators.js

@@ -0,0 +1,113 @@
+const numeric = '0123456789'
+const symbols = '!@#$%^&*()_+-=[]{}|;:,.<>?'
+const alphaLower = 'abcdefghijklmnopqrstuvwxyz'
+const alphaUpper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+const alphanumericSymbols = `${alphaLower}${alphaUpper}${numeric}${symbols}`
+
+export const OTP_GENERATOR_TYPES = Object.freeze({
+  any: 'any',
+  alpha: 'alpha',
+  numeric: 'numeric',
+  symbols: 'symbols',
+  alphaLower: 'alphaLower',
+  alphaUpper: 'alphaUpper',
+  alphanumeric: 'alphanumeric',
+  alphanumericSymbols: 'alphanumericSymbols',
+})
+
+const types = Object.freeze({
+  [OTP_GENERATOR_TYPES.numeric]: numeric,
+  [OTP_GENERATOR_TYPES.symbols]: symbols,
+  [OTP_GENERATOR_TYPES.alphaLower]: alphaLower,
+  [OTP_GENERATOR_TYPES.alphaUpper]: alphaUpper,
+  [OTP_GENERATOR_TYPES.any]: alphanumericSymbols,
+  [OTP_GENERATOR_TYPES.alpha]: `${alphaLower}${alphaUpper}`,
+  [OTP_GENERATOR_TYPES.alphanumericSymbols]: alphanumericSymbols,
+  [OTP_GENERATOR_TYPES.alphanumeric]: `${alphaLower}${alphaUpper}${numeric}`,
+})
+
+/**
+ * Generates a one-time password (OTP) code based on a specified type or character set.
+ *
+ * @param {Object} [options={}] - The options object.
+ * @param {number} [options.length=4] - The desired length of the generated code (1-30).
+ * @param {string} [options.type='numeric'] - The type of characters to use. One of:
+ *  'any', 'alpha', 'numeric', 'symbols', 'alphaLower', 'alphaUpper', 'alphanumeric', 'alphanumericSymbols'.
+ * @param {string} [options.charset] - A custom string of characters to use instead of the predefined types.
+ * @returns {string} The generated code.
+ * @throws {Error} If the length is not a number between 1 and 30.
+ * @throws {Error} If charset is provided and is not a non-empty string.
+ * @throws {Error} If the type is invalid and no valid charset is provided.
+ */
+export function generateCode({ length = 4, type = 'numeric', charset } = {}) {
+  const max = 30
+  const min = 1
+
+  if (typeof length !== 'number' || length < min || length > max) {
+    throw new Error(`length must be a number between ${min} and ${max}`)
+  }
+
+  if (charset !== undefined) {
+    if (typeof charset !== 'string') {
+      throw new Error('charset must be a string if provided')
+    }
+    if (charset.length === 0) {
+      throw new Error('charset must not be empty')
+    }
+  }
+
+  const chars = charset || types[type]
+  if (!chars) {
+    throw new Error(
+      `type must be one of: ${Object.keys(types)
+        .map((t) => `'${t}'`)
+        .join(', ')}`,
+    )
+  }
+
+  return Array.from(
+    { length },
+    () => chars[Math.floor(Math.random() * chars.length)],
+  ).join('')
+}
+
+/**
+ * Generates an OTP code using alphabetic characters (both lowercase and uppercase).
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlpha(length = 4) {
+  return generateCode({ length, type: 'alpha' })
+}
+
+/**
+ * Generates an OTP code using only numeric digits (0-9).
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeDigits(length = 4) {
+  return generateCode({ length, type: 'numeric' })
+}
+
+/**
+ * Generates an OTP code using alphabetic characters and digits.
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlphaNumeric(length = 4) {
+  return generateCode({ length, type: 'alphanumeric' })
+}
+
+/**
+ * Generates an OTP code using alphabetic characters, digits, and symbols.
+ *
+ * @param {number} [length=4] - The desired length of the code.
+ * @returns {string} The generated code.
+ */
+export function generateCodeAlphaNumericSymbols(length = 4) {
+  return generateCode({ length, type: 'any' })
+}

package/src/core/regex-utils.js

@@ -0,0 +1,27 @@
+/**
+ * Checks whether the given input is a valid regular expression.
+ *
+ * - If the input is an instance of `RegExp`, returns `true`.
+ * - If the input is a string, attempts to create a `RegExp` object from it and returns `true` if valid.
+ * - Returns `false` for any other types or if the string is an invalid regex pattern.
+ *
+ * @param {string | RegExp} pattern - The regex pattern to validate, either as a string or a RegExp object.
+ * @returns {boolean} `true` if the pattern is a valid regular expression, otherwise `false`.
+ *
+ * @example
+ * isValidRegex('^[a-z]+$')       // true
+ * isValidRegex(/^[a-z]+$/)       // true
+ * isValidRegex('[')              // false
+ * isValidRegex(123)              // false
+ */
+
+export const isValidRegex = (pattern) => {
+  if (pattern instanceof RegExp) return true
+  if (typeof pattern !== 'string') return false
+  try {
+    new RegExp(pattern)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/core/sanitize-objects.js

@@ -0,0 +1,50 @@
+/**
+ * Creates a new object containing only the key-value pairs that pass the provided filter function.
+ *
+ * @param {Object} obj - The object to sanitize.
+ * @param {(entry: [string, any]) => boolean} filter - A function that determines whether to include each `[key, value]` entry.
+ * @returns {Object} A new object with only the filtered entries.
+ *
+ * @example
+ * sanitizeObject({ a: 1, b: undefined }, ([, v]) => v !== undefined) // { a: 1 }
+ */
+export const sanitizeObject = (obj, filter) =>
+  Object.fromEntries(Object.entries(obj).filter(filter))
+
+/**
+ * Removes all properties from the object whose values are `undefined`.
+ *
+ * @param {Object} obj - The object to sanitize.
+ * @returns {Object} A new object without `undefined` values.
+ *
+ * @example
+ * sanitizeUndefinedFields({ a: 1, b: undefined }) // { a: 1 }
+ */
+export const sanitizeUndefinedFields = (obj) =>
+  sanitizeObject(obj, ([, value]) => value !== undefined)
+
+/**
+ * Returns a new object containing only the specified allowed properties.
+ *
+ * @param {Object} obj - The original object.
+ * @param {string[]} [allowedFields=[]] - An array of property names to retain.
+ * @returns {Object} A new object containing only the allowed properties.
+ *
+ * @example
+ * sanitizeObjectAllowProps({ a: 1, b: 2 }, ['a']) // { a: 1 }
+ */
+export const sanitizeObjectAllowProps = (obj, allowedFields = []) =>
+  sanitizeObject(obj, ([key]) => allowedFields.includes(key))
+
+/**
+ * Returns a new object excluding the specified disallowed properties.
+ *
+ * @param {Object} obj - The original object.
+ * @param {string[]} [disallowedFields=[]] - An array of property names to exclude.
+ * @returns {Object} A new object without the disallowed properties.
+ *
+ * @example
+ * sanitizeObjectDisallowProps({ a: 1, b: 2 }, ['b']) // { a: 1 }
+ */
+export const sanitizeObjectDisallowProps = (obj, disallowedFields = []) =>
+  sanitizeObject(obj, ([key]) => !disallowedFields.includes(key))

package/src/crypto/crypto.js

@@ -0,0 +1,128 @@
+import { promisify } from 'util'
+import { randomBytes, scrypt } from 'crypto'
+
+const scryptPromisify = promisify(scrypt)
+
+const keyLength = 64
+const baseFormat = 'hex'
+
+/**
+ * Generates a cryptographically secure random salt as a Buffer.
+ *
+ * @param {number} length - The length of the salt in bytes.
+ * @returns {Buffer} A Buffer containing random bytes.
+ *
+ * @example
+ * const salt = getSalt(16)
+ * console.log(salt.toString('hex')) // 'e4b1c9...'
+ */
+export const getSalt = (length) => {
+  return randomBytes(length)
+}
+
+/**
+ * Generates a cryptographically secure random salt and returns it as a hexadecimal string.
+ *
+ * @param {number} length - The length of the salt in bytes.
+ * @returns {string} The salt encoded as a hexadecimal string.
+ *
+ * @example
+ * const saltHex = getSaltHex(16)
+ * console.log(saltHex) // 'e4b1c9...'
+ */
+export const getSaltHex = (length) => {
+  return getSalt(length).toString(baseFormat)
+}
+
+/**
+ * Encrypts a given expression using scrypt with a provided salt.
+ *
+ * @param {Object} options - The encryption options.
+ * @param {string} options.expression - The expression to encrypt (e.g., a password).
+ * @param {string} options.salt - The salt to use (as a string).
+ * @param {number} [options.length=64] - The desired key length in bytes for the derived key.
+ * @returns {Promise<Buffer>} A Promise that resolves to the derived key as a Buffer.
+ *
+ * @example
+ * const buffer = await getEncryptedBuffer({
+ *   expression: 'my-password',
+ *   salt: 'somesalt',
+ *   length: 32
+ * })
+ * console.log(buffer.toString('hex'))
+ */
+export const getEncryptedBuffer = async ({
+  salt,
+  expression,
+  length = keyLength,
+}) => {
+  const encryptedExpression = await scryptPromisify(expression, salt, length)
+
+  return encryptedExpression
+}
+
+/**
+ * Encrypts a string expression (e.g., password) using scrypt and returns the result as a hexadecimal string.
+ *
+ * Optionally appends a `passwordPrivateKey` to the salt for extra security.
+ *
+ * @param {Object} options
+ * @param {string} options.expression - The expression to encrypt.
+ * @param {string} options.salt - The salt string.
+ * @param {string} [options.passwordPrivateKey] - Optional extra key to enhance the salt.
+ * @returns {Promise<string>} A Promise that resolves to the encrypted expression as a hex string.
+ *
+ * @example
+ * const encrypted = await encrypt({
+ *   expression: 'my-password',
+ *   salt: 'abc123',
+ *   passwordPrivateKey: 'my-secret-key'
+ * })
+ * console.log(encrypted) // '9af0a1b23c...'
+ */
+export const encrypt = async ({ salt, expression, passwordPrivateKey }) => {
+  const encryptedExpression = await getEncryptedBuffer({
+    expression,
+    salt: `${salt}${passwordPrivateKey ? passwordPrivateKey : ''}`,
+  })
+
+  return encryptedExpression.toString(baseFormat)
+}
+
+/**
+ * Compares a plain-text password to an already encrypted one using scrypt.
+ *
+ * Re-encrypts the input password using the provided salt and optional private key,
+ * then compares it to the stored encrypted password.
+ *
+ * @param {Object} options
+ * @param {string} options.salt - The salt used during encryption.
+ * @param {string} options.password - The plain-text password to validate.
+ * @param {string} options.encryptedPassword - The previously encrypted password (hex string).
+ * @param {string} [options.passwordPrivateKey] - Optional private key used in encryption.
+ * @returns {Promise<boolean>} A Promise that resolves to `true` if passwords match, otherwise `false`.
+ *
+ * @example
+ * const isValid = await isPasswordMatch({
+ *   password: 'my-password',
+ *   salt: 'abc123',
+ *   encryptedPassword: '9af0a1b23c...',
+ *   passwordPrivateKey: 'my-secret-key'
+ * })
+ * console.log(isValid) // true or false
+ */
+export const isPasswordMatch = async ({
+  salt,
+  password,
+  encryptedPassword,
+  passwordPrivateKey,
+}) => {
+  const encryptedCurrentPassword = await getEncryptedBuffer({
+    expression: password,
+    salt: `${salt}${passwordPrivateKey ? passwordPrivateKey : ''}`,
+  })
+  const isMatch = encryptedCurrentPassword.equals(
+    Buffer.from(encryptedPassword, baseFormat),
+  )
+  return isMatch
+}

package/src/crypto/encryption.js

@@ -0,0 +1,48 @@
+import { encrypt, getSaltHex } from './crypto.js'
+
+/**
+ * Encrypts a plain-text password using scrypt and a salt.
+ *
+ * This function generates a random salt (in hex) of the specified length,
+ * appends an optional passwordPrivateKey (if provided),
+ * and uses the Node.js `crypto.scrypt` algorithm to encrypt the password.
+ *
+ * @async
+ * @function encryptPassword
+ *
+ * @param {Object} input - The input object containing the password.
+ * @param {string} input.password - The plain-text password to encrypt.
+ *
+ * @param {Object} options - Configuration options for encryption.
+ * @param {number} options.saltLength - The desired length of the generated salt (in bytes).
+ * @param {string} [options.passwordPrivateKey] - An optional private key to strengthen the salt.
+ *
+ * @returns {Promise<Object>} An object containing:
+ * - `salt` {string} The generated salt in hex format.
+ * - `password` {string} The encrypted password in hex format.
+ *
+ * @example
+ * const result = await encryptPassword(
+ *   { password: 'mySecretPassword' },
+ *   { saltLength: 16, passwordPrivateKey: 'abc123' }
+ * );
+ * console.log(result); // { salt: 'f3ab...', password: '8e1f...' }
+ */
+
+export const encryptPassword = async (
+  { password },
+  { saltLength, passwordPrivateKey },
+) => {
+  const salt = getSaltHex(saltLength)
+
+  const encrypted = await encrypt({
+    salt,
+    passwordPrivateKey,
+    expression: password,
+  })
+
+  return {
+    salt,
+    password: encrypted,
+  }
+}

package/src/crypto/index.js

@@ -0,0 +1,2 @@
+export * from './crypto.js'
+export * from './encryption.js'

package/src/fastify/error-handlers/with-error-handling.js

@@ -1,7 +1,11 @@
 import httpStatus from 'http-status'
 
-import { HttpError } from '../../http/HttpError.js'
 import { GENERAL_ERROR } from '../error-codes.js'
+import { HttpError } from '../../http/HttpError.js'
+
+/** @typedef {import('fastify').FastifyReply} Reply */
+/** @typedef {import('fastify').FastifyRequest} Request */
+/** @typedef {import('pino').Logger} Logger */
 
 /**
  * Generic error-handling wrapper that logs and throws a safe error.

package/src/ids/generators.js

@@ -0,0 +1,73 @@
+import { v4 as uuidv4 } from 'uuid'
+import { ID_PREFIXES } from './prefixes.js'
+
+/**
+ * Generates a new UUID v4 string.
+ *
+ * @returns {string} A new UUID (version 4).
+ *
+ * @example
+ * generateId() // '550e8400-e29b-41d4-a716-446655440000'
+ */
+export const generateId = () => {
+  return uuidv4()
+}
+
+/**
+ * Generates a unique ID with the given prefix.
+ *
+ * @param {string} prefix - A prefix string to prepend to the UUID.
+ * @returns {string} A unique ID in the format `${prefix}_${uuid}`.
+ *
+ * @example
+ * generatePrefixedId('usr') // 'usr_550e8400-e29b-41d4-a716-446655440000'
+ */
+export const generatePrefixedId = (prefix) => {
+  return `${prefix}_${generateId()}`
+}
+
+/**
+ * Generates a user ID with a `usr_` prefix.
+ *
+ * @returns {string} A user ID.
+ */
+export const generateUserId = () => generatePrefixedId(ID_PREFIXES.USER)
+
+/**
+ * Generates a tenant ID with a `tnt_` prefix.
+ *
+ * @returns {string} A tenant ID.
+ */
+export const generateTenantId = () => generatePrefixedId(ID_PREFIXES.TENANT)
+
+/**
+ * Generates a permission ID with a `prm_` prefix.
+ *
+ * @returns {string} A permission ID.
+ */
+export const generatePermissionId = () =>
+  generatePrefixedId(ID_PREFIXES.PERMISSION)
+
+/**
+ * Generates a correlation ID with a `crln_` prefix.
+ *
+ * @returns {string} A correlation ID.
+ */
+export const generateCorrelationId = () =>
+  generatePrefixedId(ID_PREFIXES.CORRELATION)
+
+/**
+ * Generates a verification ID with a `vrf_` prefix.
+ *
+ * @returns {string} A verification ID.
+ */
+export const generateVerificationId = () =>
+  generatePrefixedId(ID_PREFIXES.VERIFICATION)
+
+/**
+ * Generates a role permissions ID with a `role_` prefix.
+ *
+ * @returns {string} A role permissions ID.
+ */
+export const generateRolePermissionsId = () =>
+  generatePrefixedId(ID_PREFIXES.ROLE_PERMISSIONS)

package/src/ids/prefixes.js

@@ -0,0 +1,28 @@
+/**
+ * Mapping of entity types to their unique ID prefixes.
+ *
+ * These prefixes are prepended to UUIDs to create consistent and identifiable IDs across the system.
+ * For example: 'usr_550e8400-e29b-41d4-a716-446655440000'
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const ID_PREFIXES = Object.freeze({
+  /** User entity ID prefix */
+  USER: 'usr',
+
+  /** Tenant entity ID prefix */
+  TENANT: 'tnt',
+
+  /** Permission entity ID prefix */
+  PERMISSION: 'prm',
+
+  /** Correlation ID prefix (e.g., for tracing requests) */
+  CORRELATION: 'crln',
+
+  /** Verification entity ID prefix (e.g., email/phone code) */
+  VERIFICATION: 'vrf',
+
+  /** Role-permissions mapping ID prefix */
+  ROLE_PERMISSIONS: 'role',
+})

package/src/index.js

@@ -1,6 +1,8 @@
+export * from './core/index.js'
+export * from './crypto/index.js'
+export * from './logger/index.js'
 export * from './fastify/index.js'
 export * from './mongodb/index.js'
-export * from './mongodb/connect.js'
 export * from './rabbit-mq/index.js'
 export * as http from './http/http.js'
 export * from './http/responseType.js'

package/src/logger/get-logger.js

@@ -0,0 +1,64 @@
+import pino from 'pino'
+
+const requiredMethods = ['info', 'warn', 'error', 'debug']
+
+const dummyLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}
+
+/**
+ * @param {any} logger
+ * @returns {boolean}
+ */
+const isValidLogger = (logger) =>
+  typeof logger === 'object' &&
+  requiredMethods.every((method) => typeof logger[method] === 'function')
+
+/**
+ * Creates or returns a logger instance based on user-provided options.
+ *
+ * Supported usages:
+ * - `undefined` → pino with level 'info'
+ * - `true` → pino with level 'info'
+ * - `{ logger: true, level?: string }` → pino with given level
+ * - `{ logger: LoggerObject }` → use provided logger
+ * - fallback → dummy logger
+ *
+ * @param {true | Object | undefined} option
+ * @returns {import('pino').Logger | typeof dummyLogger}
+ */
+export const getLogger = (option) => {
+  // No option provided or just true: use pino default
+  if (option === undefined || option === true) {
+    const logger = pino({ level: 'info' })
+    logger.info(
+      '[getLogger] No logger config provided. Using default Pino logger (level: info).',
+    )
+    return logger
+  }
+
+  // Option object provided
+  if (typeof option === 'object') {
+    const { logger, level } = option
+
+    // User asked for internal pino with level
+    if (logger === true) {
+      const pinoLogger = pino({ level: level || 'info' })
+      pinoLogger.info(
+        `[getLogger] Using internal Pino logger (level: ${level || 'info'}).`,
+      )
+      return pinoLogger
+    }
+
+    // User supplied a custom logger
+    if (isValidLogger(logger)) {
+      return logger
+    }
+  }
+
+  // Invalid or no-op fallback
+  return dummyLogger
+}

package/src/logger/index.js

@@ -0,0 +1 @@
+export * from './get-logger.js'

package/src/mailer/transport.factory.js

@@ -2,9 +2,33 @@ import aws from 'aws-sdk'
 import nodemailer from 'nodemailer'
 import sgTransport from 'nodemailer-sendgrid-transport'
 
+/**
+ * Factory for creating Nodemailer transporters based on configuration.
+ */
 export class TransportFactory {
   /**
-   * @param {object} config
+   * Create a Nodemailer transporter
+   *
+   * @param {object} config - Transport configuration object
+   * @param {'smtp' | 'gmail' | 'sendgrid' | 'ses'} config.type - Type of email transport
+   *
+   * For type 'smtp':
+   * @param {string} config.host - SMTP server host
+   * @param {number} config.port - SMTP server port
+   * @param {boolean} config.secure - Use TLS
+   * @param {{ user: string, pass: string }} config.auth - SMTP auth credentials
+   *
+   * For type 'gmail':
+   * @param {{ user: string, pass: string }} config.auth - Gmail credentials
+   *
+   * For type 'sendgrid':
+   * @param {string} config.apiKey - SendGrid API key
+   *
+   * For type 'ses':
+   * @param {string} config.accessKeyId - AWS access key
+   * @param {string} config.secretAccessKey - AWS secret
+   * @param {string} config.region - AWS region
+   *
    * @returns {import('nodemailer').Transporter}
    */
   static create(config) {