@lucaapp/service-utils 5.25.0 → 5.27.0

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

@@ -28,6 +28,7 @@ export declare class Api {
     apiTitle: string;
     apiDescription: string;
     private prefixPath;
+    private rootPrefixPath;
     debug: boolean;
     tags: string[];
     constructor(options?: ApiConstructorOptions);

package/dist/lib/api/api.js

@@ -10,6 +10,7 @@ const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
 const zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
 const endpoint_1 = require("./endpoint");
 const openapi_1 = require("./openapi");
+const security_1 = require("./security");
 const body_parser_1 = __importDefault(require("body-parser"));
 const rawBodySaver = function (req, res, buf, encoding) {
     if (buf && buf.length) {
@@ -22,6 +23,7 @@ class Api {
         this.router = options.router || (0, express_1.Router)();
         this.registry = options.registry || new zod_to_openapi_1.OpenAPIRegistry();
         this.prefixPath = options.prefixPath || '';
+        this.rootPrefixPath = this.prefixPath;
         this.openApiVersion = options.openApiVersion || '3.0.0';
         this.apiVersion = options.apiVersion || '1.0.0';
         this.apiTitle = options.apiTitle || 'API';
@@ -31,33 +33,35 @@ class Api {
         this.router.use(body_parser_1.default.json({ verify: rawBodySaver, limit: '2mb' }));
     }
     child(options) {
-        return new Api({
+        const child = new Api({
             prefixPath: this.prefixPath + (options.prefixPath || ''),
             debug: this.debug,
             tags: [...this.tags, ...(options.tags || [])],
             registry: this.registry,
             router: this.router,
         });
+        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, path, summary, options, this.tags, this.debug);
+        (0, openapi_1.registerEndpoint)(this.registry, 'get', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug);
     }
     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, path, summary, options, this.tags, this.debug);
+        (0, openapi_1.registerEndpoint)(this.registry, 'post', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug);
     }
     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, path, summary, options, this.tags, this.debug);
+        (0, openapi_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug);
     }
     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, path, summary, options, this.tags, this.debug);
+        (0, openapi_1.registerEndpoint)(this.registry, 'put', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug);
     }
     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, path, summary, options, this.tags, this.debug);
+        (0, openapi_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug);
     }
     generateOpenAPISpec() {
         let generator;
@@ -74,8 +78,11 @@ class Api {
                 title: this.apiTitle,
                 description: this.apiDescription,
             },
+            servers: [{ url: '/' }],
         });
         (0, openapi_1.forcePathParamsRequired)(spec);
+        (0, openapi_1.hoistCombinatorRequiredFields)(spec);
+        spec.components = { ...spec.components, securitySchemes: security_1.SECURITY_SCHEMES };
         return spec;
     }
     mountSwaggerMiddlewares() {

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

@@ -3,4 +3,6 @@ export * from './api';
 export * from './endpoint';
 export * from './middleware';
 export * from './response';
+export type { SecurityScheme } from './security';
 export * from './send';
+export { hoistCombinatorRequiredFields } from './openapi';

package/dist/lib/api/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extendZodWithOpenApi = void 0;
+exports.hoistCombinatorRequiredFields = exports.extendZodWithOpenApi = void 0;
 var zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
 Object.defineProperty(exports, "extendZodWithOpenApi", { enumerable: true, get: function () { return zod_to_openapi_1.extendZodWithOpenApi; } });
 __exportStar(require("./api"), exports);
@@ -22,3 +22,9 @@ __exportStar(require("./endpoint"), exports);
 __exportStar(require("./middleware"), exports);
 __exportStar(require("./response"), exports);
 __exportStar(require("./send"), exports);
+// Normalizes an OpenAPI spec's anyOf/allOf combinators the same way
+// generateOpenAPISpec() does, so a frozen/historical spec (a POS compat
+// baseline that predates this generator's fix) can be diffed against a
+// current spec on equal terms. See openapi.ts for what "normalize" means.
+var openapi_1 = require("./openapi");
+Object.defineProperty(exports, "hoistCombinatorRequiredFields", { enumerable: true, get: function () { return openapi_1.hoistCombinatorRequiredFields; } });

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

@@ -7,5 +7,23 @@ export declare const forcePathParamsRequired: (spec: {
         parameters?: Record<string, unknown>;
     };
 }) => void;
