@lucaapp/service-utils 5.29.1 → 5.30.0

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

@@ -7,6 +7,12 @@ import { ZodObjectSchemaOrUndefined } from './types/utils';
 type OpenApiVersion = '3.0.0' | '3.0.1' | '3.0.2' | '3.0.3' | '3.1.0';
 type ApiConstructorOptions = {
     prefixPath?: string;
+    /**
+     * Keep every endpoint registered on this Api out of the generated OpenAPI
+     * spec. Inherited by children and never turned off again, so a hidden branch
+     * stays hidden. Routing is unaffected; this only controls documentation.
+     */
+    hidden?: boolean;
     openApiVersion?: OpenApiVersion;
     apiVersion?: string;
     apiTitle?: string;
@@ -19,6 +25,7 @@ type ApiConstructorOptions = {
 type ApiChildOptions = {
     prefixPath?: string;
     tags?: string[];
+    hidden?: boolean;
 };
 export declare class Api {
     router: Router;
@@ -31,6 +38,7 @@ export declare class Api {
     private rootPrefixPath;
     debug: boolean;
     tags: string[];
+    private hidden;
     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

@@ -30,6 +30,7 @@ class Api {
         this.apiDescription = options.apiDescription || '';
         this.debug = options.debug || false;
         this.tags = options.tags || [];
+        this.hidden = options.hidden || false;
         this.router.use(body_parser_1.default.json({ verify: rawBodySaver, limit: '2mb' }));
     }
     child(options) {
@@ -39,29 +40,31 @@ class Api {
             tags: [...this.tags, ...(options.tags || [])],
             registry: this.registry,
             router: this.router,
+            // Once hidden, always hidden: a child cannot re-expose its parent's tree.
+            hidden: this.hidden || options.hidden || false,
         });
         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);
+        (0, openapi_1.registerEndpoint)(this.registry, 'get', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
     }
     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);
+        (0, openapi_1.registerEndpoint)(this.registry, 'post', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
     }
     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);
+        (0, openapi_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
     }
     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);
+        (0, openapi_1.registerEndpoint)(this.registry, 'put', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
     }
     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);
+        (0, openapi_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, this.rootPrefixPath, path, summary, options, this.tags, this.debug, this.hidden);
     }
     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) => 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 {};

package/dist/lib/api/openapi.js

@@ -225,40 +225,29 @@ const hoistCombinatorRequiredFields = (spec) => {
     visit(schemas);
 };
 exports.hoistCombinatorRequiredFields = hoistCombinatorRequiredFields;
-/**
- * Turn each middleware's declared schemes into OpenAPI security requirements.
- *
- * OpenAPI expresses the two relations differently: separate objects in the
- * `security` array are alternatives (OR), while several schemes inside one
- * object are all required (AND). A middleware's own `security: [a, b]` means
- * "a or b" -- it accepts either credential -- but two middlewares on the same
- * route both run, so their requirements are combined with AND.
- *
- * That makes the result the cartesian product across middlewares:
- *
- *   [[a, b], [c]]  ->  [{a, c}, {b, c}]
- *
- * A single middleware therefore still renders as plain alternatives, which is
- * what it did before, and stacked middlewares no longer render as if presenting
- * any one of their credentials were enough.
- */
-const buildSecurityRequirements = (securityByMiddleware) => securityByMiddleware.reduce((requirements, alternatives) => requirements.flatMap(requirement => 
-// Duplicates collapse on their own: the same scheme required twice is
-// still one entry in the object.
-alternatives.map(scheme => ({ ...requirement, [scheme]: [] }))), [{}]);
 const registerEndpoint = (registry, method, prefixPath, rootPrefixPath, path, summary, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-options, tags, debug) => {
+options, tags, debug, hiddenApi = false) => {
+    // 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) {
+        return;
+    }
     let bodySchema = options.schemas?.body || undefined;
     let paramsSchema = options.schemas?.params || undefined;
     let querySchema = options.schemas?.query || undefined;
     let headersSchema = options.schemas?.headers || undefined;
     let responseSchemas = options.responses;
-    // One entry per security-declaring middleware, each holding that middleware's
-    // alternatives. Kept separate because the two levels mean different things:
-    // within a middleware the schemes are alternatives, across middlewares they
-    // are all enforced. See buildSecurityRequirements.
-    const securityByMiddleware = [];
+    // Union across middlewares, one scheme per requirement object, which OpenAPI
+    // reads as "any one of these". Deliberately not one object holding all of
+    // them, which would read as "all of these at once": jwt_operator,
+    // jwt_support, jwt_operator_device and jwt_consumer are all apiKey in the
+    // same X-Auth header, so requiring two of them is unsatisfiable. Nearly every
+    // location-guarded route stacks requireOperatorOROperatorDevice with
+    // authorizeLocation(Group), and 5.29.1 documented those 281 routes as needing
+    // an operator token and an operator-device token simultaneously.
+    const securitySchemes = new Set();
     if (options.errors) {
         for (const errorType of Object.keys(options.errors)) {
             const statusCode = options.errors[errorType];
@@ -319,9 +308,8 @@ options, tags, debug) => {
                 });
             }
         }
-        const middlewareSecurity = middleware.options.security || [];
-        if (middlewareSecurity.length > 0) {
-            securityByMiddleware.push([...middlewareSecurity]);
+        for (const scheme of middleware.options.security || []) {
+            securitySchemes.add(scheme);
         }
     }
     // Add ZodError response
@@ -381,8 +369,8 @@ options, tags, debug) => {
         responses: responseMap,
         operationId: options.operationId ||
             deriveOperationId(registry, method, prefixPath.slice(rootPrefixPath.length) + path),
-        ...(securityByMiddleware.length > 0 && {
-            security: buildSecurityRequirements(securityByMiddleware),
+        ...(securitySchemes.size > 0 && {
+            security: [...securitySchemes].map(scheme => ({ [scheme]: [] })),
         }),
     });
 };

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

@@ -21,4 +21,11 @@ export type EndpointOptions<TResponseSchemas extends ReadonlyArray<EndpointRespo
     responses: TResponseSchemas;
     errors?: Record<string, number>;
     operationId?: string;
+    /**
+     * Keep this endpoint out of the generated OpenAPI spec. For routes that only
+     * a known caller may use -- provider webhooks, service-to-service endpoints,
+     * job triggers -- where publishing the shape invites traffic that has no
+     * business arriving. Routing is unaffected.
+     */
+    hidden?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.29.1",
+  "version": "5.30.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [