core-services-sdk 1.3.52 → 1.3.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.52",
+  "version": "1.3.54",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/postgresql/validate-schema.js

@@ -6,19 +6,35 @@ import { connectToPg } from './connect-to-pg.js'
  * 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
+ * @param {Object} params
+ *   Parameters object.
+ *
+ * @param {string|Object} params.connection
  *   Database connection configuration.
  *   Can be a database connection URI or a Knex connection object.
  *
- * @param {string[]} tables
+ * @param {string[]} params.tables
  *   List of required table names to validate.
  *
+ * @param {Object} [params.log]
+ *   Optional logger object.
+ *
+ * @param {Function} [params.log.info]
+ *   Logger function for informational messages.
+ *
+ * @param {Function} [params.log.error]
+ *   Logger function for error messages.
+ *
  * @returns {Promise<void>}
  *
  * @throws {Error}
  *   Throws an error if one or more required tables are missing.
  */
-export async function validateSchema(connection, tables) {
+export async function validateSchema({
+  tables,
+  connection,
+  log = { error: console.error, info: console.info },
+}) {
   const db = connectToPg(connection)
 
   const missingTables = []
@@ -31,9 +47,12 @@ export async function validateSchema(connection, tables) {
   }
 
   if (missingTables.length > 0) {
-    throw new Error(
-      `Missing the following tables: ${missingTables.join(', ')}. ` +
-        `Did you run migrations?`,
-    )
+    const errorMessage = `Missing the following tables: ${missingTables.join(', ')}. Did you run migrations?`
+    log.error(errorMessage)
+    throw new Error(errorMessage)
+  }
+
+  if (tables.length) {
+    log.info(`All required tables are exists: ${tables.join(', ')}`)
   }
 }

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

@@ -37,18 +37,26 @@ describe('validateSchema', () => {
   })
 
   it('does not throw when all required tables exist', async () => {
-    await expect(validateSchema(DATABASE_URI, ['files'])).resolves.not.toThrow()
+    await expect(
+      validateSchema({ connection: DATABASE_URI, tables: ['files'] }),
+    ).resolves.not.toThrow()
   })
 
   it('throws a single error listing missing tables', async () => {
     await expect(
-      validateSchema(DATABASE_URI, ['files', 'documents', 'attachments']),
+      validateSchema({
+        connection: DATABASE_URI,
+        tables: ['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']),
+      validateSchema({
+        connection: DATABASE_URI,
+        tables: ['missing_a', 'missing_b'],
+      }),
     ).rejects.toThrow('Missing the following tables: missing_a, missing_b')
   })
 })

package/types/ids/generators.d.ts

@@ -2,30 +2,39 @@ export function generateId(): string
 export function generatePrefixedId(prefix: string): string
 export function generateUserId(): string
 export function generateTenantId(): string
+export function generateSessionId(): string
+export function generateOnboardingId(): string
 export function generatePermissionId(): string
-export function generateCorrelationId(): string
-export function generateVerificationId(): string
+export function generateRoleId(): string
 export function generateRolePermissionsId(): string
-export function generateOnboardingId(): string
-export function generateSessionId(): string
+export function generateVerificationId(): string
+export function generateAssetId(): string
+export function generateAssetUploadId(): string
 export function generateFileId(): string
+export function generateSupplierId(): string
+export function generateInvoiceId(): string
+export function generateInvoiceItemId(): string
+export function generateInvoiceCorrectionId(): string
+export function generateDocumentDataId(): string
+export function generateBotFlowId(): string
+export function generateCorrelationId(): string
 export function generateEventId(): string
 export function generateJobId(): string
 export function generateTaskId(): string
 export function generateQueueId(): string
 export function generateMessageId(): string
+export function generateEmailId(): string
+export function generateIncomingEmailId(): string
+export function generateImId(): string
 export function generateNotificationId(): string
-export function generateLogId(): string
 export function generateAuditId(): string
