@lucaapp/service-utils 5.15.0 → 5.16.0

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

@@ -6,6 +6,7 @@ export type OperatorDevice = {
     role: OperatorDeviceRole;
     operatorId: string;
     locationId: string | null;
+    terminalId: string | null;
     createdAt: Date;
     updatedAt: Date;
 };

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

@@ -1,205 +1,90 @@
 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;
-    /** Short verifier token used by consumer-facing flows to prove ownership of the payment session. */
     paymentVerifier: string;
-    /** 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 declare const PAYMENT_LEGACY_VERSION = 1;
+export type PaymentLegacyVersion = typeof PAYMENT_LEGACY_VERSION;
 export type Payment = PaymentBase & {
-    /** Total paid by the consumer (= `invoiceAmount + tipAmount`), in the smallest currency subunit. Kept for legacy consumers. */
+    version: PaymentLegacyVersion;
     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;
-    /** 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;
 };
-/**
- * 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 declare const PAYMENT_EVENT_VERSION = 2;
+export type PaymentEventVersion = typeof PAYMENT_EVENT_VERSION;
 export type PaymentEvent = PaymentBase & {
-    /** Checkout session id. Optional — some flows emit payment events without a checkout. */
+    version: PaymentEventVersion;
     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,15 +1,9 @@
 "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). */
+exports.operatorReceivableAmount = exports.consumerPayAmount = exports.PAYMENT_EVENT_VERSION = exports.PAYMENT_LEGACY_VERSION = void 0;
+exports.PAYMENT_LEGACY_VERSION = 1;
+exports.PAYMENT_EVENT_VERSION = 2;
 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

@@ -1,4 +1,4 @@
-import type { Payment } from './events/payment';
+import type { Payment, PaymentEvent } from './events/payment';
 import type { Consumer } from './events/consumer';
 import type { Operator } from './events/operator';
 import type { LocationGroupEmployees } from './events/locationGroupEmployees';
@@ -39,7 +39,7 @@ declare enum KafkaTopic {
     TOKENIZATION_JOB_ITEM = "tokenization_job_item"
 }
 type MessageFormats = {
-    [KafkaTopic.PAYMENTS]: Payment;
+    [KafkaTopic.PAYMENTS]: Payment | PaymentEvent;
     [KafkaTopic.CONSUMERS]: Consumer;
     [KafkaTopic.OPERATORS]: Operator;
     [KafkaTopic.OPERATORS_PAY]: OperatorPay;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.15.0",
+  "version": "5.16.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -86,7 +86,7 @@
   "resolutions": {
     "tar": "^7.5.11",
     "lodash": "^4.18.1",
-    "qs": "^6.14.2",
+    "qs": "6.15.2",
     "dottie": "2.0.7",
     "fast-xml-parser": "^5.7.1",
     "yaml": "^2.8.3",
@@ -100,6 +100,7 @@
     "axios": "1.16.0",
     "path-to-regexp": "0.1.13",
     "ip-address": "10.1.1",
-    "fast-xml-builder": "^1.1.7"
+    "fast-xml-builder": "^1.1.7",
+    "brace-expansion": "2.0.3"
   }
 }