@lucaapp/service-utils 5.30.0 → 5.32.0

package/dist/lib/api/api.d.ts

@@ -13,6 +13,17 @@ type ApiConstructorOptions = {
      * stays hidden. Routing is unaffected; this only controls documentation.
      */
     hidden?: boolean;
+    /**
+     * Paths kept out of the generated OpenAPI spec, matched against the full
+     * registered path including the prefix. A string must match exactly; a
+     * RegExp is tested against it. Inherited by children.
+     *
+     * This is the central place to keep routes undocumented, so the decision
+     * lives in one list next to the Api rather than spread across the route
+     * files it applies to. `hidden` on a single endpoint does the same thing at
+     * the definition site; prefer this list when the routes share a reason.
+     */
+    excludeFromSpec?: ReadonlyArray<string | RegExp>;
     openApiVersion?: OpenApiVersion;
     apiVersion?: string;
     apiTitle?: string;
@@ -39,6 +50,7 @@ export declare class Api {
     debug: boolean;
     tags: string[];
     private hidden;
+    private excludeFromSpec;
     constructor(options?: ApiConstructorOptions);
     child(options: ApiChildOptions): Api;
     get<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;

package/dist/lib/api/api.js

@@ -31,6 +31,7 @@ class Api {
         this.debug = options.debug || false;
         this.tags = options.tags || [];
         this.hidden = options.hidden || false;
+        this.excludeFromSpec = options.excludeFromSpec || [];
         this.router.use(body_parser_1.default.json({ verify: rawBodySaver, limit: '2mb' }));
     }
     child(options) {
@@ -42,29 +43,30 @@ class Api {
             router: this.router,
             // Once hidden, always hidden: a child cannot re-expose its parent's tree.
             hidden: this.hidden || options.hidden || false,
+            excludeFromSpec: this.excludeFromSpec,
         });
         child.rootPrefixPath = this.rootPrefixPath;
         return child;
     }
     get(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'get', path, options, handler, this.debug);
-        (0, openapi_1.registerEndpoint)(this.registry, 'get', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
+        (0, openapi_1.registerEndpoint)(this.registry, 'get', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden, this.excludeFromSpec);
     }
     post(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'post', path, options, handler, this.debug);
-        (0, openapi_1.registerEndpoint)(this.registry, 'post', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
+        (0, openapi_1.registerEndpoint)(this.registry, 'post', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden, this.excludeFromSpec);
     }
     patch(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'patch', path, options, handler, this.debug);
-        (0, openapi_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
+        (0, openapi_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden, this.excludeFromSpec);
     }
     put(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'put', path, options, handler, this.debug);
-        (0, openapi_1.registerEndpoint)(this.registry, 'put', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
+        (0, openapi_1.registerEndpoint)(this.registry, 'put', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden, this.excludeFromSpec);
     }
     delete(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'delete', path, options, handler, this.debug);
-        (0, openapi_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
+        (0, openapi_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden, this.excludeFromSpec);
     }
     generateOpenAPISpec() {
         let generator;

package/dist/lib/api/openapi.d.ts

@@ -25,5 +25,5 @@ export declare const hoistCombinatorRequiredFields: (spec: {
         schemas?: Record<string, unknown>;
     };
 }) => void;
-export declare const registerEndpoint: (registry: OpenAPIRegistry, method: HttpMethod, prefixPath: string, rootPrefixPath: string, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, tags: string[], debug: boolean, hiddenApi?: boolean) => void;
+export declare const registerEndpoint: (registry: OpenAPIRegistry, method: HttpMethod, prefixPath: string, rootPrefixPath: string, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, tags: string[], debug: boolean, hiddenApi?: boolean, excludeFromSpec?: ReadonlyArray<string | RegExp>) => void;
 export {};

package/dist/lib/api/openapi.js

@@ -227,11 +227,16 @@ const hoistCombinatorRequiredFields = (spec) => {
 exports.hoistCombinatorRequiredFields = hoistCombinatorRequiredFields;
 const registerEndpoint = (registry, method, prefixPath, rootPrefixPath, path, summary, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-options, tags, debug, hiddenApi = false) => {
+options, tags, debug, hiddenApi = false, excludeFromSpec = []) => {
     // Hidden endpoints are never registered, so they leave no path, no
     // operationId and no security behind. Checked before any schema work: there
     // is nothing to build for an operation that will not be published.
-    if (hiddenApi || options.hidden) {
+    //
+    // The exclusion list is matched against the same path string the spec would
+    // have used, so an entry can be copied straight out of a generated spec.
+    const specPath = mapExpressParamsToOpenAPIParams(prefixPath + path);
+    const excluded = excludeFromSpec.some(pattern => typeof pattern === 'string' ? pattern === specPath : pattern.test(specPath));
+    if (hiddenApi || options.hidden || excluded) {
         return;
     }
     let bodySchema = options.schemas?.body || undefined;

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

@@ -0,0 +1,48 @@
+import { SupportedCurrencies } from '../../money/supportedCurrencies';
+export declare const ORDER_EVENT_VERSION = 1;
+export type OrderEventVersion = typeof ORDER_EVENT_VERSION;
+/**
+ * luca-web order types mirrored to downstream consumers (LUCA-36037).
+ * String-typed on the wire to stay decoupled from backend-pay's OrderType enum;
+ * these are the currently-produced values.
+ */
+export type OrderEventType = 'HOTEL_SPECIAL_OFFER' | 'HOTEL_MINI_BAR' | 'IN_ROOM_ORDER' | 'QR_CODE_ORDER' | 'SELF_SERVICE_SHOP_ORDER' | 'PRE_ORDER' | 'TERMINAL_ORDER';
+export type OrderEventStatus = 'OPEN' | 'PAID' | 'REFUNDED';
+/**
+ * Localised display text keyed by locale; `de` is always present.
+ * Mirrors the menu snapshot backend-pay stores on the order line.
+ */
+export type OrderEventTranslatableName = {
+    de: string;
+    en?: string;
+    [locale: string]: string | undefined;
+};
+export type OrderEventItem = {
+    name: OrderEventTranslatableName;
+    quantity: number;
+    /** Unit price in minor units (cents). */
+    price: number;
+    /** VAT rate in percent, when known. */
+    tax?: number;
+    subItems?: OrderEventItem[];
+};
+/**
+ * Emitted by backend-pay when a luca-web order is created (LUCA-36037).
+ * Carries the full order snapshot so consumers can mirror it without a callback.
+ */
+export type OrderEvent = {
+    version: OrderEventVersion;
+    uuid: string;
+    orderRef: string;
+    type: OrderEventType | null;
+    status: OrderEventStatus;
+    locationId: string;
+    locationGroupId: string;
+    currency: SupportedCurrencies;
+    /** Invoice total in minor units (cents). */
+    invoiceAmount: number;
+    table: string | null;
+    note: string | null;
+    createdAt: Date;
+    items: OrderEventItem[];
+};

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

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDER_EVENT_VERSION = void 0;
+exports.ORDER_EVENT_VERSION = 1;

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

@@ -70,6 +70,12 @@ export type PaymentEvent = {
     paymentVerifier: string;
     checkoutId?: string;
     orderId?: string;
+    /**
+     * backend-pay Orders.uuid[] linked to this payment's checkout (LUCA-36037).
+     * Distinct from the singular `orderId` (the luca-POS order id). A checkout can
+     * cover multiple orders, so this is a list. Absent for non-web payments.
+     */
+    payOrderIds?: string[] | null;
     statusCompleteAt?: Date | null;
     merchantDetails?: PaymentMerchantDetails;
 } & PaymentEventCardAcquirerFields;

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

@@ -27,4 +27,6 @@ export type RefundEvent = {
     checkoutId?: string | null;
     /** Payment method of the original payment (e.g. CARD). */
     method?: string | null;
+    /** Optional on the wire for in-flight events produced before this field existed. */
+    reason?: string | null;
 };

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

@@ -1,4 +1,5 @@
 import type { Payment, PaymentEvent } from './events/payment';
+import type { OrderEvent } from './events/order';
 import type { RefundEvent } from './events/refund';
 import type { Consumer } from './events/consumer';
 import type { Operator } from './events/operator';
@@ -20,6 +21,7 @@ import { TokenizationJobItem } from './events/tokenizationJobItem';
 import { Organization, OperatorOrganization } from '../../types/organization';
 declare enum KafkaTopic {
     PAYMENTS = "payments",
+    ORDERS = "orders",
     REFUNDS = "refunds",
     CONSUMERS = "consumers",
     OPERATORS = "operators",
@@ -44,6 +46,7 @@ declare enum KafkaTopic {
 }
 type MessageFormats = {
     [KafkaTopic.PAYMENTS]: Payment | PaymentEvent;
+    [KafkaTopic.ORDERS]: OrderEvent;
     [KafkaTopic.REFUNDS]: RefundEvent;
     [KafkaTopic.CONSUMERS]: Consumer;
     [KafkaTopic.OPERATORS]: Operator;
@@ -68,6 +71,7 @@ type MessageFormats = {
 };
 declare const MessageIssuer: {
     payments: Service;
+    orders: Service;
     refunds: Service;
     consumers: Service;
     operators: Service;

package/dist/lib/kafka/events.js

@@ -5,6 +5,7 @@ const serviceIdentity_1 = require("../serviceIdentity");
 var KafkaTopic;
 (function (KafkaTopic) {
     KafkaTopic["PAYMENTS"] = "payments";
+    KafkaTopic["ORDERS"] = "orders";
     KafkaTopic["REFUNDS"] = "refunds";
     KafkaTopic["CONSUMERS"] = "consumers";
     KafkaTopic["OPERATORS"] = "operators";
@@ -29,6 +30,7 @@ var KafkaTopic;
 })(KafkaTopic || (exports.KafkaTopic = KafkaTopic = {}));
 const MessageIssuer = {
     [KafkaTopic.PAYMENTS]: serviceIdentity_1.Service.BACKEND_PAY,
+    [KafkaTopic.ORDERS]: serviceIdentity_1.Service.BACKEND_PAY,
     [KafkaTopic.REFUNDS]: serviceIdentity_1.Service.BACKEND_PAY,
     [KafkaTopic.CONSUMERS]: serviceIdentity_1.Service.BACKEND,
     [KafkaTopic.OPERATORS]: serviceIdentity_1.Service.BACKEND,
@@ -54,5 +56,6 @@ const MessageIssuer = {
 exports.MessageIssuer = MessageIssuer;
 const MessageSignatureIssuers = {
     [KafkaTopic.PAYMENTS]: [serviceIdentity_1.Service.BACKEND_PAY, serviceIdentity_1.Service.BACKEND_TSE],
+    [KafkaTopic.ORDERS]: [serviceIdentity_1.Service.BACKEND_PAY],
 };
 exports.MessageSignatureIssuers = MessageSignatureIssuers;

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

@@ -3,4 +3,6 @@ export { KafkaTopic } from './events';
 export type { ConversationMessage } from './events/conversationMessage';
 export type { RefundEvent } from './events/refund';
 export { REFUND_EVENT_VERSION } from './events/refund';
+export type { OrderEvent, OrderEventItem, OrderEventType, OrderEventStatus, OrderEventTranslatableName, } from './events/order';
+export { ORDER_EVENT_VERSION } from './events/order';
 export type { KafkaEvent, GenericKafkaEvent, EventPayloadHandler, GenericEventPayloadHandler, KafkaConfiguration, CustomTopicConfig, CustomTopicPoisonContext, CustomTopicPoisonHandler, } from './types';

package/dist/lib/kafka/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFUND_EVENT_VERSION = exports.KafkaTopic = exports.KafkaClient = void 0;
+exports.ORDER_EVENT_VERSION = exports.REFUND_EVENT_VERSION = exports.KafkaTopic = exports.KafkaClient = void 0;
 var kafkaClient_1 = require("./kafkaClient");
 Object.defineProperty(exports, "KafkaClient", { enumerable: true, get: function () { return kafkaClient_1.KafkaClient; } });
 var events_1 = require("./events");
 Object.defineProperty(exports, "KafkaTopic", { enumerable: true, get: function () { return events_1.KafkaTopic; } });
 var refund_1 = require("./events/refund");
 Object.defineProperty(exports, "REFUND_EVENT_VERSION", { enumerable: true, get: function () { return refund_1.REFUND_EVENT_VERSION; } });
+var order_1 = require("./events/order");
+Object.defineProperty(exports, "ORDER_EVENT_VERSION", { enumerable: true, get: function () { return order_1.ORDER_EVENT_VERSION; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -105,7 +105,7 @@
     "fast-xml-builder": "^1.1.7",
     "brace-expansion": "2.1.4",
     "form-data": "4.0.6",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
     "@opentelemetry/core": "2.8.0"
   }
 }