-export declare const registerEndpoint: (registry: OpenAPIRegistry, method: HttpMethod, prefixPath: string, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, tags: string[], debug: boolean) => void;
+/**
+ * zod-to-openapi represents a same-status multi-error response as `anyOf`, and
+ * `.extend()` on a registered/ref'd schema as `allOf: [$ref, inline]`. Either
+ * shape hides required/property information that used to be flat at the parent
+ * level inside the combinator, which oasdiff's breaking-change diff cannot see
+ * through — it reports every such change as fields being removed, even when the
+ * change was purely additive. This walks the finished spec and restores the
+ * safely-hoistable subset of that information to the parent schema (see
+ * hoistAnyOf / hoistAllOf for what "safe" means for each combinator — they are
+ * NOT the same rule). Ref topology is untouched: refs are only read to compute
+ * what's safe to hoist, never rewritten.
+ */
+export declare const hoistCombinatorRequiredFields: (spec: {
+    paths?: Record<string, unknown>;
+    components?: {
+        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) => void;
 export {};

package/dist/lib/api/openapi.js

@@ -1,15 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerEndpoint = exports.forcePathParamsRequired = void 0;
+exports.registerEndpoint = exports.hoistCombinatorRequiredFields = exports.forcePathParamsRequired = void 0;
 const zod_1 = require("zod");
 const http_1 = require("./types/http");
 const mapExpressParamsToOpenAPIParams = (path) => path.replaceAll(/\:([^\:\/]+)/g, '{$1}');
+const deriveOperationId = (registry, method, path) => {
+    const operationId = method +
+        path
+            .replaceAll(':', 'by-')
+            .split(/[^A-Za-z0-9]+/)
+            .filter(Boolean)
+            .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+    const isTaken = registry.definitions.some(definition => definition.type === 'route' &&
+        definition.route.operationId === operationId);
+    if (isTaken) {
+        throw new Error(`Duplicate operationId ${operationId} for ${method.toUpperCase()} ${path}, set options.operationId`);
+    }
+    return operationId;
+};
 const buildResponseConfig = (responseOptions) => {
     const responses = {};
     responseOptions.forEach(response => {
-        // raw responses end the request outside the schema layer and carry the
-        // placeholder status 0, which is not a valid OpenAPI response key
-        if (response.isRawResponseEnd) {
+        // Raw responses that declare no real schema (rawResponseEnd()'s default,
+        // schema: z.void()) end the request outside the schema layer and carry
+        // the placeholder status 0, which is not a valid OpenAPI response key —
+        // skip them; the fallback below documents a generic 200 instead. A route
+        // that sets isRawResponseEnd but ALSO declares a real schema (bypassing
+        // the response() helper for streaming/binary output while still telling
+        // callers what the body looks like) must still be documented normally —
+        // skipping unconditionally silently drops real, intentional schema
+        // information (LUCA-35888).
+        if (response.isRawResponseEnd && response.schema instanceof zod_1.z.ZodVoid) {
             return;
         }
         const isAlreadyPresent = !!responses[String(response.status)];
@@ -81,7 +103,129 @@ const forcePathParamsRequired = (spec) => {
     });
 };
 exports.forcePathParamsRequired = forcePathParamsRequired;
-const registerEndpoint = (registry, method, prefixPath, path, summary, 
+const resolveSchemaRef = (node, schemas) => {
+    if (node && typeof node === 'object' && typeof node.$ref === 'string') {
+        return schemas[node.$ref.split('/').pop()];
+    }
+    return node;
+};
+// Two same-named properties across anyOf branches are only safe to assert at the
+// parent level if they agree on primitive type — an enum/const literal that differs
+// per branch (e.g. a discriminating `error` code) must NOT leak into the hoisted
+// type, or the parent schema would wrongly forbid the other branches' literals.
+const widenAnyOfProperty = (fragments) => {
+    if (fragments.some(f => f === undefined || typeof f !== 'object')) {
+        return undefined;
+    }
+    const types = new Set(fragments.map(f => f.type));
+    if (types.size !== 1 || fragments[0].type === undefined) {
+        return undefined;
+    }
+    const widened = { type: fragments[0].type };
+    if (fragments.some(f => f.nullable)) {
+        widened.nullable = true;
+    }
+    return widened;
+};
+// anyOf is OR — an object only ever matches ONE branch, so a field is safe to
+// assert at the parent only if every branch requires it, and its type is widened
+// to what every branch agrees on (see widenAnyOfProperty). A field required in
+// some but not all branches must stay inside the combinator: hoisting it would
+// assert something false for the branches that lack it, and would wrongly
+// suppress a real breaking-change finding on that branch in the future.
+const hoistAnyOf = (node, schemas) => {
+    const branches = node.anyOf.map(b => resolveSchemaRef(b, schemas));
+    if (branches.length === 0 ||
+        branches.some(b => !b || typeof b !== 'object')) {
+        return;
+    }
+    const requiredSets = branches.map(b => new Set(b.required || []));
+    const commonRequiredNames = [...requiredSets[0]].filter(name => requiredSets.every(set => set.has(name)));
+    const hoistedProperties = {};
+    const hoistedRequired = [];
+    for (const name of commonRequiredNames) {
+        const fragments = branches.map(b => b.properties?.[name]);
+        const widened = widenAnyOfProperty(fragments);
+        if (widened) {
+            hoistedProperties[name] = widened;
+            hoistedRequired.push(name);
+        }
+    }
+    if (hoistedRequired.length === 0) {
+        return; // nothing intersects safely — leave the combinator untouched, no-op
+    }
+    node.type = 'object';
+    node.properties = { ...(node.properties || {}), ...hoistedProperties };
+    node.required = [...new Set([...(node.required || []), ...hoistedRequired])];
+};
+// allOf is AND — an object must match every branch simultaneously, so unioning
+// every branch's properties/required to the parent is always safe: nothing is
+// asserted that isn't already true of any value satisfying the allOf. No type
+// widening needed (unlike anyOf) since branches aren't alternatives.
+const hoistAllOf = (node, schemas) => {
+    const branches = node.allOf.map(b => resolveSchemaRef(b, schemas));
+    if (branches.some(b => !b || typeof b !== 'object')) {
+        return;
+    }
+    const unionProperties = {};
+    const unionRequired = new Set();
+    for (const branch of branches) {
+        for (const [key, value] of Object.entries(branch.properties || {})) {
+            if (!(key in unionProperties)) {
+                unionProperties[key] = value;
+            }
+        }
+        for (const name of branch.required || []) {
+            unionRequired.add(name);
+        }
+    }
+    if (Object.keys(unionProperties).length === 0) {
+        return; // nothing to hoist — leave the combinator untouched, no-op
+    }
+    node.type = 'object';
+    node.properties = { ...(node.properties || {}), ...unionProperties };
+    node.required = [...new Set([...(node.required || []), ...unionRequired])];
+};
+/**
+ * zod-to-openapi represents a same-status multi-error response as `anyOf`, and
+ * `.extend()` on a registered/ref'd schema as `allOf: [$ref, inline]`. Either
+ * shape hides required/property information that used to be flat at the parent
+ * level inside the combinator, which oasdiff's breaking-change diff cannot see
+ * through — it reports every such change as fields being removed, even when the
+ * change was purely additive. This walks the finished spec and restores the
+ * safely-hoistable subset of that information to the parent schema (see
+ * hoistAnyOf / hoistAllOf for what "safe" means for each combinator — they are
+ * NOT the same rule). Ref topology is untouched: refs are only read to compute
+ * what's safe to hoist, never rewritten.
+ */
+const hoistCombinatorRequiredFields = (spec) => {
+    const schemas = (spec.components?.schemas || {});
+    const visit = (node) => {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach(visit);
+            return;
+        }
+        const obj = node;
+        if (Array.isArray(obj.anyOf)) {
+            obj.anyOf.forEach(visit);
+            hoistAnyOf(obj, schemas);
+        }
+        else if (Array.isArray(obj.allOf)) {
+            obj.allOf.forEach(visit);
+            hoistAllOf(obj, schemas);
+        }
+        else {
+            Object.values(obj).forEach(visit);
+        }
+    };
+    visit(spec.paths || {});
+    visit(schemas);
+};
+exports.hoistCombinatorRequiredFields = hoistCombinatorRequiredFields;
+const registerEndpoint = (registry, method, prefixPath, rootPrefixPath, path, summary, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 options, tags, debug) => {
     let bodySchema = options.schemas?.body || undefined;
@@ -89,6 +233,7 @@ options, tags, debug) => {
     let querySchema = options.schemas?.query || undefined;
     let headersSchema = options.schemas?.headers || undefined;
     let responseSchemas = options.responses;
+    const securitySchemes = new Set();
     if (options.errors) {
         for (const errorType of Object.keys(options.errors)) {
             const statusCode = options.errors[errorType];
@@ -149,6 +294,9 @@ options, tags, debug) => {
                 });
             }
         }
+        for (const scheme of middleware.options.security || []) {
+            securitySchemes.add(scheme);
+        }
     }
     // Add ZodError response
     responseSchemas.push({
@@ -205,7 +353,11 @@ options, tags, debug) => {
             headers: headersSchema ? [headersSchema] : [],
         },
         responses: responseMap,
-        ...(options.operationId && { operationId: options.operationId }),
+        operationId: options.operationId ||
+            deriveOperationId(registry, method, prefixPath.slice(rootPrefixPath.length) + path),
+        ...(securitySchemes.size > 0 && {
+            security: [...securitySchemes].map(scheme => ({ [scheme]: [] })),
+        }),
     });
 };
 exports.registerEndpoint = registerEndpoint;

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

