@lucaapp/service-utils 5.38.0 → 5.40.0

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

@@ -0,0 +1,24 @@
+import * as Sentry from '@sentry/node';
+import type { ErrorRequestHandler } from 'express';
+export type ErrorReportingOptions = {
+    dsn?: string;
+    serviceName: string;
+    environment?: string;
+    release?: string;
+    flushTimeoutMs?: number;
+};
+export type ServerErrorContext = {
+    method?: string;
+    route?: string;
+    reqId?: string;
+};
+export declare const scrubString: (value: string) => string;
+export declare const scrubValue: (value: unknown, depth?: number) => unknown;
+export declare const scrubEvent: <T extends Sentry.Event>(event: T) => T;
+export declare const initErrorReporting: (options: ErrorReportingOptions) => boolean;
+export declare const isErrorReportingEnabled: () => boolean;
+export declare const statusOf: (error: unknown) => number;
+export declare const captureServerError: (error: unknown, context?: ServerErrorContext) => void;
+export declare const errorReportingHandler: ErrorRequestHandler;
+export declare const exitAfterReport: (error: unknown) => void;
+export declare const closeErrorReporting: () => Promise<void>;

package/dist/lib/errorReporting/index.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+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.closeErrorReporting = exports.exitAfterReport = exports.errorReportingHandler = exports.captureServerError = exports.statusOf = exports.isErrorReportingEnabled = exports.initErrorReporting = exports.scrubEvent = exports.scrubValue = exports.scrubString = void 0;
+const Sentry = __importStar(require("@sentry/node"));
+const boom_1 = require("@hapi/boom");
+const DEFAULT_FLUSH_TIMEOUT_MS = 800;
+const MAX_DEPTH = 8;
+const FILTERED = '[Filtered]';
+const SENSITIVE_KEY = /auth|cookie|token|secret|passw|passcode|^pin$|session|e-?mail|phone|iban|card|(^|_)pan($|_|number)|cvc|cvv|shopper|reservation|booking|confirmation|(^|_)name$|surname|(first|last|full|guest|holder)_?name|address|birth|passport|signature|tax_?id|vat|api_?key/i;
+const digitCount = (value) => value.replaceAll(/\D/g, '').length;
+const STRING_PATTERNS = [
+    [/eyJ[\w-]+\.[\w-]+\.[\w-]+(?:\.[\w-]+\.[\w-]+)?/g, () => '[jwt]'],
+    [
+        /\b(bearer|basic)\s+[\w+./=~-]+/gi,
+        (_match, scheme) => `${scheme} ${FILTERED}`,
+    ],
+    [/[\w+.-]+@[\w-]+\.[\w.-]+/g, () => '[email]'],
+    [
+        /\b[A-Z]{2}\d{2}[\d A-Z]{11,32}\b/gi,
+        match => (digitCount(match) >= 10 ? '[iban]' : match),
+    ],
+    [
+        /\d[\d -]{11,}\d/g,
+        match => {
+            const digits = digitCount(match);
+            return digits >= 13 && digits <= 19 ? '[number]' : match;
+        },
+    ],
+];
+let enabled = false;
+let flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS;
+const scrubString = (value) => {
+    let result = value;
+    for (const [pattern, replacement] of STRING_PATTERNS) {
+        result = result.replace(pattern, replacement);
+    }
+    return result;
+};
+exports.scrubString = scrubString;
+const scrubValue = (value, depth = 0) => {
+    if (typeof value === 'string')
+        return (0, exports.scrubString)(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= MAX_DEPTH)
+        return FILTERED;
+    if (Buffer.isBuffer(value))
+        return '[Buffer]';
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime())
+            ? '[Invalid Date]'
+            : value.toISOString();
+    if (Array.isArray(value))
+        return value.map(item => (0, exports.scrubValue)(item, depth + 1));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        SENSITIVE_KEY.test(key) ? FILTERED : (0, exports.scrubValue)(item, depth + 1),
+    ]));
+};
+exports.scrubValue = scrubValue;
+const scrubBreadcrumb = (breadcrumb) => ({
+    ...breadcrumb,
+    ...(breadcrumb.message && { message: (0, exports.scrubString)(breadcrumb.message) }),
+    ...(breadcrumb.data && {
+        data: (0, exports.scrubValue)(breadcrumb.data),
+    }),
+});
+const scrubEvent = (event) => {
+    const { message, extra, contexts, tags, breadcrumbs, exception, request, user, } = event;
+    return {
+        ...event,
+        ...(message && { message: (0, exports.scrubString)(message) }),
+        ...(extra && { extra: (0, exports.scrubValue)(extra) }),
+        ...(contexts && { contexts: (0, exports.scrubValue)(contexts) }),
+        ...(tags && { tags: (0, exports.scrubValue)(tags) }),
+        ...(breadcrumbs && {
+            breadcrumbs: breadcrumbs.map(breadcrumb => scrubBreadcrumb(breadcrumb)),
+        }),
+        ...(exception?.values && {
+            exception: {
+                ...exception,
+                values: exception.values.map(value => ({
+                    ...value,
+                    ...(value.value && { value: (0, exports.scrubString)(value.value) }),
+                })),
+            },
+        }),
+        request: request && {
+            method: request.method,
+            url: request.url && (0, exports.scrubString)(request.url.split(/[?#]/, 1)[0] ?? ''),
+        },
+        user: user?.id === undefined ? undefined : { id: user.id },
+    };
+};
+exports.scrubEvent = scrubEvent;
+const initErrorReporting = (options) => {
+    if (!options.dsn) {
+        enabled = false;
+        return false;
+    }
+    Sentry.init({
+        dsn: options.dsn,
+        environment: options.environment,
+        release: options.release,
+        serverName: options.serviceName,
+        sendDefaultPii: false,
+        skipOpenTelemetrySetup: true,
+        defaultIntegrations: false,
+        integrations: [
+            Sentry.eventFiltersIntegration(),
+            Sentry.functionToStringIntegration(),
+            Sentry.linkedErrorsIntegration(),
+            Sentry.dedupeIntegration(),
+            Sentry.contextLinesIntegration(),
+            Sentry.nodeContextIntegration(),
+        ],
+        beforeSend: event => (0, exports.scrubEvent)(event),
+        beforeBreadcrumb: breadcrumb => scrubBreadcrumb(breadcrumb),
+    });
+    flushTimeoutMs = options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
+    enabled = true;
+    return true;
+};
+exports.initErrorReporting = initErrorReporting;
+const isErrorReportingEnabled = () => enabled;
+exports.isErrorReportingEnabled = isErrorReportingEnabled;
+const statusOf = (error) => {
+    if ((0, boom_1.isBoom)(error))
+        return error.output.statusCode;
+    if (error instanceof Error &&
+        (error.name === 'SessionError' || error.constructor.name === 'SessionError'))
+        return 401;
+    const { statusCode, status } = (error ?? {});
+    if (typeof statusCode === 'number')
+        return statusCode;
+    if (typeof status === 'number')
+        return status;
+    return 500;
+};
+exports.statusOf = statusOf;
+const captureServerError = (error, context = {}) => {
+    if (!enabled || (0, exports.statusOf)(error) < 500)
+        return;
+    const tags = Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined));
+    Sentry.captureException(error, { tags });
+};
+exports.captureServerError = captureServerError;
+const routeOf = (request) => request.route?.path
+    ? `${request.baseUrl ?? ''}${request.route.path}`
+    : '[unmatched]';
+const errorReportingHandler = (error, request, _response, next) => {
+    try {
+        (0, exports.captureServerError)(error, {
+            method: request.method,
+            route: routeOf(request),
+            ...(request.id !== undefined && { reqId: String(request.id) }),
+        });
+    }
+    catch { }
+    next(error);
+};
+exports.errorReportingHandler = errorReportingHandler;
+const exitAfterReport = (error) => {
+    if (enabled) {
+        try {
+            Sentry.captureException(error, { level: 'fatal' });
+            Sentry.flush(flushTimeoutMs)
+                .then(() => process.exit(1))
+                .catch(() => process.exit(1));
+        }
+        catch {
+            process.exit(1);
+        }
+    }
+    else {
+        process.exit(1);
+    }
+};
+exports.exitAfterReport = exitAfterReport;
+const closeErrorReporting = async () => {
+    if (enabled) {
+        enabled = false;
+        await Sentry.close(flushTimeoutMs);
+    }
+};
+exports.closeErrorReporting = closeErrorReporting;

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

@@ -1,36 +1,35 @@
 export declare const FISCALIZED_PAYMENT_EVENT_VERSION = 1;
 export type FiscalizedPaymentEventVersion = typeof FISCALIZED_PAYMENT_EVENT_VERSION;
 /**
- * Emitted by backend-tse when a payment's fiscalization reaches a terminal
- * ready state (signed and receipt PDF materializable).
- * Consumers (e.g. backend-pay) use this instead of polling readiness.
- *
- * ID fields are intentionally distinct — they are not always equal:
- * - POS checkout fast-path can create `fiscal_payment_events` under a throwaway
- *   Kafka uuid before `V3Payment` exists; TSE then reuses that fiscal row via
- *   `checkoutId` and does not rewrite the fiscal id to `V3Payment.uuid`.
- * - Cash / HTTP paths often have no `V3Payment` at all.
+ * Final fiscalization outcome of a payment, decided by backend-tse:
+ * - `FISCALIZED`: the Kassenbeleg is final — signed with its receipt PDF
+ *   materializable, or issued in Notfallmodus.
+ * - `NOT_FISCALIZED`: backend-tse will never fiscalize this payment (a luca-web
+ *   QR / self-service payment at a location that does not fiscalize web
+ *   orders). There is no fiscal row and no Kassenbeleg.
+ */
+export type FiscalizedPaymentStatus = 'FISCALIZED' | 'NOT_FISCALIZED';
+/**
+ * Emitted by backend-tse once a payment's fiscalization outcome is final, so
+ * consumers (backend-pay) need not poll readiness. Delivery is at least once:
+ * dedupe on the envelope `id` (the fiscal payment id, or the payment id when
+ * NOT_FISCALIZED).
  */
 export type FiscalizedPayment = {
     version: FiscalizedPaymentEventVersion;
+    status: FiscalizedPaymentStatus;
     /**
-     * `fiscal_payment_events.id` — TSE primary key used for receipt-token /
-     * readiness / PDF. Always present. Envelope `id` should match this.
-     */
-    fiscalPaymentEventId: string;
-    locationId: string;
-    /**
-     * backend-pay `V3Payment.uuid` when TSE knows it (settled Kafka card/web
-     * path). May differ from `fiscalPaymentEventId` after fast-path reuse.
-     * Absent for cash / when only a throwaway Kafka uuid was seen.
+     * backend-pay `V3Payment.uuid` for luca-web QR / self-service payments. Null
+     * for POS card payments (backend-tse cannot tell the real uuid from the
+     * fast-path one) and cash; resolve those via `checkoutId`.
      */
-    paymentId?: string | null;
+    paymentId: string | null;
     /**
-     * backend-pay `V3Checkout.uuid` when known. Join key when
-     * `fiscalPaymentEventId` ≠ `paymentId`.
+     * `fiscal_payment_events.id` — the key for the receipt token / PDF. Null when
+     * NOT_FISCALIZED.
      */
-    checkoutId?: string | null;
-    notfallmodus?: boolean;
-    tseSigningEventId?: string | null;
-    statusCompleteAt?: Date | null;
+    fiscalPaymentEventId: string | null;
+    locationId: string;
+    /** backend-pay `V3Checkout.uuid` for card / web payments. */
+    checkoutId: string | null;
 };

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

@@ -26,6 +26,19 @@ export type OrderEventItem = {
     tax?: number;
     subItems?: OrderEventItem[];
 };
+/**
+ * Legal / billing details of the location group, printed as the Kassenbeleg
+ * issuer for mirrored web orders (LUCA-36795).
+ */
+export type OrderEventIssuer = {
+    legalName?: string | null;
+    street?: string | null;
+    postalCode?: string | null;
+    city?: string | null;
+    country?: string | null;
+    taxNumber?: string | null;
+    vatId?: string | null;
+};
 /**
  * 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.
@@ -45,4 +58,6 @@ export type OrderEvent = {
     note: string | null;
     createdAt: Date;
     items: OrderEventItem[];
+    /** Optional so older producers and consumers keep working. */
+    issuer?: OrderEventIssuer | null;
 };

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

