core-services-sdk 1.3.20 → 1.3.22

package/.eslintrc.json

@@ -0,0 +1,14 @@
+{
+  "env": {
+    "es2021": true,
+    "node": true
+  },
+  "extends": ["eslint:recommended", "plugin:prettier/recommended"],
+  "plugins": ["prettier"],
+  "rules": {
+    "prettier/prettier": "error",
+    "no-unused-vars": "warn",
+    "no-console": "off"
+  },
+  "ignores": ["node_modules", "dist", ".next"]
+}

package/.vscode/settings.json

@@ -12,5 +12,10 @@
   },
   "javascript.preferences.importModuleSpecifierEnding": "js",
   "js/ts.implicitProjectConfig.checkJs": true,
-  "javascript.validate.enable": true
+  "javascript.validate.enable": true,
+  "eslint.validate": ["javascript"],
+
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
 }

package/eslint.config.js

@@ -0,0 +1,21 @@
+import eslintPluginPrettier from 'eslint-plugin-prettier'
+
+/** @type {import("eslint").Linter.FlatConfig} */
+export default [
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      sourceType: 'module',
+      ecmaVersion: 'latest',
+    },
+    plugins: {
+      prettier: eslintPluginPrettier,
+    },
+    rules: {
+      'no-console': 'off',
+      'no-unused-vars': 'warn',
+      'curly': ['error', 'all'],
+      'prettier/prettier': 'error',
+    },
+  },
+]

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.20",
+  "version": "1.3.22",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
-    "test": "vitest run --coverage"
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --coverage",
+    "format": "prettier --write .",
+    "bump": "node ./scripts/bump-version.js"
   },
   "repository": {
     "type": "git",
@@ -30,13 +34,18 @@
     "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",
+    "eslint": "^9.30.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.5.1",
     "path": "^0.12.7",
+    "prettier": "^3.6.2",
     "url": "^0.11.4",
     "vitest": "^3.2.4"
   }
-}
+}

package/scripts/bump-version.js

@@ -0,0 +1,68 @@
+import fs from 'fs'
+import path from 'path'
+import { execSync } from 'child_process'
+
+const type = process.argv[2] // "major" | "minor" | "patch" | "-major" | "-minor" | "-patch"
+
+if (!['major', 'minor', 'patch', '-major', '-minor', '-patch'].includes(type)) {
+  console.error(`Usage: npm run bump <major|minor|patch|-major|-minor|-patch>`)
+  process.exit(1)
+}
+
+const pkgPath = path.resolve(process.cwd(), 'package.json')
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+
+let [major, minor, patch] = pkg.version.split('.').map(Number)
+
+const bump = () => {
+  switch (type) {
+    case 'major':
+      return [major + 1, 0, 0]
+    case 'minor':
+      return [major, minor + 1, 0]
+    case 'patch':
+      return [major, minor, patch + 1]
+    case '-major':
+      if (major === 0) {
+        throw new Error('Cannot decrement major below 0')
+      }
+      return [major - 1, 0, 0]
+    case '-minor':
+      if (minor === 0) {
+        if (major === 0) {
+          throw new Error('Cannot decrement minor below 0.0')
+        }
+        return [major - 1, 0, 0]
+      }
+      return [major, minor - 1, 0]
+    case '-patch':
+      if (patch === 0) {
+        if (minor === 0) {
+          if (major === 0) {
+            throw new Error('Cannot decrement below 0.0.0')
+          }
+          return [major - 1, 0, 0]
+        }
+        return [major, minor - 1, 0]
+      }
+      return [major, minor, patch - 1]
+  }
+}
+
+const [newMajor, newMinor, newPatch] = bump()
+const newVersion = `${newMajor}.${newMinor}.${newPatch}`
+
+pkg.version = newVersion
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+
+console.log(`✔ Updated version to ${newVersion}`)
+
+// update package-lock.json if exists
+if (fs.existsSync('./package-lock.json')) {
+  try {
+    execSync('npm install --package-lock-only', { stdio: 'inherit' })
+    console.log('✔ package-lock.json updated')
+  } catch (err) {
+    console.error('Failed to update package-lock.json', err)
+  }
+}

package/src/core/normalize-phone-number.js

