core-services-sdk 1.3.21 → 1.3.23

package/.vscode/settings.json

@@ -16,6 +16,6 @@
   "eslint.validate": ["javascript"],
 
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true
+    "source.fixAll.eslint": "explicit"
   }
 }

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.21",
+  "version": "1.3.23",
   "main": "src/index.js",
   "type": "module",
+  "types": "types/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run --coverage",
     "format": "prettier --write .",
-    "bump": "node ./scripts/bump-version.js"
+    "bump": "node ./scripts/bump-version.js",
+    "build:types": "tsc --declaration --allowJs --emitDeclarationOnly --outDir types ./src/index.js"
   },
   "repository": {
     "type": "git",
@@ -34,17 +36,19 @@
     "mongodb": "^6.18.0",
     "nodemailer": "^7.0.5",
     "pino": "^9.7.0",
+    "ulid": "^3.0.1",
     "uuid": "^11.1.0",
     "xml2js": "^0.6.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.2.4",
-    "path": "^0.12.7",
-    "url": "^0.11.4",
-    "vitest": "^3.2.4",
     "eslint": "^9.30.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-prettier": "^5.5.1",
-    "prettier": "^3.6.2"
+    "path": "^0.12.7",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "url": "^0.11.4",
+    "vitest": "^3.2.4"
   }
-}
+}

package/src/ids/generators.js