@@ -3,8 +3,8 @@ 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 type { OrderEvent, OrderEventIssuer, OrderEventItem, OrderEventType, OrderEventStatus, OrderEventTranslatableName, } from './events/order';
 export { ORDER_EVENT_VERSION } from './events/order';
-export type { FiscalizedPayment } from './events/fiscalizedPayment';
+export type { FiscalizedPayment, FiscalizedPaymentStatus, } from './events/fiscalizedPayment';
 export { FISCALIZED_PAYMENT_EVENT_VERSION } from './events/fiscalizedPayment';
 export type { KafkaEvent, GenericKafkaEvent, EventPayloadHandler, GenericEventPayloadHandler, KafkaConfiguration, CustomTopicConfig, CustomTopicPoisonContext, CustomTopicPoisonHandler, } from './types';

package/errorReporting/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/lib/errorReporting/index.js",
+  "types": "../dist/lib/errorReporting/index.d.ts"
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.38.0",
+  "version": "5.40.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist/**/*"
+    "dist/**/*",
+    "errorReporting/package.json"
   ],
   "license": "Apache-2.0",
   "author": "Culture4Life <hello@luca-app.de> (https://www.luca-app.de/)",
@@ -59,7 +60,7 @@
     "pg-boss": "12.14.0"
   },
   "devDependencies": {
-    "@sentry/node": "^9.10.1",
+    "@sentry/node": "10.76.2",
     "@types/busboy": "^1.5.4",
     "@types/lodash": "^4.14.187",
     "@types/negotiator": "^0.6.4",
@@ -85,7 +86,7 @@
     "yarn-osv-audit": "1.0.0"
   },
   "peerDependencies": {
-    "@sentry/node": "^9.10.1",
+    "@sentry/node": "^9.10.1 || ^10.0.0",
     "pino-sentry-transport": "^1.5.1"
   },
   "peerDependenciesMeta": {