core-services-sdk 1.3.50 → 1.3.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.50",
+  "version": "1.3.52",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
@@ -33,9 +33,11 @@
     "fastify": "^5.4.0",
     "google-libphonenumber": "^3.2.42",
     "http-status": "^2.1.0",
+    "knex": "^3.1.0",
     "mongodb": "^6.18.0",
     "nodemailer": "^7.0.5",
     "p-retry": "^7.0.0",
+    "pg": "^8.16.3",
     "pino": "^9.7.0",
     "ulid": "^3.0.1",
     "uuid": "^11.1.0",

package/src/ids/generators.js

@@ -4,12 +4,7 @@ import { ID_PREFIXES } from './prefixes.js'
 /**
  * Generates a new ULID string.
  *
- * ULIDs are 26-character, lexicographically sortable identifiers.
- *
- * @returns {string} A new ULID.
- *
- * @example
- * generateId() // '01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
+ * @returns {string}
  */
 export const generateId = () => {
   return ulid()
@@ -18,222 +13,140 @@ export const generateId = () => {
 /**
  * Generates a unique ID with the given prefix.
  *
- * @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_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
+ * @param {string} prefix
+ * @returns {string}
  */
 export const generatePrefixedId = (prefix) => {
   return `${prefix}_${generateId()}`
 }
 
-/**
- * Generates a user ID with a `usr_` prefix.
- *
- * @returns {string} A user ID.
- */
+/* =========================
+ * Core identity
+ * ========================= */
+
 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 generateSessionId = () => generatePrefixedId(ID_PREFIXES.SESSION)
+
+export const generateOnboardingId = () =>
+  generatePrefixedId(ID_PREFIXES.ONBOARDING)
+
+/* =========================
+ * Authorization
+ * ========================= */
+
 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)
+export const generateRoleId = () => generatePrefixedId(ID_PREFIXES.ROLE)
+
+export const generateRolePermissionsId = () =>
+  generatePrefixedId(ID_PREFIXES.ROLE_PERMISSION)
 
-/**
- * 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)
+/* =========================
+ * Assets & uploads
+ * ========================= */
 
-/**
- * Generates an onboarding ID with a `onb_` prefix.
- *
- * @returns {string} An onboarding ID.
- */
-export const generateOnboardingId = () =>
-  generatePrefixedId(ID_PREFIXES.ONBOARDING)
+export const generateAssetId = () => generatePrefixedId(ID_PREFIXES.ASSET)
 
-/**
- * Generates a session ID with a `sess_` prefix.
- *
- * @returns {string} A session ID.
- */
-export const generateSessionId = () => generatePrefixedId(ID_PREFIXES.SESSION)
+export const generateAssetUploadId = () =>
+  generatePrefixedId(ID_PREFIXES.ASSET_UPLOAD)
+
+/* =========================
+ * Files (legacy)
+ * ========================= */
 
-/**
- * Generates a file ID with a `fil_` prefix.
- *
- * @returns {string} A file ID.
- */
 export const generateFileId = () => generatePrefixedId(ID_PREFIXES.FILE)
 
-/**
- * Generates an event ID with an `evt_` prefix.
- *
- * @returns {string} An event ID.
- */
+/* =========================
+ * Accounting
+ * ========================= */
+
+export const generateSupplierId = () => generatePrefixedId(ID_PREFIXES.SUPPLIER)
+
+export const generateInvoiceId = () => generatePrefixedId(ID_PREFIXES.INVOICE)
+
+export const generateInvoiceItemId = () =>
+  generatePrefixedId(ID_PREFIXES.INVOICE_ITEM)
+
+export const generateInvoiceCorrectionId = () =>
+  generatePrefixedId(ID_PREFIXES.INVOICE_CORRECTION)
+
+/* =========================
+ * AI / document processing
+ * ========================= */
+
+export const generateDocumentDataId = () =>
+  generatePrefixedId(ID_PREFIXES.DOCUMENT_DATA)
+
+/* =========================
+ * Bots / automation
+ * ========================= */
+
+export const generateBotFlowId = () => generatePrefixedId(ID_PREFIXES.BOT_FLOW)
+
+/* =========================
+ * Infra / messaging
+ * ========================= */
+
+export const generateCorrelationId = () =>
+  generatePrefixedId(ID_PREFIXES.CORRELATION)
+
 export const generateEventId = () => generatePrefixedId(ID_PREFIXES.EVENT)
 
-/**
- * Generates a job ID with a `job_` prefix.
- *
- * @returns {string} A job ID.
- */
 export const generateJobId = () => generatePrefixedId(ID_PREFIXES.JOB)
 
-/**
- * Generates a task ID with a `task_` prefix.
- *
- * @returns {string} A task ID.
- */
 export const generateTaskId = () => generatePrefixedId(ID_PREFIXES.TASK)
 
-/**
- * Generates a queue ID with a `que_` prefix.
- *
- * @returns {string} A queue ID.
- */
 export const generateQueueId = () => generatePrefixedId(ID_PREFIXES.QUEUE)
 
-/**
- * Generates a message ID with a `msg_` prefix.
- *
- * @returns {string} A message ID.
- */
 export const generateMessageId = () => generatePrefixedId(ID_PREFIXES.MESSAGE)
 
-/**
- * Generates a notification ID with a `ntf_` prefix.
- *
- * @returns {string} A notification ID.
- */
+/* =========================
+ * Communication
+ * ========================= */
+
+export const generateEmailId = () => generatePrefixedId(ID_PREFIXES.EMAIL)
+
+export const generateIncomingEmailId = () =>
+  generatePrefixedId(ID_PREFIXES.INCOMING_EMAIL)
+
+export const generateImId = () => generatePrefixedId(ID_PREFIXES.IM)
+
 export const generateNotificationId = () =>
   generatePrefixedId(ID_PREFIXES.NOTIFICATION)
 
-/**
- * Generates a log ID with a `log_` prefix.
- *
- * @returns {string} A log ID.
- */
-export const generateLogId = () => generatePrefixedId(ID_PREFIXES.LOG)
+/* =========================
+ * Observability
+ * ========================= */
 
-/**
- * Generates an audit ID with an `adt_` prefix.
- *
- * @returns {string} An audit ID.
- */
 export const generateAuditId = () => generatePrefixedId(ID_PREFIXES.AUDIT)
 
-/**
- * Generates a config ID with a `cfg_` prefix.
- *
- * @returns {string} A config ID.
- */
-export const generateConfigId = () => generatePrefixedId(ID_PREFIXES.CONFIG)
-
-/**
- * Generates a key ID with a `key_` prefix.
- *
- * @returns {string} A key ID.
- */
-export const generateKeyId = () => generatePrefixedId(ID_PREFIXES.KEY)
+export const generateLogId = () => generatePrefixedId(ID_PREFIXES.LOG)
 
-/**
- * Generates a metric ID with a `met_` prefix.
- *
- * @returns {string} A metric ID.
- */
 export const generateMetricId = () => generatePrefixedId(ID_PREFIXES.METRIC)
 
-/**
- * Generates a tag ID with a `tag_` prefix.
- *
- * @returns {string} A tag ID.
- */
-export const generateTagId = () => generatePrefixedId(ID_PREFIXES.TAG)
+/* =========================
+ * Security / config / misc
+ * ========================= */
+
+export const generateKeyId = () => generatePrefixedId(ID_PREFIXES.KEY)
 
-/**
- * Generates a policy ID with a `plc_` prefix.
- *
- * @returns {string} A policy ID.
- */
 export const generatePolicyId = () => generatePrefixedId(ID_PREFIXES.POLICY)
 
-/**
- * Generates a profile ID with a `prf_` prefix.
- *
- * @returns {string} A profile ID.
- */
 export const generateProfileId = () => generatePrefixedId(ID_PREFIXES.PROFILE)
 
-/**
- * Generates a device ID with a `dev_` prefix.
- *
- * @returns {string} A device ID.
- */
 export const generateDeviceId = () => generatePrefixedId(ID_PREFIXES.DEVICE)
 
-/**
- * Generates an alert ID with an `alr_` prefix.
- *
- * @returns {string} An alert ID.
- */
 export const generateAlertId = () => generatePrefixedId(ID_PREFIXES.ALERT)
 
-/**
- * Generates a resource ID with a `res_` prefix.
- *
- * @returns {string} A resource ID.
- */
 export const generateResourceId = () => generatePrefixedId(ID_PREFIXES.RESOURCE)
 
-/**
- * Generates a resource ID with a `ieml_` prefix.
- *
- * @returns {string} An incoming email ID.
- */
-export const generateIncomingEmailId = () =>
-  generatePrefixedId(ID_PREFIXES.INCOMING_EMAIL)
-
-/**
- * Generates a resource ID with a `eml_` prefix.
- *
- * @returns {string} An Email ID.
- */
-export const generateEmailId = () => generatePrefixedId(ID_PREFIXES.EMAIL)
+export const generateTagId = () => generatePrefixedId(ID_PREFIXES.TAG)
 
-/**
- * Generates a resource ID with a `im_` prefix.
- *
- * @returns {string} An Instant Message ID.
- */
-export const generateImId = () => generatePrefixedId(ID_PREFIXES.IM)
+export const generateConfigId = () => generatePrefixedId(ID_PREFIXES.CONFIG)

package/src/ids/prefixes.js

@@ -1,97 +1,93 @@
 /**
  * Mapping of entity types to their unique ID prefixes.
  *
- * These prefixes are prepended to ULIDs to create consistent and identifiable IDs across the system.
- * For example: 'usr_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T'
+ * Prefixes are prepended to ULIDs to create readable,
+ * sortable, and easily identifiable IDs across the system.
+ *
+ * Example:
+ *   ast_01HZY3M7K4FJ9A8Q4Y1ZB5NX3T
  *
  * @readonly
  * @enum {string}
  */
 export const ID_PREFIXES = Object.freeze({
-  /** User entity ID prefix */
+  //////////////////////////////////////////////////////
+  // Core identity
+  //////////////////////////////////////////////////////
   USER: 'usr',
-
-  /** Tenant entity ID prefix */
   TENANT: 'tnt',
+  SESSION: 'sess',
+  ONBOARDING: 'onb',
 
-  /** Permission entity ID prefix */
+  //////////////////////////////////////////////////////
+  // Authorization & access
+  //////////////////////////////////////////////////////
+  ROLE: 'role',
   PERMISSION: 'prm',
-
-  /** Correlation ID prefix (e.g., for tracing requests) */
-  CORRELATION: 'crln',
-
-  /** Verification entity ID prefix (e.g., email/phone code) */
+  ROLE_PERMISSION: 'rprm',
   VERIFICATION: 'vrf',
+  POLICY: 'plc',
+  PROFILE: 'prf',
+  DEVICE: 'dev',
 
-  /** Role-permissions mapping ID prefix */
-  ROLE_PERMISSIONS: 'role',
-
-  /** Onboarding mapping ID prefix */
-  ONBOARDING: 'onb',
-
-  /** Session mapping ID prefix */
-  SESSION: 'sess',
+  //////////////////////////////////////////////////////
+  // Assets & uploads
+  //////////////////////////////////////////////////////
+  ASSET: 'ast',
+  ASSET_UPLOAD: 'aupl',
 
-  /** File mapping ID prefix */
+  // Legacy – kept for backward compatibility
   FILE: 'fil',
 
-  /** Event entity ID prefix */
+  //////////////////////////////////////////////////////
+  // Accounting domain
+  //////////////////////////////////////////////////////
+  SUPPLIER: 'sup',
+  INVOICE: 'inv',
+  INVOICE_ITEM: 'invi',
+  INVOICE_CORRECTION: 'invc',
+
+  //////////////////////////////////////////////////////
+  // AI / document processing
+  //////////////////////////////////////////////////////
+  DOCUMENT_DATA: 'docd',
+
+  //////////////////////////////////////////////////////
+  // Messaging / jobs / infra
+  //////////////////////////////////////////////////////
+  CORRELATION: 'crln',
   EVENT: 'evt',
-
-  /** Job entity ID prefix */
   JOB: 'job',
-
-  /** Task entity ID prefix */
   TASK: 'task',
-
-  /** Queue entity ID prefix */
   QUEUE: 'que',
-
-  /** Message entity ID prefix */
   MESSAGE: 'msg',
-
-  /** Notification entity ID prefix */
   NOTIFICATION: 'ntf',
 
-  /** Log entity ID prefix */
-  LOG: 'log',
+  //////////////////////////////////////////////////////
+  // Communication
+  //////////////////////////////////////////////////////
+  EMAIL: 'eml',
+  INCOMING_EMAIL: 'ieml',
+  IM: 'im',
 
-  /** Audit entity ID prefix */
+  //////////////////////////////////////////////////////
+  // Observability
+  //////////////////////////////////////////////////////
   AUDIT: 'adt',
-
-  /** Config entity ID prefix */
-  CONFIG: 'cfg',
-
-  /** Key entity ID prefix */
-  KEY: 'key',
-
-  /** Metric entity ID prefix */
+  LOG: 'log',
   METRIC: 'met',
 
-  /** Tag entity ID prefix */
+  //////////////////////////////////////////////////////
+  // Misc / config
+  //////////////////////////////////////////////////////
   TAG: 'tag',
-
-  /** Policy entity ID prefix */
-  POLICY: 'plc',
-
-  /** Profile entity ID prefix */
-  PROFILE: 'prf',
-
-  /** Device entity ID prefix */
-  DEVICE: 'dev',
-
-  /** Alert entity ID prefix */
-  ALERT: 'alr',
-
-  /** Resource entity ID prefix */
+  CONFIG: 'cfg',
+  KEY: 'key',
   RESOURCE: 'res',
+  ALERT: 'alr',
 
-  /** Incoming email ID prefix */
-  INCOMING_EMAIL: 'ieml',
-
-  /** Email ID prefix */
-  EMAIL: 'eml',
-
-  /** Instant Message ID prefix */
-  IM: 'im',
+  //////////////////////////////////////////////////////
+  // Bots / automation flows
+  //////////////////////////////////////////////////////
+  BOT_FLOW: 'botf',
 })

package/src/index.js

@@ -10,3 +10,4 @@ export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
 export * from './util/index.js'
 export * from './instant-messages/index.js'
+export * from './postgresql/index.js'

package/src/postgresql/connect-to-pg.js

@@ -0,0 +1,23 @@
+import knex from 'knex'
+
+/**
+ * Creates and returns a Knex database connection instance.
+ *
+ * This function initializes a Knex client configured for PostgreSQL
+ * using the provided connection configuration.
+ *
+ * @param {object|string} connection
+ *   Knex connection configuration.
+ *   Can be a connection object or a connection string.
+ *
+ * @returns {import('knex').Knex}
+ *   A configured Knex database instance.
+ */
+export const connectToPg = (connection) => {
+  const db = knex({
+    connection,
+    client: 'pg',
+  })
+
+  return db
+}

package/src/postgresql/index.js

@@ -0,0 +1,3 @@
+export * from './connect-to-pg.js'
+export * from './validate-schema.js'
+export * from './start-stop-postgres-docker.js'

package/src/postgresql/start-stop-postgres-docker.js

@@ -0,0 +1,158 @@
+import { execSync } from 'node:child_process'
+
+/**
+ * Starts a PostgreSQL Docker container for testing purposes.
+ *
+ * If a container with the same name already exists, it will be stopped and removed first.
+ * The function blocks until PostgreSQL is ready to accept connections.
+ *
+ * @param {object} options
+ * @param {number} [options.port=5433]
+ *   Host port to bind PostgreSQL to.
+ *
+ * @param {string} [options.containerName='postgres-test']
+ *   Docker container name.
+ *
+ * @param {string} [options.user='testuser']
+ *   Database user name.
+ *
+ * @param {string} [options.pass='testpass']
+ *   Database user password.
+ *
+ * @param {string} [options.db='testdb']
+ *   Database name.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if PostgreSQL does not become ready within the expected time.
+ */
+
+export function startPostgres({
+  port = 5433,
+  containerName = 'postgres-test',
+  user = 'testuser',
+  pass = 'testpass',
+  db = 'testdb',
+}) {
+  console.log(`[PgTest] Starting PostgreSQL on port ${port}...`)
+
+  stopPostgres(containerName)
+
+  execSync(
+    `docker run -d \
+      --name ${containerName} \
+      -e POSTGRES_USER=${user} \
+      -e POSTGRES_PASSWORD=${pass} \
+      -e POSTGRES_DB=${db} \
+      -p ${port}:5432 \
+      postgres:16`,
+    { stdio: 'inherit' },
+  )
+
+  waitForPostgres(containerName, user, db)
+}
+
+/**
+ * Stops and removes a PostgreSQL Docker container used for testing.
+ *
+ * If the container does not exist, the function exits silently.
+ *
+ * @param {string} [containerName='postgres-test']
+ *   Docker container name.
+ *
+ * @returns {void}
+ */
+
+export function stopPostgres(containerName = 'postgres-test') {
+  console.log(`[PgTest] Stopping PostgreSQL...`)
+  try {
+    execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' })
+  } catch {}
+}
+
+/**
+ * Checks whether PostgreSQL inside the Docker container
+ * is ready to accept connections.
+ *
+ * @param {string} containerName
+ *   Docker container name.
+ *
+ * @param {string} user
+ *   Database user name.
+ *
+ * @param {string} db
+ *   Database name.
+ *
+ * @returns {boolean}
+ *   Returns true if PostgreSQL is ready, otherwise false.
+ */
+
+export function isPostgresReady(containerName, user, db) {
+  try {
+    execSync(
+      `docker exec ${containerName} psql -U ${user} -d ${db} -c "SELECT 1"`,
+      { stdio: 'ignore' },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Waits until PostgreSQL inside the Docker container
+ * is ready to accept connections.
+ *
+ * Retries for a fixed number of attempts before failing.
+ *
+ * @param {string} containerName
+ *   Docker container name.
+ *
+ * @param {string} user
+ *   Database user name.
+ *
+ * @param {string} db
+ *   Database name.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if PostgreSQL does not become ready within the timeout.
+ */
+
+export function waitForPostgres(containerName, user, db) {
+  console.log(`[PgTest] Waiting for PostgreSQL to be ready...`)
+
+  const maxRetries = 20
+  let retries = 0
+  let ready = false
+
+  while (!ready && retries < maxRetries) {
+    ready = isPostgresReady(containerName, user, db)
+    if (!ready) {
+      retries++
+      execSync(`sleep 1`)
+    }
+  }
+
+  if (!ready) {
+    throw new Error(
+      `[PgTest] PostgreSQL failed to start within ${maxRetries} seconds`,
+    )
+  }
+
+  console.log(`[PgTest] PostgreSQL is ready.`)
+}
+
+/**
+ * Build a PostgreSQL connection URI
+ * @param {object} opts
+ * @param {string} opts.user
+ * @param {string} opts.pass
+ * @param {number} opts.port
+ * @param {string} opts.db
+ */
+export function buildPostgresUri({ user, pass, port, db }) {
+  return `postgres://${user}:${pass}@localhost:${port}/${db}`
+}

package/src/postgresql/validate-schema.js

@@ -0,0 +1,39 @@
+import { connectToPg } from './connect-to-pg.js'
+
+/**
+ * Validates that the specified database tables exist.
+ *
+ * Checks all provided table names and collects any missing tables.
+ * Throws a single error listing all missing tables after validation completes.
+ *
+ * @param {string|object} connection
+ *   Database connection configuration.
+ *   Can be a database connection URI or a Knex connection object.
+ *
+ * @param {string[]} tables
+ *   List of required table names to validate.
+ *
+ * @returns {Promise<void>}
+ *
+ * @throws {Error}
+ *   Throws an error if one or more required tables are missing.
+ */
+export async function validateSchema(connection, tables) {
+  const db = connectToPg(connection)
+
+  const missingTables = []
+
+  for (const table of tables) {
+    const exists = await db.schema.hasTable(table)
+    if (!exists) {
+      missingTables.push(table)
+    }
+  }
+
+  if (missingTables.length > 0) {
+    throw new Error(
+      `Missing the following tables: ${missingTables.join(', ')}. ` +
+        `Did you run migrations?`,
+    )
+  }
+}

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

@@ -29,12 +29,25 @@ import {
   generateDeviceId,
   generateAlertId,
   generateResourceId,
+  generateRoleId,
+  generateAssetId,
+  generateAssetUploadId,
+  generateSupplierId,
+  generateInvoiceId,
+  generateInvoiceItemId,
+  generateInvoiceCorrectionId,
+  generateDocumentDataId,
+  generateEmailId,
+  generateIncomingEmailId,
+  generateImId,
+  generateBotFlowId,
 } from '../../src/ids/generators.js'
 import { ID_PREFIXES } from '../../src/ids/prefixes.js'
 
 // ULID is a 26-character Base32 string (no I, L, O, U).
 const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/
 
+// @ts-ignore
 const testPrefixFunction = (fn, expectedPrefix) => {
   const id = fn()
   expect(typeof id).toBe('string')
@@ -91,7 +104,7 @@ describe('generate*Id functions', () => {
   })
 
   it('generateRolePermissionsId returns ID with role_ prefix', () => {
-    testPrefixFunction(generateRolePermissionsId, ID_PREFIXES.ROLE_PERMISSIONS)
+    testPrefixFunction(generateRolePermissionsId, ID_PREFIXES.ROLE_PERMISSION)
   })
 
   it('generateSessionId returns ID with sess_ prefix', () => {
@@ -169,4 +182,55 @@ describe('generate*Id functions', () => {
   it('generateResourceId returns ID with res_ prefix', () => {
     testPrefixFunction(generateResourceId, ID_PREFIXES.RESOURCE)
   })
+
+  it('generateRoleId returns ID with role_ prefix', () => {
+    testPrefixFunction(generateRoleId, ID_PREFIXES.ROLE)
+  })
+
+  it('generateAssetId returns ID with ast_ prefix', () => {
+    testPrefixFunction(generateAssetId, ID_PREFIXES.ASSET)
+  })
+
+  it('generateAssetUploadId returns ID with aupl_ prefix', () => {
+    testPrefixFunction(generateAssetUploadId, ID_PREFIXES.ASSET_UPLOAD)
+  })
+
+  it('generateSupplierId returns ID with sup_ prefix', () => {
+    testPrefixFunction(generateSupplierId, ID_PREFIXES.SUPPLIER)
+  })
+
+  it('generateInvoiceId returns ID with inv_ prefix', () => {
+    testPrefixFunction(generateInvoiceId, ID_PREFIXES.INVOICE)
+  })
+
+  it('generateInvoiceItemId returns ID with invi_ prefix', () => {
+    testPrefixFunction(generateInvoiceItemId, ID_PREFIXES.INVOICE_ITEM)
+  })
+
+  it('generateInvoiceCorrectionId returns ID with invc_ prefix', () => {
+    testPrefixFunction(
+      generateInvoiceCorrectionId,
+      ID_PREFIXES.INVOICE_CORRECTION,
+    )
+  })
+
+  it('generateDocumentDataId returns ID with docd_ prefix', () => {
+    testPrefixFunction(generateDocumentDataId, ID_PREFIXES.DOCUMENT_DATA)
+  })
+
+  it('generateEmailId returns ID with eml_ prefix', () => {
+    testPrefixFunction(generateEmailId, ID_PREFIXES.EMAIL)
+  })
+
+  it('generateIncomingEmailId returns ID with ieml_ prefix', () => {
+    testPrefixFunction(generateIncomingEmailId, ID_PREFIXES.INCOMING_EMAIL)
+  })
+
+  it('generateImId returns ID with im_ prefix', () => {
+    testPrefixFunction(generateImId, ID_PREFIXES.IM)
+  })
+
+  it('generateBotFlowId returns ID with botf_ prefix', () => {
+    testPrefixFunction(generateBotFlowId, ID_PREFIXES.BOT_FLOW)
+  })
 })

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

@@ -5,35 +5,44 @@ import { ID_PREFIXES } from '../../src/ids/prefixes.js'
 describe('ID_PREFIXES', () => {
   it('contains expected keys and values', () => {
     expect(ID_PREFIXES).toEqual({
-      USER: 'usr',
-      TENANT: 'tnt',
-      PERMISSION: 'prm',
+      ALERT: 'alr',
+      ASSET: 'ast',
+      ASSET_UPLOAD: 'aupl',
+      AUDIT: 'adt',
+      BOT_FLOW: 'botf',
+      CONFIG: 'cfg',
       CORRELATION: 'crln',
-      VERIFICATION: 'vrf',
-      ROLE_PERMISSIONS: 'role',
-      ONBOARDING: 'onb',
-      SESSION: 'sess',
-      FILE: 'fil',
+      DEVICE: 'dev',
+      DOCUMENT_DATA: 'docd',
+      EMAIL: 'eml',
       EVENT: 'evt',
+      FILE: 'fil',
+      IM: 'im',
+      INCOMING_EMAIL: 'ieml',
+      INVOICE: 'inv',
+      INVOICE_CORRECTION: 'invc',
+      INVOICE_ITEM: 'invi',
       JOB: 'job',
-      TASK: 'task',
-      QUEUE: 'que',
-      MESSAGE: 'msg',
-      NOTIFICATION: 'ntf',
-      LOG: 'log',
-      AUDIT: 'adt',
-      CONFIG: 'cfg',
       KEY: 'key',
+      LOG: 'log',
+      MESSAGE: 'msg',
       METRIC: 'met',
-      TAG: 'tag',
+      NOTIFICATION: 'ntf',
+      ONBOARDING: 'onb',
+      PERMISSION: 'prm',
       POLICY: 'plc',
       PROFILE: 'prf',
-      DEVICE: 'dev',
-      ALERT: 'alr',
+      QUEUE: 'que',
       RESOURCE: 'res',
-      INCOMING_EMAIL: 'ieml',
-      EMAIL: 'eml',
-      IM: 'im',
+      ROLE: 'role',
+      ROLE_PERMISSION: 'rprm',
+      SESSION: 'sess',
+      SUPPLIER: 'sup',
+      TAG: 'tag',
+      TASK: 'task',
+      TENANT: 'tnt',
+      USER: 'usr',
+      VERIFICATION: 'vrf',
     })
   })
 

package/tests/postgresql/validate-schema.integration.test.js

@@ -0,0 +1,54 @@
+import { describe, it, beforeAll, afterAll, expect } from 'vitest'
+
+import {
+  startPostgres,
+  stopPostgres,
+  buildPostgresUri,
+} from '../../src/postgresql/start-stop-postgres-docker.js'
+import { connectToPg } from '../../src/postgresql/connect-to-pg.js'
+import { validateSchema } from '../../src/postgresql/validate-schema.js'
+
+const PG_OPTIONS = {
+  port: 5433,
+  containerName: 'postgres-validate-schema-test',
+  user: 'testuser',
+  pass: 'testpass',
+  db: 'testdb',
+}
+
+const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
+
+describe('validateSchema', () => {
+  beforeAll(async () => {
+    startPostgres(PG_OPTIONS)
+
+    const db = connectToPg(DATABASE_URI)
+
+    // create one table only
+    await db.schema.createTable('files', (table) => {
+      table.string('id').primary()
+    })
+
+    await db.destroy()
+  })
+
+  afterAll(() => {
+    stopPostgres(PG_OPTIONS.containerName)
+  })
+
+  it('does not throw when all required tables exist', async () => {
+    await expect(validateSchema(DATABASE_URI, ['files'])).resolves.not.toThrow()
+  })
+
+  it('throws a single error listing missing tables', async () => {
+    await expect(
+      validateSchema(DATABASE_URI, ['files', 'documents', 'attachments']),
+    ).rejects.toThrow('Missing the following tables: documents, attachments')
+  })
+
+  it('throws when all tables are missing', async () => {
+    await expect(
+      validateSchema(DATABASE_URI, ['missing_a', 'missing_b']),
+    ).rejects.toThrow('Missing the following tables: missing_a, missing_b')
+  })
+})