-export function generateConfigId(): string
-export function generateKeyId(): string
+export function generateLogId(): string
 export function generateMetricId(): string
-export function generateTagId(): string
+export function generateKeyId(): string
 export function generatePolicyId(): string
 export function generateProfileId(): string
 export function generateDeviceId(): string
 export function generateAlertId(): string
 export function generateResourceId(): string
-export function generateIncomingEmailId(): string
-export function generateEmailId(): string
-export function generateImId(): string
+export function generateTagId(): string
+export function generateConfigId(): string

package/types/ids/prefixes.d.ts

@@ -1,76 +1,62 @@
 /**
  * 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
  */
 export type ID_PREFIXES = string
 /**
  * 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: Readonly<{
-  /** User entity ID prefix */
   USER: 'usr'
-  /** Tenant entity ID prefix */
   TENANT: 'tnt'
-  /** Permission entity ID prefix */
+  SESSION: 'sess'
+  ONBOARDING: 'onb'
+  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'
-  /** Role-permissions mapping ID prefix */
-  ROLE_PERMISSIONS: 'role'
-  /** Onboarding mapping ID prefix */
-  ONBOARDING: 'onb'
-  /** Session mapping ID prefix */
-  SESSION: 'sess'
-  /** File mapping ID prefix */
+  POLICY: 'plc'
+  PROFILE: 'prf'
+  DEVICE: 'dev'
+  ASSET: 'ast'
+  ASSET_UPLOAD: 'aupl'
   FILE: 'fil'
-  /** Event entity ID prefix */
+  SUPPLIER: 'sup'
+  INVOICE: 'inv'
+  INVOICE_ITEM: 'invi'
+  INVOICE_CORRECTION: 'invc'
+  DOCUMENT_DATA: 'docd'
+  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'
-  /** Audit entity ID prefix */
+  EMAIL: 'eml'
+  INCOMING_EMAIL: 'ieml'
+  IM: 'im'
   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 */
   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'
-  /** Incoming email ID prefix */
-  INCOMING_EMAIL: 'ieml'
-  /** Email ID prefix */
-  EMAIL: 'eml'
-  /** Instant Message ID prefix */
-  IM: 'im'
+  ALERT: 'alr'
+  BOT_FLOW: 'botf'
 }>

package/types/index.d.ts

@@ -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/types/postgresql/connect-to-pg.d.ts

@@ -0,0 +1 @@
+export function connectToPg(connection: object | string): import('knex').Knex

package/types/postgresql/index.d.ts

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

package/types/postgresql/start-stop-postgres-docker.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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,
+  containerName,
+  user,
+  pass,
+  db,
+}: {
+  port?: number
+  containerName?: string
+  user?: string
+  pass?: string
+  db?: string
+}): void
+/**
+ * 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?: string): void
+/**
+ * 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: string,
+  user: string,
+  db: string,
+): boolean
+/**
+ * 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: string,
+  user: string,
+  db: string,
+): void
+/**
+ * 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,
+}: {
+  user: string
+  pass: string
+  port: number
+  db: string
+}): string

package/types/postgresql/validate-schema.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 {Object} params
+ *   Parameters object.
+ *
+ * @param {string|Object} params.connection
+ *   Database connection configuration.
+ *   Can be a database connection URI or a Knex connection object.
+ *
+ * @param {string[]} params.tables
+ *   List of required table names to validate.
+ *
+ * @param {Object} [params.log]
+ *   Optional logger object.
+ *
+ * @param {Function} [params.log.info]
+ *   Logger function for informational messages.
+ *
+ * @param {Function} [params.log.error]
+ *   Logger function for error messages.
+ *
+ * @returns {Promise<void>}
+ *
+ * @throws {Error}
+ *   Throws an error if one or more required tables are missing.
+ */
+export function validateSchema({
+  tables,
+  connection,
+  log,
+}: {
+  connection: string | any
+  tables: string[]
+  log?: {
+    info?: Function
+    error?: Function
+  }
+}): Promise<void>