@@ -0,0 +1,3 @@
+import type { SecuritySchemeObject } from 'openapi3-ts/oas30';
+export type SecurityScheme = 'jwt_operator' | 'jwt_support' | 'jwt_operator_device' | 'jwt_consumer' | 'api_key';
+export declare const SECURITY_SCHEMES: Record<SecurityScheme, SecuritySchemeObject>;

package/dist/lib/api/security.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_SCHEMES = void 0;
+const X_AUTH_HEADER = {
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-Auth',
+};
+exports.SECURITY_SCHEMES = {
+    jwt_operator: X_AUTH_HEADER,
+    jwt_support: X_AUTH_HEADER,
+    jwt_operator_device: X_AUTH_HEADER,
+    jwt_consumer: X_AUTH_HEADER,
+    api_key: { type: 'apiKey', in: 'header', name: 'X-Api-Key' },
+};

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SecurityScheme } from '../security';
 import { ArrayToUnion, ExtractZodOutput, ZodSchemaOuput } from './utils';
 export type EndpointResponseSchema = {
     status: number;
@@ -45,6 +46,7 @@ export type MiddlewareOptions<TResponseSchemas extends ReadonlyArray<EndpointRes
         returnRawBody?: boolean;
     };
     errors?: Record<string, number>;
+    security?: ReadonlyArray<SecurityScheme>;
 };
 export type Middleware<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema> = {
     options: MiddlewareOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema>;

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

@@ -43,6 +43,18 @@ export type Payment = PaymentBase & {
 };
 export declare const PAYMENT_EVENT_VERSION = 2;
 export type PaymentEventVersion = typeof PAYMENT_EVENT_VERSION;
+/**
+ * Stable acquirer snapshot fields for CARD fiscalization (LUCA-35099).
+ * Populated by backend-pay when available on V3Payment at produce time.
+ * Fees are intentionally omitted — pay remains source of truth at report/close.
+ */
+export type PaymentEventCardAcquirerFields = {
+    cardLast4?: string | null;
+    authCode?: string | null;
+    cardScheme?: string | null;
+    cardBrandLabel?: string | null;
+    terminalId?: string | null;
+};
 export type PaymentEvent = {
     version: PaymentEventVersion;
     uuid: string;
@@ -60,7 +72,7 @@ export type PaymentEvent = {
     orderId?: string;
     statusCompleteAt?: Date | null;
     merchantDetails?: PaymentMerchantDetails;
-};
+} & PaymentEventCardAcquirerFields;
 export declare const consumerPayAmount: (event: PaymentEvent) => number;
 export declare const operatorReceivableAmount: (event: PaymentEvent) => number;
 export type PaymentMerchantDetails = {

package/dist/lib/negotiator/language.d.ts

@@ -18,9 +18,44 @@ type LanguageOptions = typeof AVAILABLE_LANGUAGES[number];
  * ```
  */
 export declare const isInternalLanguage: (lang: string) => lang is InternalLanguages;
+/**
+ * Canonicalises a language code for storage: `DE-de` -> `de-DE`.
+ * Returns null when the value is absent or not a plausible language code.
+ *
+ * The region is dropped when keeping it would not fit the `STRING(5)` language
+ * columns, so `fil-PH` stores as `fil` rather than overflowing or being thrown
+ * away — the language is the part we care about.
+ *
+ * Unlike {@link toInternalLanguage} this does NOT narrow to the languages our
+ * templates support — storage keeps what the user actually asked for, and
+ * narrowing happens on retrieval.
+ */
+export declare const normalizeStoredLanguage: (lang?: string | null) => string | null;
+/**
+ * Reads the caller's preferred language without narrowing it to the languages
+ * our templates support. Use for values that get persisted; use
+ * {@link getPreferredLanguageFromRequestHeaders} when the result immediately
+ * selects a template.
+ *
+ * Returns null when no usable `Accept-Language` was sent, so callers can leave
+ * the column untouched rather than writing a guessed default.
+ *
+ * @example
+ * ```typescript
+ * getStoredLanguageFromRequestHeaders({ 'accept-language': 'fr-FR,fr;q=0.9' }) // 'fr-FR'
+ * getStoredLanguageFromRequestHeaders({}) // null
+ * ```
+ */
+export declare const getStoredLanguageFromRequestHeaders: (headers?: Record<string, string>) => string | null;
+export declare const getStoredLanguageFromRequest: (request: Request) => string | null;
 /**
  * Safely converts a language code to an InternalLanguage.
- * If the language is not supported, falls back to 'en'.
+ * The region subtag is dropped before matching, so `de-DE` resolves to `de`
+ * rather than falling back. If the language is not supported, falls back to 'en'.
+ *
+ * This is the retrieval-side counterpart to {@link normalizeStoredLanguage}:
+ * columns may hold any language the user asked for, and every read that feeds
+ * a template goes through here.
  *
  * @param lang - Language code to convert
  * @returns The language if supported, otherwise 'en'
@@ -28,11 +63,12 @@ export declare const isInternalLanguage: (lang: string) => lang is InternalLangu
  * @example
  * ```typescript
  * toInternalLanguage('de') // returns 'de'
+ * toInternalLanguage('de-DE') // returns 'de'
  * toInternalLanguage('en') // returns 'en'
  * toInternalLanguage('fr') // returns 'en' (fallback)
  * ```
  */
-export declare const toInternalLanguage: (lang: string) => InternalLanguages;
+export declare const toInternalLanguage: (lang?: string | null) => InternalLanguages;
 export declare const parseAcceptLanguageHeader: (header?: string) => LanguageOptions;
 /**
  * @deprecated Use getPreferredLanguageFromRequestHeaders instead.

package/dist/lib/negotiator/language.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPreferredLanguageFromRequestHeaders = exports.getPreferredLanguageFromRequest = exports.parseAcceptLanguageHeader = exports.toInternalLanguage = exports.isInternalLanguage = exports.AVAILABLE_LANGUAGES = exports.DEFAULT_LANGUAGE_WHEN_HEADER = exports.DEFAULT_LANGUAGE_WHEN_NO_HEADER = void 0;
+exports.getPreferredLanguageFromRequestHeaders = exports.getPreferredLanguageFromRequest = exports.parseAcceptLanguageHeader = exports.toInternalLanguage = exports.getStoredLanguageFromRequest = exports.getStoredLanguageFromRequestHeaders = exports.normalizeStoredLanguage = exports.isInternalLanguage = exports.AVAILABLE_LANGUAGES = exports.DEFAULT_LANGUAGE_WHEN_HEADER = exports.DEFAULT_LANGUAGE_WHEN_NO_HEADER = void 0;
 const negotiator_1 = __importDefault(require("negotiator"));
 exports.DEFAULT_LANGUAGE_WHEN_NO_HEADER = 'de';
 exports.DEFAULT_LANGUAGE_WHEN_HEADER = 'en';
@@ -25,9 +25,80 @@ const isInternalLanguage = (lang) => {
     return exports.AVAILABLE_LANGUAGES.includes(lang);
 };
 exports.isInternalLanguage = isInternalLanguage;
+/**
+ * Shape of a language code we are willing to persist: a 2-3 letter primary
+ * subtag, optionally followed by a 2-letter region. Deliberately narrower than
+ * full BCP 47 so an attacker-controlled `Accept-Language` cannot write junk;
+ * script subtags (`zh-Hant`) are rejected rather than truncated.
+ */
+const STORED_LANGUAGE_PATTERN = /^[a-z]{2,3}(-[a-z]{2})?$/i;
+/**
+ * Longest value the `language` columns accept — they are `STRING(5)`, which
+ * fits `pt-BR` but not a 3-letter primary subtag with a region (`fil-PH`).
+ */
+const STORED_LANGUAGE_MAX_LENGTH = 5;
+/**
+ * Canonicalises a language code for storage: `DE-de` -> `de-DE`.
+ * Returns null when the value is absent or not a plausible language code.
+ *
+ * The region is dropped when keeping it would not fit the `STRING(5)` language
+ * columns, so `fil-PH` stores as `fil` rather than overflowing or being thrown
+ * away — the language is the part we care about.
+ *
+ * Unlike {@link toInternalLanguage} this does NOT narrow to the languages our
+ * templates support — storage keeps what the user actually asked for, and
+ * narrowing happens on retrieval.
+ */
+const normalizeStoredLanguage = (lang) => {
+    const trimmed = lang?.trim();
+    if (!trimmed || !STORED_LANGUAGE_PATTERN.test(trimmed)) {
+        return null;
+    }
+    const [primary, region] = trimmed.split('-');
+    const canonical = region
+        ? `${primary.toLowerCase()}-${region.toUpperCase()}`
+        : primary.toLowerCase();
+    return canonical.length > STORED_LANGUAGE_MAX_LENGTH
+        ? primary.toLowerCase()
+        : canonical;
+};
+exports.normalizeStoredLanguage = normalizeStoredLanguage;
+/**
+ * Reads the caller's preferred language without narrowing it to the languages
+ * our templates support. Use for values that get persisted; use
+ * {@link getPreferredLanguageFromRequestHeaders} when the result immediately
+ * selects a template.
+ *
+ * Returns null when no usable `Accept-Language` was sent, so callers can leave
+ * the column untouched rather than writing a guessed default.
+ *
+ * @example
+ * ```typescript
+ * getStoredLanguageFromRequestHeaders({ 'accept-language': 'fr-FR,fr;q=0.9' }) // 'fr-FR'
+ * getStoredLanguageFromRequestHeaders({}) // null
+ * ```
+ */
+const getStoredLanguageFromRequestHeaders = (headers) => {
+    const acceptLanguageHeader = headers?.['accept-language'];
+    if (!acceptLanguageHeader) {
+        return null;
+    }
+    // Take the highest-priority entry we can actually store, rather than giving
+    // up when the first one happens to be unstorable (e.g. `zh-Hant-TW, zh-TW`).
+    const negotiator = new negotiator_1.default({ headers });
+    return (negotiator.languages().map(exports.normalizeStoredLanguage).find(Boolean) ?? null);
+};
+exports.getStoredLanguageFromRequestHeaders = getStoredLanguageFromRequestHeaders;
+const getStoredLanguageFromRequest = (request) => (0, exports.getStoredLanguageFromRequestHeaders)(request.headers);
+exports.getStoredLanguageFromRequest = getStoredLanguageFromRequest;
 /**
  * Safely converts a language code to an InternalLanguage.
- * If the language is not supported, falls back to 'en'.
+ * The region subtag is dropped before matching, so `de-DE` resolves to `de`
+ * rather than falling back. If the language is not supported, falls back to 'en'.
+ *
+ * This is the retrieval-side counterpart to {@link normalizeStoredLanguage}:
+ * columns may hold any language the user asked for, and every read that feeds
+ * a template goes through here.
  *
  * @param lang - Language code to convert
  * @returns The language if supported, otherwise 'en'
@@ -35,12 +106,14 @@ exports.isInternalLanguage = isInternalLanguage;
  * @example
  * ```typescript
  * toInternalLanguage('de') // returns 'de'
+ * toInternalLanguage('de-DE') // returns 'de'
  * toInternalLanguage('en') // returns 'en'
  * toInternalLanguage('fr') // returns 'en' (fallback)
  * ```
  */
 const toInternalLanguage = (lang) => {
-    return (0, exports.isInternalLanguage)(lang) ? lang : 'en';
+    const primary = lang?.trim().split('-')[0]?.toLowerCase();
+    return primary && (0, exports.isInternalLanguage)(primary) ? primary : 'en';
 };
 exports.toInternalLanguage = toInternalLanguage;
 const parseAcceptLanguageHeader = (header) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.25.0",
+  "version": "5.27.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -88,7 +88,7 @@
     "tar": "7.5.21",
     "body-parser": "1.20.6",
     "lodash": "^4.18.1",
-    "qs": "6.15.2",
+    "qs": "6.16.0",
     "dottie": "2.0.7",
     "fast-xml-parser": "^5.7.1",
     "yaml": "^2.8.3",