@lucaapp/service-utils 5.26.0 → 5.29.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,9 +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,5 +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/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, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, tags: string[], debug: 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) => void;
 export {};

package/dist/lib/api/openapi.js

@@ -4,6 +4,21 @@ exports.registerEndpoint = exports.hoistCombinatorRequiredFields = exports.force
 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 => {
@@ -210,7 +225,7 @@ const hoistCombinatorRequiredFields = (spec) => {
     visit(schemas);
 };
 exports.hoistCombinatorRequiredFields = hoistCombinatorRequiredFields;
-const registerEndpoint = (registry, method, prefixPath, path, summary, 
+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;
@@ -218,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];
@@ -278,6 +294,9 @@ options, tags, debug) => {
                 });
             }
         }
+        for (const scheme of middleware.options.security || []) {
+            securitySchemes.add(scheme);
+        }
     }
     // Add ZodError response
     responseSchemas.push({
@@ -334,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_operator_device' | 'api_key_atworld' | 'api_key_at_support' | 'basic_adyen_webhook' | 'hmac_adyen_webhook';
+export declare const SECURITY_SCHEMES: Record<SecurityScheme, SecuritySchemeObject>;

package/dist/lib/api/security.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_SCHEMES = void 0;
+const xAuth = (description) => ({
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-Auth',
+    description,
+});
+const xApiKey = (description) => ({
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-Api-Key',
+    description,
+});
+const basicAuth = (description) => ({
+    type: 'http',
+    scheme: 'basic',
+    description,
+});
+const hmacHeader = (description) => ({
+    type: 'apiKey',
+    in: 'header',
+    name: 'hmacsignature',
+    description,
+});
+exports.SECURITY_SCHEMES = {
+    jwt_operator: xAuth('Operator session JWT issued by the luca backend'),
+    jwt_support: xAuth('Support session JWT issued by the luca backend'),
+    jwt_operator_device: xAuth('Operator device JWT issued by the luca backend (kiosk, terminal, link)'),
+    jwt_consumer: xAuth('Consumer JWT'),
+    api_key_operator_device: xApiKey('Operator device API key (sk_...) created by the operator for an external device'),
+    api_key_atworld: xApiKey('ATworld partner API key'),
+    api_key_at_support: xApiKey('AT support API key (partner or luca)'),
+    basic_adyen_webhook: basicAuth('Basic auth credential luca configures on the Adyen webhook endpoint'),
+    hmac_adyen_webhook: hmacHeader('Adyen HMAC-SHA256 signature over the raw request body, verified against the configured balance platform HMAC keys'),
+};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.26.0",
+  "version": "5.29.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -11,7 +11,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "ts:check": "tsc -p . --noEmit",
-    "lint": "eslint .",
+    "lint": "eslint --quiet .",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:ci": "VITEST_JUNIT_SUITE_NAME=service-utils CI=true vitest run --coverage",
@@ -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",