@lucaapp/service-utils 5.8.0 → 5.10.0

package/dist/lib/kafka/events/payment.d.ts

@@ -1,28 +1,205 @@
-export type Payment = {
+import { SupportedCurrencies } from '../../money/supportedCurrencies';
+/**
+ * JSON-serialisable value tree.
+ *
+ * Used for opaque payloads carried across the wire. Anything stored here
+ * must round-trip through `JSON.stringify` / `JSON.parse` without loss.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Legacy 3-letter terminal status code from the original payment provider integration. */
+export type RapydPaymentStatus = 'ACT' | 'CAN' | 'CLO' | 'ERR' | 'EXP' | 'NEW' | 'REV';
+/** Provider-neutral payment lifecycle status. */
+export type PaymentStatus = 'PAID' | 'NEW' | 'ACTIVE' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'ERROR' | 'UNKNOWN';
+/**
+ * Lifecycle timestamps shared by all payment events.
+ *
+ * Each timestamp marks the first time the payment entered the corresponding
+ * state. A null value means the state was never reached.
+ */
+export type PaymentStatusTimings = {
+    /** Timestamp when the payment record was created (session start, NOT settlement). */
+    paymentCreatedAt: Date;
+    /** Payment record created; awaiting consumer action (e.g. order created, link sent, QR displayed). */
+    statusNewAt: Date | null;
+    /** Consumer engaged with the payment flow (e.g. opened a 3DS challenge, tapped a terminal, clicked the payment link). */
+    statusActiveAt: Date | null;
+    /** Provider authorised and captured the funds (online auth + capture or terminal sale complete). */
+    statusCompleteAt?: Date | null;
+    /** Cancelled by consumer or operator before completion. */
+    statusCanceledAt: Date | null;
+    /** Payment session expired before completion. */
+    statusExpiredAt: Date | null;
+    /** Provider returned an error or refused the payment. */
+    statusErrorAt: Date | null;
+    /** Authorised payment was reversed before settlement (e.g. chargeback pre-arbitration). */
+    statusReversedAt?: Date | null;
+    /** Projected or actual settlement date to the merchant balance. Null until the provider schedules settlement. */
+    settleAt?: Date | null;
+};
+/** Fields shared by both the legacy {@link Payment} event and the provider-neutral {@link PaymentEvent}. */
+export type PaymentBase = {
+    /** Stable payment id. Uniquely identifies the payment across all systems. */
     uuid: string;
+    /** Merchant location id (UUID). */
     locationId: string;
+    /** Human-readable location name. Null when not provided. */
     locationName: string | null;
+    /** Table or seat identifier from the POS. Null for non-dine-in payments. */
     table: string | null;
+    /** Pre-created payment-request id. Null for spontaneous payments. */
     paymentRequestId: string | null;
-    paymentCreatedAt: Date;
-    paidAt: Date | null;
+    /** Short verifier token used by consumer-facing flows to prove ownership of the payment session. */
     paymentVerifier: string;
-    totalAmount: number;
+    /** Net goods/services amount before tip, in the smallest currency subunit. */
     invoiceAmount: number;
+    /** Consumer-added gratuity, in the smallest currency subunit. Zero when no tip was given. */
     tipAmount: number;
+} & PaymentStatusTimings;
+/**
+ * Legacy payment event tied to the original provider integration.
+ *
+ * Kept for backward compatibility. New consumers should subscribe to
+ * {@link PaymentEvent}.
+ */
+export type Payment = PaymentBase & {
+    /** Total paid by the consumer (= `invoiceAmount + tipAmount`), in the smallest currency subunit. Kept for legacy consumers. */
+    totalAmount: number;
+    /** Timestamp when the payment was marked paid. */
+    paidAt: Date | null;
+    /** @deprecated Legacy terminal "CLO" state. Use `statusCompleteAt`. */
+    statusClosedAt: Date | null;
+    /** Fixed processing fee, in the smallest currency subunit. */
     fixedFee: number;
+    /** Variable fee (commission + markup), in the smallest currency subunit. */
     variableFee: number;
+    /** Legacy provider payment id. */
     rapydPaymentId: string | null;
+    /** Legacy provider error code on failure. */
     rapydErrorCode: string | null;
+    /** Legacy provider error message on failure. */
     rapydErrorMessage: string | null;
-    rapydPaymentStatus: 'ACT' | 'CAN' | 'CLO' | 'ERR' | 'EXP' | 'NEW' | 'REV';
+    /** Legacy 3-letter status code from the provider. */
+    rapydPaymentStatus: RapydPaymentStatus;
+    /** Legacy provider customer / saved-card alias. */
     rapydCustomerId: string | null;
+    /** Aggregated payout batch id. Null until the payment is included in a payout. */
     payoutId: string | null;
-    statusActiveAt: Date | null;
-    statusCanceledAt: Date | null;
-    statusClosedAt: Date | null;
-    statusErrorAt: Date | null;
-    statusExpiredAt: Date | null;
-    statusNewAt: Date | null;
-    statusReversedAt?: Date | null;
+};
+/**
+ * Provider-neutral payment lifecycle event.
+ *
+ * Carries the full domain context needed for fiscalisation, receipt
+ * rendering, and downstream reconciliation. Wire format is JSON: monetary
+ * fields are integers in the smallest currency subunit and `currency`
+ * declares the unit.
+ */
+export type PaymentEvent = PaymentBase & {
+    /** Checkout session id. Optional — some flows emit payment events without a checkout. */
+    checkoutId?: string;
+    /** Order id (e.g. POS / fiscalisation order reference). Absent for payments not tied to an order. */
+    orderId?: string;
+    /** Operator-added service charge / convenience fee, in the smallest currency subunit. Zero if none. */
+    surchargeAmount: number;
+    /** ISO 4217 code that applies to every monetary field on this event. Single-currency invariant. */
+    currency: SupportedCurrencies;
+    /** Lifecycle status at event-emission time. */
+    status: PaymentStatus;
+    /** Method identifier, e.g. `'CARD'`, `'CASH'`, `'WALLET'`. */
+    method: string;
+    /** True if `method` is a cash variant. Cash flows skip provider webhooks and short-circuit fiscalisation. */
+    isCash: boolean;
+    /** Origin service identifier (free-form short string). */
+    source: string;
+    /** Aggregated payout batch id. Null until included in a payout. */
+    payoutId?: string | null;
+    /** Provider-side identifiers, errors, and raw provider payload. Absent for cash. */
+    merchantDetails?: PaymentMerchantDetails;
+    /** Card-specific identifiers and terminal context. Absent for non-card methods. */
+    cardDetails?: PaymentCardDetails;
+    /** Per-item breakdown for fiscalisation and receipt rendering. */
+    lineItems?: PaymentEventLineItem[];
+};
+/** Amount the consumer actually pays = `invoiceAmount + tipAmount + surchargeAmount` (smallest currency subunit). */
+export declare const consumerPayAmount: (event: PaymentEvent) => number;
+/**
+ * Amount receivable by the operator before Luca / provider fees are
+ * deducted = `invoiceAmount + tipAmount` (smallest currency subunit).
+ *
+ * Surcharge is excluded — it covers the consumer-side fee, not operator
+ * revenue. Net payout to the operator is this minus the per-payment fees.
+ */
+export declare const operatorReceivableAmount: (event: PaymentEvent) => number;
+/**
+ * Provider-side metadata for a payment.
+ *
+ * All fields optional — populated by whichever provider handled the
+ * payment. Absent on cash and other non-provider flows.
+ */
+export type PaymentMerchantDetails = {
+    /** Payment-processor identifier (lowercase short string). Null when not yet routed to a provider. */
+    provider?: string | null;
+    /** Provider's payment id. Null until the provider authorises. */
+    providerIdentifier?: string | null;
+    /** Machine-readable error / decline code from the provider. Null on success. */
+    providerErrorCode?: string | null;
+    /** Human-readable provider error detail. Null on success. */
+    providerErrorMessage?: string | null;
+    /** Raw provider payload (notification or response body). Used for audits and chargeback evidence. */
+    providerData?: {
+        [key: string]: JsonValue;
+    } | null;
+    /** Provider-facing merchant reference used to reconcile internal records against the provider's records. */
+    externalReference?: string | null;
+};
+/**
+ * Card and terminal context.
+ *
+ * Card fields populated for card payments; terminal/consumer fields
+ * populated when applicable, regardless of card vs. wallet.
+ */
+export type PaymentCardDetails = {
+    /** Last 4 digits of the card. Null for non-card methods. */
+    last4?: string | null;
+    /** Provider authorisation code. Null until authorised. */
+    authCode?: string | null;
+    /** Saved-card alias for tokenised cards. Null for one-time payments. */
+    consumerAlias?: string | null;
+    /** Physical terminal id. Null for online / QR payments. */
+    terminalId?: string | null;
+    /** Consumer account id. Null for anonymous payments. */
+    consumerId?: string | null;
+};
+/**
+ * One billable line in the order, used for fiscalisation and receipt
+ * rendering.
+ *
+ * Sub-items represent components of a parent line (e.g. base drink + paid
+ * topping) and follow the same shape recursively. Amounts are integers in
+ * the smallest currency subunit.
+ */
+export type PaymentEventLineItem = {
+    /** Stable line-item id. Omitted on synthetic sub-items that have no own row. */
+    uuid?: string;
+    /** POS-system menu item / SKU id. Null when not synced from the POS menu. */
+    posItemId?: string | null;
+    /** Display name (e.g. `'Espresso'`). May be omitted when the consumer can resolve it from `posItemId`. */
+    name?: string;
+    /** Number of units, e.g. `2` for two coffees. */
+    quantity: number;
+    /** Price for one unit, in the smallest currency subunit. */
+    pricePerUnit: number;
+    /** `quantity × pricePerUnit + Σ subItems.totalPrice`, in the smallest currency subunit. */
+    totalPrice: number;
+    /**
+     * VAT / sales-tax rate as a percentage value (e.g. `19` for 19%, `7` for
+     * 7%). NOT a decimal fraction — `0.19` would mean 0.19%. Null if
+     * tax-exempt or unknown.
+     */
+    taxPercentage?: number | null;
+    /** Item currency. Typically equals the parent payment currency. */
+    currency: SupportedCurrencies;
+    /** Recursive components of this line. Each sub-item follows the same shape. */
+    subItems?: PaymentEventLineItem[];
 };

package/dist/lib/kafka/events/payment.js

@@ -1,2 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorReceivableAmount = exports.consumerPayAmount = void 0;
+/** Amount the consumer actually pays = `invoiceAmount + tipAmount + surchargeAmount` (smallest currency subunit). */
+const consumerPayAmount = (event) => event.invoiceAmount + event.tipAmount + event.surchargeAmount;
+exports.consumerPayAmount = consumerPayAmount;
+/**
+ * Amount receivable by the operator before Luca / provider fees are
+ * deducted = `invoiceAmount + tipAmount` (smallest currency subunit).
+ *
+ * Surcharge is excluded — it covers the consumer-side fee, not operator
+ * revenue. Net payout to the operator is this minus the per-payment fees.
+ */
+const operatorReceivableAmount = (event) => event.invoiceAmount + event.tipAmount;
+exports.operatorReceivableAmount = operatorReceivableAmount;

package/dist/lib/kafka/events.d.ts

@@ -82,5 +82,6 @@ declare const MessageIssuer: {
     "wsevent_backend-pos": Service;
     tokenization_job_item: Service;
 };
-export { KafkaTopic, MessageIssuer };
+declare const MessageSignatureIssuers: Partial<Record<KafkaTopic, Service[]>>;
+export { KafkaTopic, MessageIssuer, MessageSignatureIssuers };
 export type { MessageFormats };

package/dist/lib/kafka/events.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MessageIssuer = exports.KafkaTopic = void 0;
+exports.MessageSignatureIssuers = exports.MessageIssuer = exports.KafkaTopic = void 0;
 const serviceIdentity_1 = require("../serviceIdentity");
 var KafkaTopic;
 (function (KafkaTopic) {
@@ -48,3 +48,7 @@ const MessageIssuer = {
     [KafkaTopic.TOKENIZATION_JOB_ITEM]: serviceIdentity_1.Service.BACKEND_PAY,
 };
 exports.MessageIssuer = MessageIssuer;
+const MessageSignatureIssuers = {
+    [KafkaTopic.PAYMENTS]: [serviceIdentity_1.Service.BACKEND_PAY, serviceIdentity_1.Service.BACKEND_TSE],
+};
+exports.MessageSignatureIssuers = MessageSignatureIssuers;

package/dist/lib/kafka/kafkaClient.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KafkaClient = void 0;
 const kafkajs_1 = require("kafkajs");
@@ -61,6 +71,18 @@ const messageAcknowledgedCounter = new metrics_1.metricsClient.Counter({
 const getIssuer = (kafkaTopic) => {
     return events_1.MessageIssuer[kafkaTopic].valueOf();
 };
+const getAllowedSignatureIssuers = (kafkaTopic) => {
+    return (events_1.MessageSignatureIssuers[kafkaTopic] ?? [events_1.MessageIssuer[kafkaTopic]]).map(issuer => issuer.valueOf());
+};
+const headerToString = (header) => {
+    if (Array.isArray(header)) {
+        return headerToString(header[0]);
+    }
+    if (Buffer.isBuffer(header)) {
+        return header.toString();
+    }
+    return header;
+};
 class KafkaClient {
     constructor(parentLogger, kafkaConfig, topicSecrets, serviceIdentity) {
         this.connect = async () => {
@@ -119,11 +141,15 @@ class KafkaClient {
                 this.logger.info('Skipping signature verification (encryption disabled)');
                 return;
             }
-            if (!headers || !headers.signature) {
+            const signature = headerToString(headers?.signature);
+            if (!signature) {
                 throw (0, utils_1.logAndGetError)(this.logger, 'Unable to verify signature. Expected header not present');
             }
-            const issuer = getIssuer(kafkaTopic);
-            const { signature } = headers;
+            const issuer = headerToString(headers?.signatureIssuer) ?? getIssuer(kafkaTopic);
+            const allowedIssuers = getAllowedSignatureIssuers(kafkaTopic);
+            if (!allowedIssuers.includes(issuer)) {
+                throw (0, utils_1.logAndGetError)(this.logger, `Unable to verify signature. Issuer ${issuer} is not allowed for topic=${kafkaTopic}`);
+            }
             const jwks = await this.serviceIdentity.getRemoteJWKS(issuer);
             if (!jwks) {
                 throw (0, utils_1.logAndGetError)(this.logger, `Unable to find jwks for issuer=${issuer}`);
@@ -230,7 +256,10 @@ class KafkaClient {
                         {
                             key,
                             value: encryptedValue,
-                            headers: { signature },
+                            headers: {
+                                signature,
+                                signatureIssuer: this.serviceIdentity.identityName,
+                            },
                         },
                     ],
                 };

package/dist/lib/metrics/metricsClient.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.metricsClient = void 0;
 exports.metricsClient = __importStar(require("prom-client"));

package/dist/lib/pgBoss/controller/routes.d.ts

@@ -1,20 +1,10 @@
 import { Api } from '../../api/api';
 import { PgBossService } from '../service';
+import type { Middleware } from '../../api/types/middleware';
 /**
- * Mounts pg-boss dashboard API routes onto an Api instance.
- *
- * Endpoints:
- * - GET  /queues                          — list queues with stats
- * - GET  /queues/:name/jobs               — list jobs in a queue
- * - GET  /queues/:queue/jobs/:id          — job detail
- * - POST /queues/:queue/jobs/:id/retry    — retry a job
- * - POST /queues/:queue/jobs/:id/cancel   — cancel a job
- * - DELETE /queues/:queue/jobs/:id        — delete a job
- * - GET  /schedules                       — list cron schedules
- * - POST /schedules                       — create a schedule
- * - PUT  /schedules/:name                 — update a schedule
- * - DELETE /schedules/:name               — delete a schedule
- * - POST /queues/:name/jobs               — enqueue a new job
- * - GET  /warnings                        — recent warnings
+ * Express path prefix for every pg-boss admin route. `Api.child()` only
+ * affects OpenAPI documentation, not the underlying express router, so the
+ * prefix MUST live on each path string to make routing work end-to-end.
  */
-export declare const mountPgBossApiRoutes: (api: Api, service: PgBossService) => void;
+export declare const PGBOSS_API_PATH_PREFIX = "/support/pgboss";
+export declare const mountPgBossApiRoutes: (api: Api, service: PgBossService, middlewares?: Middleware<any, any, any, any, any, any>[]) => void;

package/dist/lib/pgBoss/controller/routes.js

@@ -1,37 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mountPgBossApiRoutes = void 0;
+exports.mountPgBossApiRoutes = exports.PGBOSS_API_PATH_PREFIX = void 0;
 const send_1 = require("../../api/send");
 const response_1 = require("../../api/response");
 const routes_schema_1 = require("./routes.schema");
 /**
- * Mounts pg-boss dashboard API routes onto an Api instance.
- *
- * Endpoints:
- * - GET  /queues                          — list queues with stats
- * - GET  /queues/:name/jobs               — list jobs in a queue
- * - GET  /queues/:queue/jobs/:id          — job detail
- * - POST /queues/:queue/jobs/:id/retry    — retry a job
- * - POST /queues/:queue/jobs/:id/cancel   — cancel a job
- * - DELETE /queues/:queue/jobs/:id        — delete a job
- * - GET  /schedules                       — list cron schedules
- * - POST /schedules                       — create a schedule
- * - PUT  /schedules/:name                 — update a schedule
- * - DELETE /schedules/:name               — delete a schedule
- * - POST /queues/:name/jobs               — enqueue a new job
- * - GET  /warnings                        — recent warnings
+ * Express path prefix for every pg-boss admin route. `Api.child()` only
+ * affects OpenAPI documentation, not the underlying express router, so the
+ * prefix MUST live on each path string to make routing work end-to-end.
  */
-const mountPgBossApiRoutes = (api, service) => {
+exports.PGBOSS_API_PATH_PREFIX = '/support/pgboss';
+const mountPgBossApiRoutes = (api, service, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+middlewares) => {
     const pgBossApi = api.child({ tags: ['PgBoss'] });
-    // GET /queues — list queues with stats
-    pgBossApi.get('/queues', 'List all queues with stats', {
+    const p = (path) => `${exports.PGBOSS_API_PATH_PREFIX}${path}`;
+    const mw = middlewares?.length ? { middlewares } : {};
+    pgBossApi.get(p('/queues'), 'List all queues with stats', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.queueStatsArraySchema)],
     }, async (_request, _context, respond) => {
         const stats = await service.getQueueStats();
         return respond((0, send_1.ok)(stats));
     });
-    // GET /queues/:name/jobs — list jobs in a queue
-    pgBossApi.get('/queues/:name/jobs', 'List jobs in a queue', {
+    pgBossApi.get(p('/queues/:name/jobs'), 'List jobs in a queue', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.jobArraySchema)],
         schemas: {
             params: routes_schema_1.queueNameParamsSchema,
@@ -40,8 +33,8 @@ const mountPgBossApiRoutes = (api, service) => {
         const jobs = await service.listJobs(request.params.name);
         return respond((0, send_1.ok)(jobs));
     });
-    // GET /queues/:queue/jobs/:id — job detail
-    pgBossApi.get('/queues/:queue/jobs/:id', 'Get job details', {
+    pgBossApi.get(p('/queues/:queue/jobs/:id'), 'Get job details', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.jobDetailSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -54,8 +47,8 @@ const mountPgBossApiRoutes = (api, service) => {
         }
         return respond((0, send_1.ok)(job));
     });
-    // POST /queues/:queue/jobs/:id/retry — retry a failed job
-    pgBossApi.post('/queues/:queue/jobs/:id/retry', 'Retry a failed job', {
+    pgBossApi.post(p('/queues/:queue/jobs/:id/retry'), 'Retry a failed job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -65,8 +58,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.retryJob(queue, id);
         return respond((0, send_1.ok)({ success: true, jobId: id }));
     });
-    // POST /queues/:queue/jobs/:id/cancel — cancel a job
-    pgBossApi.post('/queues/:queue/jobs/:id/cancel', 'Cancel a job', {
+    pgBossApi.post(p('/queues/:queue/jobs/:id/cancel'), 'Cancel a job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -76,8 +69,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.cancelJob(queue, id);
         return respond((0, send_1.ok)({ success: true, jobId: id }));
     });
-    // DELETE /queues/:queue/jobs/:id — delete a job
-    pgBossApi.delete('/queues/:queue/jobs/:id', 'Delete a job', {
+    pgBossApi.delete(p('/queues/:queue/jobs/:id'), 'Delete a job', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueJobParamsSchema,
@@ -87,15 +80,15 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.deleteJob(queue, id);
         return respond((0, send_1.ok)({ success: true, deleted: id }));
     });
-    // GET /schedules — list cron schedules
-    pgBossApi.get('/schedules', 'List all cron schedules', {
+    pgBossApi.get(p('/schedules'), 'List all cron schedules', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.scheduleArraySchema)],
     }, async (_request, _context, respond) => {
         const schedules = await service.getSchedules();
         return respond((0, send_1.ok)(schedules));
     });
-    // POST /schedules — create a cron schedule
-    pgBossApi.post('/schedules', 'Create a cron schedule', {
+    pgBossApi.post(p('/schedules'), 'Create a cron schedule', {
+        ...mw,
         responses: [(0, response_1.createdResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             body: routes_schema_1.scheduleBodySchema,
@@ -105,8 +98,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.createSchedule(name, cron, data, options);
         return respond((0, send_1.created)({ success: true, name }));
     });
-    // PUT /schedules/:name — update a cron schedule
-    pgBossApi.put('/schedules/:name', 'Update a cron schedule', {
+    pgBossApi.put(p('/schedules/:name'), 'Update a cron schedule', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.scheduleNameParamsSchema,
@@ -117,8 +110,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.updateSchedule(request.params.name, cron, data, options);
         return respond((0, send_1.ok)({ success: true, name: request.params.name }));
     });
-    // DELETE /schedules/:name — delete a cron schedule
-    pgBossApi.delete('/schedules/:name', 'Delete a cron schedule', {
+    pgBossApi.delete(p('/schedules/:name'), 'Delete a cron schedule', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.scheduleNameParamsSchema,
@@ -127,8 +120,8 @@ const mountPgBossApiRoutes = (api, service) => {
         await service.deleteSchedule(request.params.name);
         return respond((0, send_1.ok)({ success: true, deleted: request.params.name }));
     });
-    // POST /queues/:name/jobs — enqueue a new job
-    pgBossApi.post('/queues/:name/jobs', 'Enqueue a new job', {
+    pgBossApi.post(p('/queues/:name/jobs'), 'Enqueue a new job', {
+        ...mw,
         responses: [(0, response_1.createdResponse)(routes_schema_1.successResponseSchema)],
         schemas: {
             params: routes_schema_1.queueNameParamsSchema,
@@ -139,8 +132,8 @@ const mountPgBossApiRoutes = (api, service) => {
         const jobId = await service.enqueueJob(request.params.name, data, options);
         return respond((0, send_1.created)({ success: true, jobId: jobId ?? undefined }));
     });
-    // GET /warnings — recent warnings
-    pgBossApi.get('/warnings', 'List recent warnings', {
+    pgBossApi.get(p('/warnings'), 'List recent warnings', {
+        ...mw,
         responses: [(0, response_1.okResponse)(routes_schema_1.warningArraySchema)],
         schemas: {
             query: routes_schema_1.warningsQuerySchema,

package/dist/lib/pgBoss/helpers.d.ts

@@ -1,5 +1,5 @@
 import { PgBoss } from 'pg-boss';
-import type { SendOptions } from 'pg-boss';
+import type { Job, SendOptions } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { Sequelize, Transaction } from 'sequelize';
 /**
@@ -13,3 +13,11 @@ export declare const enqueueJob: (boss: PgBoss, queueName: string, data: object,
  * instead of calling internal SQL functions directly.
  */
 export declare const enqueueInTransaction: (boss: PgBoss, queueName: string, data: object, options: SendOptions, transaction: Transaction, sequelize: Sequelize) => Promise<string | null>;
+/**
+ * Wrap a pg-boss worker handler so that, when the final retry attempt fails,
+ * a Mattermost DLQ alert is fired before the error is re-thrown.
+ *
+ * Requires the worker to be registered with `{ includeMetadata: true }` so
+ * `retryCount` and `retryLimit` are populated on each job.
+ */
+export declare const withDlqAlerting: <T = object>(queueName: string, handler: (jobs: Job<T>[]) => Promise<void>, logger: Logger, mattermostWebhookUrl?: string) => ((jobs: Job<T>[]) => Promise<void>);

package/dist/lib/pgBoss/helpers.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.enqueueInTransaction = exports.enqueueJob = void 0;
+exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = void 0;
+const metrics_1 = require("./metrics");
 /**
  * Enqueue a job via pg-boss with logging.
  */
@@ -42,3 +43,29 @@ const enqueueInTransaction = async (boss, queueName, data, options, transaction,
     return boss.send(queueName, data, { ...options, db });
 };
 exports.enqueueInTransaction = enqueueInTransaction;
+/**
+ * Wrap a pg-boss worker handler so that, when the final retry attempt fails,
+ * a Mattermost DLQ alert is fired before the error is re-thrown.
+ *
+ * Requires the worker to be registered with `{ includeMetadata: true }` so
+ * `retryCount` and `retryLimit` are populated on each job.
+ */
+const withDlqAlerting = (queueName, handler, logger, mattermostWebhookUrl) => {
+    return async (jobs) => {
+        try {
+            await handler(jobs);
+        }
+        catch (error) {
+            const job = jobs[0];
+            const retryCount = job?.retryCount ?? 0;
+            const retryLimit = job?.retryLimit ?? 0;
+            const isFinalFailure = retryLimit > 0 && retryCount >= retryLimit;
+            if (isFinalFailure && mattermostWebhookUrl && job) {
+                const message = error instanceof Error ? error.message : String(error);
+                await (0, metrics_1.sendDlqAlert)(mattermostWebhookUrl, queueName, job.id, message, logger);
+            }
+            throw error;
+        }
+    };
+};
+exports.withDlqAlerting = withDlqAlerting;

package/dist/lib/pgBoss/index.d.ts

@@ -2,28 +2,41 @@ import { PgBoss } from 'pg-boss';
 import type { Logger } from 'pino';
 import type { PgBossConfig } from './types';
 export { PgBoss };
+export type { Job, SendOptions } from 'pg-boss';
 export type { PgBossConfig, QueueDefinition, WorkerRegistration, PgBossInstance, } from './types';
 export { PG_BOSS_DEFAULTS, buildPgBossDefaults } from './config';
 export { mountPgBossApiRoutes } from './controller/routes';
 export { PgBossService } from './service';
 export { registerPgBossMetrics } from './metrics';
-export { enqueueJob, enqueueInTransaction } from './helpers';
+export { enqueueJob, enqueueInTransaction, withDlqAlerting } from './helpers';
 export { sendDlqAlert } from './metrics';
 export interface PgBossContext {
     boss: PgBoss;
     logger: Logger;
     config: Required<PgBossConfig>;
+    serviceName: string;
+    metricsInterval?: NodeJS.Timeout;
 }
 /**
  * Creates a pg-boss instance with error recovery (auto-restart on connection loss).
  * Issue #510 mitigation: on error, waits 5s then restarts.
  */
-export declare const createPgBoss: (config: PgBossConfig, logger: Logger) => PgBossContext;
+export declare const createPgBoss: (config: PgBossConfig, logger: Logger, serviceName?: string) => PgBossContext;
 /**
- * Starts the pg-boss instance. Call after database is connected.
+ * Starts the pg-boss instance and registers Prometheus metrics polling.
+ * Call after database is connected.
  */
 export declare const startBoss: (ctx: PgBossContext) => Promise<void>;
 /**
- * Gracefully stops the pg-boss instance. Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance and clears metrics polling.
+ * Suitable as a shutdown handler.
  */
 export declare const stopBoss: (ctx: PgBossContext) => Promise<void>;
+/**
+ * Maps the legacy `deleteAfterDays` setting to pg-boss v12's
+ * per-queue `deleteAfterSeconds` option. Use this when calling
+ * `boss.createQueue(name, { ...defaultRetention(ctx), policy: 'singleton' })`.
+ */
+export declare const defaultRetention: (ctx: PgBossContext) => {
+    deleteAfterSeconds: number;
+};

package/dist/lib/pgBoss/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.sendDlqAlert = exports.enqueueInTransaction = exports.enqueueJob = exports.registerPgBossMetrics = exports.PgBossService = exports.mountPgBossApiRoutes = exports.buildPgBossDefaults = exports.PG_BOSS_DEFAULTS = exports.PgBoss = void 0;
+exports.defaultRetention = exports.stopBoss = exports.startBoss = exports.createPgBoss = exports.sendDlqAlert = exports.withDlqAlerting = exports.enqueueInTransaction = exports.enqueueJob = exports.registerPgBossMetrics = exports.PgBossService = exports.mountPgBossApiRoutes = exports.buildPgBossDefaults = exports.PG_BOSS_DEFAULTS = exports.PgBoss = void 0;
 const pg_boss_1 = require("pg-boss");
 Object.defineProperty(exports, "PgBoss", { enumerable: true, get: function () { return pg_boss_1.PgBoss; } });
 const config_1 = require("./config");
+const metrics_1 = require("./metrics");
 var config_2 = require("./config");
 Object.defineProperty(exports, "PG_BOSS_DEFAULTS", { enumerable: true, get: function () { return config_2.PG_BOSS_DEFAULTS; } });
 Object.defineProperty(exports, "buildPgBossDefaults", { enumerable: true, get: function () { return config_2.buildPgBossDefaults; } });
@@ -11,24 +12,27 @@ var routes_1 = require("./controller/routes");
 Object.defineProperty(exports, "mountPgBossApiRoutes", { enumerable: true, get: function () { return routes_1.mountPgBossApiRoutes; } });
 var service_1 = require("./service");
 Object.defineProperty(exports, "PgBossService", { enumerable: true, get: function () { return service_1.PgBossService; } });
-var metrics_1 = require("./metrics");
-Object.defineProperty(exports, "registerPgBossMetrics", { enumerable: true, get: function () { return metrics_1.registerPgBossMetrics; } });
+var metrics_2 = require("./metrics");
+Object.defineProperty(exports, "registerPgBossMetrics", { enumerable: true, get: function () { return metrics_2.registerPgBossMetrics; } });
 var helpers_1 = require("./helpers");
 Object.defineProperty(exports, "enqueueJob", { enumerable: true, get: function () { return helpers_1.enqueueJob; } });
 Object.defineProperty(exports, "enqueueInTransaction", { enumerable: true, get: function () { return helpers_1.enqueueInTransaction; } });
-var metrics_2 = require("./metrics");
-Object.defineProperty(exports, "sendDlqAlert", { enumerable: true, get: function () { return metrics_2.sendDlqAlert; } });
+Object.defineProperty(exports, "withDlqAlerting", { enumerable: true, get: function () { return helpers_1.withDlqAlerting; } });
+var metrics_3 = require("./metrics");
+Object.defineProperty(exports, "sendDlqAlert", { enumerable: true, get: function () { return metrics_3.sendDlqAlert; } });
 const RESTART_DELAY_MS = 5000;
+const SECONDS_PER_DAY = 86_400;
 /**
  * Creates a pg-boss instance with error recovery (auto-restart on connection loss).
  * Issue #510 mitigation: on error, waits 5s then restarts.
  */
-const createPgBoss = (config, logger) => {
+const createPgBoss = (config, logger, serviceName = config.schema) => {
     const resolvedConfig = (0, config_1.buildPgBossDefaults)(config);
     const boss = new pg_boss_1.PgBoss({
         connectionString: resolvedConfig.connectionString,
         schema: resolvedConfig.schema,
         application_name: resolvedConfig.applicationName,
+        max: resolvedConfig.maxConnectionPoolSize,
         migrate: true,
     });
     boss.on('error', (error) => {
@@ -38,27 +42,43 @@ const createPgBoss = (config, logger) => {
     boss.on('warning', warning => {
         logger.warn({ warning }, 'pg-boss warning');
     });
-    return { boss, logger, config: resolvedConfig };
+    return { boss, logger, config: resolvedConfig, serviceName };
 };
 exports.createPgBoss = createPgBoss;
 /**
- * Starts the pg-boss instance. Call after database is connected.
+ * Starts the pg-boss instance and registers Prometheus metrics polling.
+ * Call after database is connected.
  */
 const startBoss = async (ctx) => {
     ctx.logger.info({ schema: ctx.config.schema }, 'Starting pg-boss');
     await ctx.boss.start();
+    ctx.metricsInterval = (0, metrics_1.registerPgBossMetrics)(ctx.boss, ctx.serviceName, ctx.logger, ctx.config.mattermostWebhookUrl || undefined);
     ctx.logger.info({ schema: ctx.config.schema }, 'pg-boss started successfully');
 };
 exports.startBoss = startBoss;
 /**
- * Gracefully stops the pg-boss instance. Suitable as a shutdown handler.
+ * Gracefully stops the pg-boss instance and clears metrics polling.
+ * Suitable as a shutdown handler.
  */
 const stopBoss = async (ctx) => {
     ctx.logger.info({ schema: ctx.config.schema }, 'Stopping pg-boss');
+    if (ctx.metricsInterval) {
+        clearInterval(ctx.metricsInterval);
+        ctx.metricsInterval = undefined;
+    }
     await ctx.boss.stop({ graceful: true, timeout: 30_000 });
     ctx.logger.info({ schema: ctx.config.schema }, 'pg-boss stopped');
 };
 exports.stopBoss = stopBoss;
+/**
+ * Maps the legacy `deleteAfterDays` setting to pg-boss v12's
+ * per-queue `deleteAfterSeconds` option. Use this when calling
+ * `boss.createQueue(name, { ...defaultRetention(ctx), policy: 'singleton' })`.
+ */
+const defaultRetention = (ctx) => ({
+    deleteAfterSeconds: ctx.config.deleteAfterDays * SECONDS_PER_DAY,
+});
+exports.defaultRetention = defaultRetention;
 const scheduleRestart = (boss, logger) => {
     setTimeout(async () => {
         try {

package/dist/lib/pgBoss/metrics.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };

package/dist/lib/pgBoss/service/manageJob.js

@@ -4,7 +4,7 @@ exports.manageJob = void 0;
 const manageJob = async (boss, logger, action, queueName, jobId) => {
     switch (action) {
         case 'retry':
-            await boss.resume(queueName, jobId);
+            await boss.retry(queueName, jobId);
             break;
         case 'cancel':
             await boss.cancel(queueName, jobId);

package/dist/lib/phone/phone.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizePhoneNumber = exports.getPhoneType = exports.getPhoneCountry = exports.parsePhone = exports.formatPhoneNumber = exports.tryParsePhoneNumber = exports.getFormattedPhoneNumber = exports.isValidMobilePhoneNumber = exports.isValidPhoneNumber = exports.OutputFormat = void 0;
 const max_1 = __importStar(require("libphonenumber-js/max"));

package/dist/lib/serviceIdentity/service.d.ts

@@ -3,6 +3,7 @@ declare enum Service {
     BACKEND_PAY = "backend-pay",
     BACKEND_POS = "backend-pos",
     BACKEND_PUBSUB = "backend-pubsub",
+    BACKEND_TSE = "backend-tse",
     BACKEND_PYTHON = "backend-python",
     BACKEND_LINK = "backend-link",
     MASTRA = "mastra",

package/dist/lib/serviceIdentity/service.js

@@ -7,6 +7,7 @@ var Service;
     Service["BACKEND_PAY"] = "backend-pay";
     Service["BACKEND_POS"] = "backend-pos";
     Service["BACKEND_PUBSUB"] = "backend-pubsub";
+    Service["BACKEND_TSE"] = "backend-tse";
     Service["BACKEND_PYTHON"] = "backend-python";
     Service["BACKEND_LINK"] = "backend-link";
     Service["MASTRA"] = "mastra";

package/dist/lib/serviceIdentity/serviceIdentity.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -15,7 +15,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:ci": "VITEST_JUNIT_SUITE_NAME=service-utils CI=true vitest run --coverage",
-    "audit": "sh ../../scripts/cached-audit.sh improved-yarn-audit --ignore-dev-deps"
+    "audit:osv": "yarn-osv-audit"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "10.0.3",
@@ -24,7 +24,7 @@
     "@aws-sdk/lib-storage": "^3.1035.0",
     "@hapi/boom": "^10.0.1",
     "@sentry/node": "^9.10.1",
-    "@tsconfig/node22": "22.0.0",
+    "@tsconfig/node24": "24.0.0",
     "@types/express": "4.17.23",
     "@types/express-serve-static-core": "^4.17.43",
     "@types/node": "22.13.11",
@@ -74,12 +74,12 @@
     "eslint": "8.57.0",
     "eslint-plugin-prettier": "4.2.1",
     "eslint-plugin-vitest": "0.4.1",
-    "improved-yarn-audit": "^3.0.4",
+    "yarn-osv-audit": "0.1.8",
     "prettier": "2.7.1",
     "semantic-release": "^25.0.3",
     "semantic-release-monorepo": "8.0.2",
-    "supertest": "^6.3.3",
-    "typescript": "5.5.3",
+    "supertest": "6.3.4",
+    "typescript": "6.0.2",
     "vite-tsconfig-paths": "4.3.2",
     "vitest": "4.1.1"
   },