@@ -7,10 +7,9 @@ import * as raw from 'google-libphonenumber'
 export function getLib() {
   // Prefer direct (CJS-style or ESM w/ named), else default
   // e.g. raw.PhoneNumberUtil OR raw.default.PhoneNumberUtil
-  // eslint-disable-next-line no-unused-vars
   /** @type {any} */
   const anyRaw = raw
-  const lib = anyRaw.PhoneNumberUtil ? anyRaw : anyRaw.default ?? anyRaw
+  const lib = anyRaw.PhoneNumberUtil ? anyRaw : (anyRaw.default ?? anyRaw)
 
   if (!lib || !lib.PhoneNumberUtil || !lib.PhoneNumberFormat) {
     throw new Error('google-libphonenumber failed to load (exports not found)')
@@ -71,7 +70,9 @@ export function normalizePhoneOrThrowIntl(input) {
   try {
     const util = phoneUtil()
     const parsed = util.parseAndKeepRawInput(clean(input))
-    if (!util.isValidNumber(parsed)) throw new Error('x')
+    if (!util.isValidNumber(parsed)) {
+      throw new Error('Phone number failed validation')
+    }
     return toResult(parsed)
   } catch (e) {
     const err = new Error('Invalid phone number')
@@ -91,7 +92,9 @@ export function normalizePhoneOrThrowWithRegion(input, defaultRegion) {
   try {
     const util = phoneUtil()
     const parsed = util.parseAndKeepRawInput(clean(input), defaultRegion)
-    if (!util.isValidNumber(parsed)) throw new Error('x')
+    if (!util.isValidNumber(parsed)) {
+      throw new Error('Phone number failed validation')
+    }
     return toResult(parsed)
   } catch (e) {
     const err = new Error('Invalid phone number')

package/src/core/regex-utils.js

@@ -16,8 +16,12 @@
  */
 
 export const isValidRegex = (pattern) => {
-  if (pattern instanceof RegExp) return true
-  if (typeof pattern !== 'string') return false
+  if (pattern instanceof RegExp) {
+    return true
+  }
+  if (typeof pattern !== 'string') {
+    return false
+  }
   try {
     new RegExp(pattern)
     return true

package/src/http/http.js

@@ -83,7 +83,9 @@ const tryGetJsonResponse = async (response) => {
     jsonText = await getTextResponse(response)
     return tryConvertJsonResponse(jsonText)
   } catch (error) {
-    if (!jsonText) throw error
+    if (!jsonText) {
+      throw error
+    }
     return jsonText
   }
 }
@@ -100,7 +102,9 @@ const tryGetXmlResponse = async (response) => {
     xmlText = await getTextResponse(response)
     return await parseStringPromise(xmlText)
   } catch (error) {
-    if (!xmlText) throw error
+    if (!xmlText) {
+      throw error
+    }
     return xmlText
   }
 }

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/mongodb/validate-mongo-uri.js

@@ -26,7 +26,7 @@ export function isValidMongoUri(uri) {
     const hasHostname = Boolean(parsed.hostname)
 
     return isValidProtocol && hasHostname
-  } catch (e) {
+  } catch {
     return false
   }
 }

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,29 +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
+      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
   }
 }
 
@@ -99,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>}
@@ -166,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/tests/http/http-method.unit.test.js

@@ -20,7 +20,7 @@ describe('HTTP_METHODS constant', () => {
     // Attempt to mutate and verify it fails
     try {
       HTTP_METHODS.NEW = 'NEW'
-    } catch (err) {
+    } catch {
       // Ignore in strict mode
     }
 

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/ids/prefixes.unit.test.js

@@ -35,7 +35,7 @@ describe('ID_PREFIXES', () => {
     // Try to mutate
     try {
       ID_PREFIXES.USER = 'hacked'
-    } catch (_) {
+    } catch {
       // Ignore error in strict mode
     }
 

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', () => {

package/tests/templates/template-loader.unit.test.js

@@ -1,4 +1,3 @@
-import dot from 'dot'
 import * as fs from 'fs/promises'
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 
@@ -7,9 +6,6 @@ import { loadTemplates } from '../../src/templates/template-loader.js'
 vi.mock('fs/promises')
 
 describe('loadTemplates', () => {
-  // @ts-ignore
-  const mockCompile = vi.spyOn(dot, 'compile')
-
   beforeEach(() => {
     vi.resetAllMocks()
   })