@@ -1,26 +1,28 @@
-import { v4 as uuidv4 } from 'uuid'
+import { ulid } from 'ulid'
 import { ID_PREFIXES } from './prefixes.js'
 
 /**
- * Generates a new UUID v4 string.
+ * Generates a new ULID string.
  *
- * @returns {string} A new UUID (version 4).
+ * ULIDs are 26-character, lexicographically sortable identifiers.
+ *
+ * @returns {string} A new ULID.
  *
  * @example
- * generateId() // '550e8400-e29b-41d4-a716-446655440000'
+ * generateId() // '01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
  */
 export const generateId = () => {
-  return uuidv4()
+  return ulid()
 }
 
 /**
  * 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}`.
+ * @param {string} prefix - A prefix string to prepend to the ULID.
+ * @returns {string} A unique ID in the format `${prefix}_${ulid}`.
  *
  * @example
- * generatePrefixedId('usr') // 'usr_550e8400-e29b-41d4-a716-446655440000'
+ * generatePrefixedId('usr') // 'usr_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
  */
 export const generatePrefixedId = (prefix) => {
   return `${prefix}_${generateId()}`
@@ -73,9 +75,9 @@ export const generateRolePermissionsId = () =>
   generatePrefixedId(ID_PREFIXES.ROLE_PERMISSIONS)
 
 /**
- * Generates a onboarding ID with a `onb_` prefix.
+ * Generates an onboarding ID with a `onb_` prefix.
  *
- * @returns {string} A onboarding ID.
+ * @returns {string} An onboarding ID.
  */
 export const generateOnboardingId = () =>
   generatePrefixedId(ID_PREFIXES.ONBOARDING)
@@ -83,6 +85,6 @@ export const generateOnboardingId = () =>
 /**
  * Generates a session ID with a `sess_` prefix.
  *
- * @returns {string} A onboarding ID.
+ * @returns {string} A session ID.
  */
 export const generateSessionId = () => generatePrefixedId(ID_PREFIXES.SESSION)

package/src/ids/prefixes.js

@@ -1,8 +1,8 @@
 /**
  * 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'
+ * These prefixes are prepended to ULIDs to create consistent and identifiable IDs across the system.
+ * For example: 'usr_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
  *
  * @readonly
  * @enum {string}

package/src/index.js

@@ -8,3 +8,4 @@ export * from './logger/index.js'
 export * from './mailer/index.js'
 export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
+export * from './util/index.js'

package/src/rabbit-mq/rabbit-mq.js

@@ -1,48 +1,83 @@
 // @ts-nocheck
 import * as amqp from 'amqplib'
-import { v4 as uuidv4 } from 'uuid'
+import { ulid } from 'ulid'
 
 /**
  * @typedef {Object} Log
- * @property {(msg: string) => void} info
- * @property {(msg: string, ...args: any[]) => void} error
+ * @property {(obj: any, msg?: string) => void} info
+ * @property {(obj: any, msg?: string) => void} error
+ * @property {(obj: any, msg?: string) => void} debug
  */
 
+const generateMsgId = () => `rbt_${ulid()}`
+
 /**
- * Connects to RabbitMQ server.
- * @param {{ host: string }} options
+ * Connects to a RabbitMQ server.
+ *
+ * @param {{ host: string, log: import('pino').Logger }} options
  * @returns {Promise<amqp.Connection>}
  */
-export const connectQueueService = async ({ host }) => {
+export const connectQueueService = async ({ host, log }) => {
+  const t0 = Date.now()
+  const logger = log.child({ op: 'connectQueueService', host })
+
   try {
-    return await amqp.connect(host)
-  } catch (error) {
-    console.error('Failed to connect to RabbitMQ:', error)
-    throw error
+    logger.debug('start')
+    const connection = await amqp.connect(host)
+
+    logger.info({
+      event: 'ok',
+      ms: Date.now() - t0,
+    })
+
+    return connection
+  } catch (err) {
+    logger.error(err, {
+      event: 'error',
+      ms: Date.now() - t0,
+    })
+    throw err
   }
 }
 
 /**
- * Creates a channel from RabbitMQ connection.
- * @param {{ host: string }} options
+ * Creates a channel from a RabbitMQ connection.
+ *
+ * @param {{ host: string, log: import('pino').Logger }} options
  * @returns {Promise<amqp.Channel>}
  */
-export const createChannel = async ({ host }) => {
+export const createChannel = async ({ host, log }) => {
+  const t0 = Date.now()
+  const logger = log.child({ op: 'createChannel', host })
+
   try {
+    logger.debug('start')
     const connection = /** @type {amqp.Connection} */ (
-      await connectQueueService({ host })
+      await connectQueueService({ host, log })
     )
-    return await connection.createChannel()
-  } catch (error) {
-    console.error('Failed to create channel:', error)
-    throw error
+    const channel = await connection.createChannel()
+
+    logger.debug('channel-created')
+    logger.info({
+      event: 'ok',
+      ms: Date.now() - t0,
+    })
+
+    return channel
+  } catch (err) {
+    logger.error(err, {
+      event: 'error',
+      ms: Date.now() - t0,
+    })
+    throw err
   }
 }
 
 /**
- * Parses a RabbitMQ message.
+ * Parses a RabbitMQ message into a structured object.
+ *
  * @param {amqp.ConsumeMessage} msgInfo
- * @returns {{ msgId: string, data: any }}
+ * @returns {{ msgId: string, data: any, correlationId?: string }}
  */
 const parseMessage = (msgInfo) => {
   return JSON.parse(msgInfo.content.toString())
@@ -54,8 +89,8 @@ const parseMessage = (msgInfo) => {
  * @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 {(data: any, correlationId?: string) => Promise<void>} options.onReceive - Async handler
+ * @param {import('pino').Logger} options.log - Base logger
  * @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)
  *
@@ -69,31 +104,48 @@ export const subscribeToQueue = async ({
   onReceive,
   nackOnError = false,
 }) => {
+  const logger = log.child({ op: 'subscribeToQueue', queue })
+
   try {
     await channel.assertQueue(queue, { durable: true })
-
     !!prefetch && (await channel.prefetch(prefetch))
 
     channel.consume(queue, async (msgInfo) => {
       if (!msgInfo) {
         return
       }
+      const t0 = Date.now()
+
+      const { msgId, data, correlationId } = parseMessage(msgInfo)
+      const child = logger.child({ msgId, correlationId })
 
       try {
-        const { msgId, data } = parseMessage(msgInfo)
-        log.info(`Handling message from '${queue}' msgId: ${msgId}`)
-        await onReceive(data)
+        child.debug('start')
+        child.info('message-received')
+
+        await onReceive(data, correlationId)
         channel.ack(msgInfo)
-      } catch (error) {
-        const { msgId } = parseMessage(msgInfo)
-        log.error(`Error handling message: ${msgId} on queue '${queue}'`)
-        log.error(error)
+
+        child.info({
+          event: 'ok',
+          ms: Date.now() - t0,
+        })
+        return
+      } catch (err) {
         nackOnError ? channel.nack(msgInfo) : channel.ack(msgInfo)
+
+        child.error(err, {
+          event: 'error',
+          ms: Date.now() - t0,
+        })
+        return
       }
     })
-  } catch (error) {
-    console.error('Failed to subscribe to queue:', error)
-    throw error
+  } catch (err) {
+    logger.error(err, {
+      event: 'error',
+    })
+    throw err
   }
 }
 
@@ -101,57 +153,73 @@ export const subscribeToQueue = async ({
  * 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
+ * @param {string} options.host - RabbitMQ connection URI
+ * @param {import('pino').Logger} options.log - Logger
  *
  * @returns {Promise<{
- *   publish: (queue: string, data: any) => Promise<boolean>,
+ *   publish: (queue: string, data: any, correlationId?: string) => Promise<boolean>,
  *   subscribe: (options: {
  *     queue: string,
- *     onReceive: (data: any) => Promise<void>,
+ *     onReceive: (data: any, correlationId?: string) => 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 })
+  const channel = await createChannel({ host, log })
+  const logger = log.child({ op: 'initializeQueue' })
 
   /**
-   * Publishes a message to a queue.
-   * @param {string} queue
-   * @param {any} data
-   * @returns {Promise<boolean>}
+   * Publishes a message to a queue with a generated `rbt_<ulid>` ID.
+   *
+   * @param {string} queue - Queue name
+   * @param {any} data - Payload to send
+   * @param {string} [correlationId] - Correlation ID for tracing
+   * @returns {Promise<boolean>} True if the message was sent successfully
    */
-  const publish = async (queue, data) => {
-    const msgId = uuidv4()
+  const publish = async (queue, data, correlationId) => {
+    const msgId = generateMsgId()
+    const t0 = Date.now()
+    const logChild = logger.child({
+      op: 'publish',
+      queue,
+      msgId,
+      correlationId,
+    })
+
     try {
+      logChild.debug('start')
+
       await channel.assertQueue(queue, { durable: true })
-      log.info(`Publishing to '${queue}' msgId: ${msgId}`)
-      return channel.sendToQueue(
+      const payload = { msgId, data, correlationId }
+      const sent = channel.sendToQueue(
         queue,
-        Buffer.from(JSON.stringify({ msgId, data })),
+        Buffer.from(JSON.stringify(payload)),
       )
-    } catch (error) {
-      log.error(`Error publishing to '${queue}' msgId: ${msgId}`)
-      log.error(error)
-      throw error
+
+      logChild.debug('message-sent')
+      logChild.info({
+        event: 'ok',
+        ms: Date.now() - t0,
+      })
+
+      return sent
+    } catch (err) {
+      logChild.error(err, {
+        event: 'error',
+        ms: Date.now() - t0,
+      })
+      throw err
     }
   }
 
   /**
-   * Subscribes to a queue.
+   * Subscribes to a queue for incoming messages.
+   *
    * @param {{
    *   queue: string,
-   *   onReceive: (data: any) => Promise<void>,
+   *   onReceive: (data: any, correlationId?: string) => Promise<void>,
    *   nackOnError?: boolean
    * }} options
    * @returns {Promise<void>}
@@ -168,7 +236,8 @@ export const initializeQueue = async ({ host, log }) => {
 }
 
 /**
- * Builds RabbitMQ URI from environment variables.
+ * Builds a RabbitMQ URI string from environment variables.
+ *
  * @param {{
  *   RABBIT_HOST: string,
  *   RABBIT_PORT: string | number,

package/src/util/index.js

@@ -0,0 +1,12 @@
+import { mask, maskSingle } from './mask-sensitive.js'
+
+/**
+ * @namespace util
+ * Common utility functions.
+ */
+export const util = {
+  mask,
+  maskSingle,
+}
+
+export { mask, maskSingle }

package/src/util/mask-sensitive.js

@@ -0,0 +1,78 @@
+/**
+ * Mask middle of a primitive value while keeping left/right edges.
+ * @param {string|number|boolean|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string}
+ */
+export const maskSingle = (
+  value,
+  fill = '•',
+  maskLen = 3,
+  left = 4,
+  right = 4,
+) => {
+  if (value == null) {
+    return ''
+  }
+  const str = String(value)
+  if (str.length === 0) {
+    return ''
+  }
+  const m = Math.max(1, maskLen)
+
+  if (str.length <= left + right) {
+    if (str.length === 1) {
+      return fill
+    }
+    if (str.length === 2) {
+      return str[0] + fill.repeat(2) // "ab" -> "a••"
+    }
+    return str.slice(0, 1) + fill.repeat(m) + str.slice(-1)
+  }
+
+  return str.slice(0, left) + fill.repeat(m) + str.slice(-right)
+}
+
+/**
+ * Recursively mask values in strings, numbers, booleans, arrays, and objects.
+ * @param {string|number|boolean|Array|Object|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string|Array|Object}
+ */
+export const mask = (value, fill = '•', maskLen = 3, left = 4, right = 4) => {
+  const type = typeof value
+
+  if (value instanceof Date) {
+    const isoDate = value.toISOString()
+    return maskSingle(isoDate, '', isoDate.length, 0, 0)
+  }
+
+  if (value == null || (value && ['string', 'number'].includes(type))) {
+    return maskSingle(value, fill, maskLen, left, right)
+  }
+
+  if (type === 'boolean') {
+    return maskSingle(value, '', 0, 0, 0)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((aValue) => mask(aValue, fill, maskLen, left, right))
+  }
+
+  if (typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([prop, propValue]) => [
+        prop,
+        mask(propValue, fill, maskLen, left, right),
+      ]),
+    )
+  }
+
+  return value
+}

package/tests/ids/generators.unit.test.js

@@ -14,25 +14,25 @@ import {
 } from '../../src/ids/generators.js'
 import { ID_PREFIXES } from '../../src/ids/prefixes.js'
 
-const UUID_V4_REGEX =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+// ULID is a 26-character Base32 string (no I, L, O, U).
+const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/
 
 const testPrefixFunction = (fn, expectedPrefix) => {
   const id = fn()
   expect(typeof id).toBe('string')
-  const [prefix, uuid] = id.split('_')
+  const [prefix, ulid] = id.split('_')
   expect(prefix).toBe(expectedPrefix)
-  expect(uuid).toMatch(UUID_V4_REGEX)
+  expect(ulid).toMatch(ULID_REGEX)
 }
 
 describe('generateId', () => {
-  it('generates a valid UUID v4', () => {
+  it('generates a valid ULID', () => {
     const id = generateId()
     expect(typeof id).toBe('string')
-    expect(id).toMatch(UUID_V4_REGEX)
+    expect(id).toMatch(ULID_REGEX)
   })
 
-  it('generates unique UUIDs', () => {
+  it('generates unique ULIDs', () => {
     const ids = new Set(Array.from({ length: 10 }, () => generateId()))
     expect(ids.size).toBe(10)
   })
@@ -41,9 +41,9 @@ describe('generateId', () => {
 describe('generatePrefixedId', () => {
   it('generates an ID with the correct prefix', () => {
     const prefixed = generatePrefixedId('test')
-    const [prefix, uuid] = prefixed.split('_')
+    const [prefix, ulid] = prefixed.split('_')
     expect(prefix).toBe('test')
-    expect(uuid).toMatch(UUID_V4_REGEX)
+    expect(ulid).toMatch(ULID_REGEX)
   })
 })
 

package/tests/rabbit-mq/rabbit-mq.test.js

@@ -7,6 +7,10 @@ const sleep = (ms) => new Promise((res) => setTimeout(res, ms))
 const testLog = {
   info: () => {},
   error: console.error,
+  debug: console.debug,
+  child() {
+    return testLog
+  },
 }
 
 describe('RabbitMQ SDK', () => {
@@ -18,6 +22,7 @@ describe('RabbitMQ SDK', () => {
   let received = null
 
   beforeAll(async () => {
+    // @ts-ignore
     sdk = await initializeQueue({ host, log: testLog })
 
     await sdk.subscribe({

package/tests/util/mask-sensitive.unit.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+
+import { mask, maskSingle } from '../../src/util/index.js'
+
+describe('maskSingle', () => {
+  it('masks middle of a regular string (length == left+right)', () => {
+    expect(maskSingle('abcdefgh')).toBe('a•••h')
+  })
+
+  it('masks numbers with default settings', () => {
+    expect(maskSingle(12345678)).toBe('1•••8')
+  })
+
+  it('masks booleans', () => {
+    expect(maskSingle(true)).toBe('t•••e')
+    expect(maskSingle(false)).toBe('f•••e')
+  })
+
+  it('masks very short strings correctly', () => {
+    expect(maskSingle('ab')).toBe('a••b'.slice(0, 3)) // will produce 'a••'
+    expect(maskSingle('a')).toBe('•')
+    expect(maskSingle('')).toBe('')
+  })
+
+  it('respects custom fill and mask length', () => {
+    expect(maskSingle('abcdefgh', '*', 5)).toBe('a*****h')
+  })
+
+  it('ensures maskLen is at least 1', () => {
+    expect(maskSingle('abcdefgh', '*', 0)).toBe('a*h')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(maskSingle(null)).toBe('')
+    expect(maskSingle(undefined)).toBe('')
+  })
+})
+
+describe('mask', () => {
+  it('masks primitives (string, number, boolean)', () => {
+    expect(mask('abcdefgh')).toBe('a•••h')
+    expect(mask(12345678)).toBe('1•••8')
+    expect(mask(true)).toBe('true')
+    expect(mask(false)).toBe('false')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(mask(null)).toBe('')
+    expect(mask(undefined)).toBe('')
+  })
+
+  it('masks arrays recursively', () => {
+    expect(mask(['abcdefgh', 12345678])).toEqual(['a•••h', '1•••8'])
+  })
+
+  it('masks objects recursively', () => {
+    expect(mask({ a: 'abcdefgh', b: 12345678 })).toEqual({
+      a: 'a•••h',
+      b: '1•••8',
+    })
+  })
+
+  it('masks nested objects/arrays recursively', () => {
+    const input = { arr: ['abcdefgh', { num: 12345678 }] }
+    const expected = { arr: ['a•••h', { num: '1•••8' }] }
+    expect(mask(input)).toEqual(expected)
+  })
+
+  it('handles Date instances by returning full ISO string', () => {
+    const d = new Date('2025-08-15T12:34:56.789Z')
+    expect(mask(d)).toBe(d.toISOString())
+  })
+
+  it('respects custom fill and mask length in recursive calls', () => {
+    const input = { val: 'abcdefgh' }
+    const expected = { val: 'a*****h' }
+    expect(mask(input, '*', 5)).toEqual(expected)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "allowJs": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types"
+  },
+  "include": ["src"]
+}

package/types/core/combine-unique-arrays.d.ts

@@ -0,0 +1 @@
+export function combineUniqueArrays(...lists: Array<any>[]): Array<any>;

package/types/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./regex-utils.js";
+export * from "./otp-generators.js";
+export * from "./sanitize-objects.js";
+export * from "./normalize-min-max.js";
+export * from "./normalize-to-array.js";
+export * from "./combine-unique-arrays.js";
+export * from "./normalize-phone-number.js";