@uns-kit/api 2.0.25 → 2.0.27

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Aljoša Vister
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Aljoša Vister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,77 +1,77 @@
-# @uns-kit/api
-
-`@uns-kit/api` exposes Express-based HTTP endpoints for UNS deployments. The plugin attaches a `createApiProxy` method to `UnsProxyProcess`, handles JWT/JWKS access control, and automatically publishes API metadata back into the Unified Namespace.
-
-Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
-For the MQTT topic registry published by the API plugin, see `../../docs/uns-topics.md`.
-
-## uns-kit in context
-
-uns-kit is a batteries-included toolkit for Unified Namespace applications. It standardizes MQTT wiring, auth, config schemas, and scaffolding so you can focus on your API surface instead of boilerplate. The toolkit packages are:
-
-| Package | Description |
-| --- | --- |
-| [`@uns-kit/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime utilities (UnsProxyProcess, MQTT helpers, configuration tooling, gRPC gateway support). |
-| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin that exposes HTTP endpoints, handles JWT/JWKS auth, and republishes API metadata to UNS. |
-| [`@uns-kit/cron`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
-| [`@uns-kit/temporal`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-temporal) | Temporal.io integration that wires workflows into UnsProxyProcess. |
-| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | Command line tool for scaffolding new UNS applications. |
-
-## Installation
-
-```bash
-pnpm add @uns-kit/api
-# or
-npm install @uns-kit/api
-```
-
-Make sure `@uns-kit/core` is also installed; the plugin augments its runtime types.
-
-## Example
-
-```ts
-import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
-import type { UnsProxyProcessWithApi } from "@uns-kit/api";
-import "@uns-kit/api"; // registers the plugin side-effect
-
-async function main() {
-  const process = new UnsProxyProcess("mqtt-broker:1883", { processName: "api-gateway" }) as UnsProxyProcessWithApi;
-
-  const api = await process.createApiProxy("gateway", { jwtSecret: "super-secret" });
-
-  api.get("factory/", "status", {
-    apiDescription: "Factory status endpoint",
-    tags: ["status"],
-    queryParams: [
-      { name: "from", type: "string", chatCanonical: "from" },
-      { name: "to", type: "string", chatCanonical: "to" },
-      { name: "limit", type: "number", chatCanonical: "limit", defaultValue: 200 },
-    ],
-    chatDefaults: {
-      limit: 200,
-    },
-  });
-
-  api.event.on("apiGetEvent", (event) => {
-    event.res.json({ status: "ok" });
-  });
-}
-
-void main();
-```
-
-`queryParams[].chatCanonical`, `queryParams[].defaultValue`, and `chatDefaults` are optional.
-When provided, they are published into OpenAPI vendor metadata (`x-uns-chat`) so assistant tooling can map canonical chat inputs (`from`, `to`, `limit`, `topic`, ...) to endpoint-specific query parameters.
-
-## Scripts
-
-```bash
-pnpm run typecheck
-pnpm run build
-```
-
-`build` emits both JavaScript and type declarations to `dist/`.
-
-## License
-
-MIT © Aljoša Vister
+# @uns-kit/api
+
+`@uns-kit/api` exposes Express-based HTTP endpoints for UNS deployments. The plugin attaches a `createApiProxy` method to `UnsProxyProcess`, handles JWT/JWKS access control, and automatically publishes API metadata back into the Unified Namespace.
+
+Note: Apps built with uns-kit are intended to be managed by the **UNS Datahub controller**.
+For the MQTT topic registry published by the API plugin, see `../../docs/uns-topics.md`.
+
+## uns-kit in context
+
+uns-kit is a batteries-included toolkit for Unified Namespace applications. It standardizes MQTT wiring, auth, config schemas, and scaffolding so you can focus on your API surface instead of boilerplate. The toolkit packages are:
+
+| Package | Description |
+| --- | --- |
+| [`@uns-kit/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime utilities (UnsProxyProcess, MQTT helpers, configuration tooling, gRPC gateway support). |
+| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin that exposes HTTP endpoints, handles JWT/JWKS auth, and republishes API metadata to UNS. |
+| [`@uns-kit/cron`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cron) | Cron-driven scheduler that emits UNS events on a fixed cadence. |
+| [`@uns-kit/temporal`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-temporal) | Temporal.io integration that wires workflows into UnsProxyProcess. |
+| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | Command line tool for scaffolding new UNS applications. |
+
+## Installation
+
+```bash
+pnpm add @uns-kit/api
+# or
+npm install @uns-kit/api
+```
+
+Make sure `@uns-kit/core` is also installed; the plugin augments its runtime types.
+
+## Example
+
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import type { UnsProxyProcessWithApi } from "@uns-kit/api";
+import "@uns-kit/api"; // registers the plugin side-effect
+
+async function main() {
+  const process = new UnsProxyProcess("mqtt-broker:1883", { processName: "api-gateway" }) as UnsProxyProcessWithApi;
+
+  const api = await process.createApiProxy("gateway", { jwtSecret: "super-secret" });
+
+  api.get("factory/", "status", {
+    apiDescription: "Factory status endpoint",
+    tags: ["status"],
+    queryParams: [
+      { name: "from", type: "string", chatCanonical: "from" },
+      { name: "to", type: "string", chatCanonical: "to" },
+      { name: "limit", type: "number", chatCanonical: "limit", defaultValue: 200 },
+    ],
+    chatDefaults: {
+      limit: 200,
+    },
+  });
+
+  api.event.on("apiGetEvent", (event) => {
+    event.res.json({ status: "ok" });
+  });
+}
+
+void main();
+```
+
+`queryParams[].chatCanonical`, `queryParams[].defaultValue`, and `chatDefaults` are optional.
+When provided, they are published into OpenAPI vendor metadata (`x-uns-chat`) so assistant tooling can map canonical chat inputs (`from`, `to`, `limit`, `topic`, ...) to endpoint-specific query parameters.
+
+## Scripts
+
+```bash
+pnpm run typecheck
+pnpm run build
+```
+
+`build` emits both JavaScript and type declarations to `dist/`.
+
+## License
+
+MIT © Aljoša Vister

package/dist/api-interfaces.d.ts

@@ -1 +1 @@
-export type { IApiProxyOptions, IGetEndpointOptions, QueryParamDef } from "@uns-kit/core/uns/uns-interfaces.js";
+export type { IApiProxyOptions, IGetEndpointOptions, QueryParamDef } from "@uns-kit/core/uns/uns-interfaces.js";

package/dist/app.d.ts

@@ -1,48 +1,48 @@
-/**
- * Module dependencies.
- */
-import { type Router } from "express";
-import * as http from "http";
-type MountConfig = {
-    apiBasePrefix?: string;
-    swaggerBasePrefix?: string;
-    disableDefaultApiMount?: boolean;
-};
-export default class App {
-    private expressApplication;
-    server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
-    private port;
-    router: Router;
-    private processName;
-    private instanceName;
-    private apiBasePrefix;
-    private swaggerBasePrefix;
-    swaggerSpec: {
-        openapi: string;
-        info: {
-            title: string;
-            version: string;
-        };
-        paths: Record<string, any>;
-        servers?: Array<{
-            url: string;
-        }>;
-    };
-    private swaggerDocs;
-    constructor(port: number, processName: string, instanceName: string, appContext?: any, mountConfig?: MountConfig);
-    static getExternalIPv4(): string | null;
-    getSwaggerSpec(): {
-        openapi: string;
-        info: {
-            title: string;
-            version: string;
-        };
-        paths: Record<string, any>;
-        servers?: Array<{
-            url: string;
-        }>;
-    };
-    registerSwaggerDoc(path: string, doc: Record<string, unknown>): void;
-    start(): Promise<void>;
-}
-export {};
+/**
+ * Module dependencies.
+ */
+import { type Router } from "express";
+import * as http from "http";
+type MountConfig = {
+    apiBasePrefix?: string;
+    swaggerBasePrefix?: string;
+    disableDefaultApiMount?: boolean;
+};
+export default class App {
+    private expressApplication;
+    server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    private port;
+    router: Router;
+    private processName;
+    private instanceName;
+    private apiBasePrefix;
+    private swaggerBasePrefix;
+    swaggerSpec: {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+        };
+        paths: Record<string, any>;
+        servers?: Array<{
+            url: string;
+        }>;
+    };
+    private swaggerDocs;
+    constructor(port: number, processName: string, instanceName: string, appContext?: any, mountConfig?: MountConfig);
+    static getExternalIPv4(): string | null;
+    getSwaggerSpec(): {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+        };
+        paths: Record<string, any>;
+        servers?: Array<{
+            url: string;
+        }>;
+    };
+    registerSwaggerDoc(path: string, doc: Record<string, unknown>): void;
+    start(): Promise<void>;
+}
+export {};

package/dist/app.js

@@ -1,150 +1,150 @@
-/**
- * Module dependencies.
- */
-import express from "express";
-import * as http from "http";
-import * as path from "path";
-import cookieParser from "cookie-parser";
-import { basePath } from "@uns-kit/core/base-path.js";
-import logger from "@uns-kit/core/logger.js";
-import os from 'os';
-const normalizeBasePrefix = (value) => {
-    if (!value)
-        return "";
-    const trimmed = value.trim();
-    if (!trimmed)
-        return "";
-    const withLeading = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-    return withLeading.replace(/\/+$/, "");
-};
-const buildSwaggerPath = (base, processName, instanceName) => {
-    const processSegment = `/${processName}`;
-    let baseWithProcess = base || "/";
-    if (!baseWithProcess.endsWith(processSegment)) {
-        baseWithProcess = `${baseWithProcess}${processSegment}`;
-    }
-    return `${baseWithProcess}/${instanceName}/swagger.json`.replace(/\/{2,}/g, "/");
-};
-export default class App {
-    expressApplication;
-    server;
-    port;
-    router;
-    processName;
-    instanceName;
-    apiBasePrefix;
-    swaggerBasePrefix;
-    swaggerSpec;
-    swaggerDocs = new Map();
-    constructor(port, processName, instanceName, appContext, mountConfig) {
-        this.router = express.Router();
-        this.port = port;
-        this.expressApplication = express();
-        this.server = http.createServer(this.expressApplication);
-        this.processName = processName;
-        this.instanceName = instanceName;
-        this.apiBasePrefix =
-            normalizeBasePrefix(mountConfig?.apiBasePrefix ?? process.env.UNS_API_BASE_PATH) || "/api";
-        const rawSwaggerBase = normalizeBasePrefix(mountConfig?.swaggerBasePrefix ?? process.env.UNS_SWAGGER_BASE_PATH) ||
-            this.apiBasePrefix;
-        // If someone passed ".../api" as swagger base, strip that to avoid duplicated segments
-        this.swaggerBasePrefix = rawSwaggerBase.endsWith("/api")
-            ? rawSwaggerBase.replace(/\/api\/?$/, "") || "/"
-            : rawSwaggerBase;
-        // Add context
-        this.expressApplication.use((req, _res, next) => {
-            req.appContext = appContext;
-            next();
-        });
-        // Body parser (req.body)
-        this.expressApplication.use(express.json());
-        this.expressApplication.use(express.urlencoded({ extended: false }));
-        // Add cookie parser
-        this.expressApplication.use(cookieParser());
-        // Static / public folder
-        const publicHome = process.env.PUBLIC_HOME === null || process.env.PUBLIC_HOME === undefined
-            ? "public"
-            : process.env.PUBLIC_HOME;
-        this.expressApplication.use(express.static(path.join(basePath, publicHome)));
-        // Map routes
-        this.router.use((_req, _res, next) => {
-            logger.info("Time: ", Date.now());
-            next();
-        });
-        if (!mountConfig?.disableDefaultApiMount) {
-            this.expressApplication.use(this.apiBasePrefix, this.router);
-        }
-        // Swagger specs
-        this.swaggerSpec = {
-            openapi: "3.0.0",
-            info: {
-                title: "UNS API",
-                version: "1.0.0",
-            },
-            paths: {},
-            servers: this.swaggerBasePrefix ? [{ url: this.swaggerBasePrefix }] : undefined,
-        };
-    }
-    static getExternalIPv4() {
-        const interfaces = os.networkInterfaces();
-        for (const name of Object.keys(interfaces)) {
-            for (const iface of interfaces[name] || []) {
-                if (iface.family === 'IPv4' && !iface.internal) {
-                    return iface.address;
-                }
-            }
-        }
-        return null;
-    }
-    getSwaggerSpec() {
-        return this.swaggerSpec;
-    }
-    registerSwaggerDoc(path, doc) {
-        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-        this.swaggerDocs.set(normalizedPath, doc);
-        this.expressApplication.get(normalizedPath, (_req, res) => res.json(doc));
-    }
-    async start() {
-        // Listen on provided port, on all network interfaces.
-        this.server.listen(this.port);
-        this.server.on("error", (error) => {
-            if (error.syscall !== "listen") {
-                throw error;
-            }
-            const bind = typeof this.port === "string"
-                ? `Pipe ${this.port}`
-                : `Port ${this.port}`;
-            // handle specific listen errors with friendly messages
-            switch (error.code) {
-                case "EACCES":
-                    logger.error(`${bind} requires elevated privileges`);
-                    process.exit(1);
-                    break;
-                case "EADDRINUSE":
-                    logger.error(`${bind} is already in use`);
-                    process.exit(1);
-                    break;
-                default:
-                    throw error;
-            }
-        });
-        this.server.on("listening", () => {
-            App.bind(this);
-            const addressInfo = this.server.address();
-            let ip;
-            let port;
-            if (addressInfo && typeof addressInfo === "object") {
-                ip = App.getExternalIPv4();
-                port = addressInfo.port;
-            }
-            else if (typeof addressInfo === "string") {
-                ip = App.getExternalIPv4();
-                port = "";
-            }
-            logger.info(`API listening on http://${ip}:${port}${this.apiBasePrefix}`);
-            const swaggerPath = buildSwaggerPath(this.swaggerBasePrefix, this.processName, this.instanceName);
-            logger.info(`Swagger openAPI on http://${ip}:${port}${swaggerPath}`);
-            this.expressApplication.get(swaggerPath, (req, res) => res.json(this.getSwaggerSpec()));
-        });
-    }
-}
+/**
+ * Module dependencies.
+ */
+import express from "express";
+import * as http from "http";
+import * as path from "path";
+import cookieParser from "cookie-parser";
+import { basePath } from "@uns-kit/core/base-path.js";
+import logger from "@uns-kit/core/logger.js";
+import os from 'os';
+const normalizeBasePrefix = (value) => {
+    if (!value)
+        return "";
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    const withLeading = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return withLeading.replace(/\/+$/, "");
+};
+const buildSwaggerPath = (base, processName, instanceName) => {
+    const processSegment = `/${processName}`;
+    let baseWithProcess = base || "/";
+    if (!baseWithProcess.endsWith(processSegment)) {
+        baseWithProcess = `${baseWithProcess}${processSegment}`;
+    }
+    return `${baseWithProcess}/${instanceName}/swagger.json`.replace(/\/{2,}/g, "/");
+};
+export default class App {
+    expressApplication;
+    server;
+    port;
+    router;
+    processName;
+    instanceName;
+    apiBasePrefix;
+    swaggerBasePrefix;
+    swaggerSpec;
+    swaggerDocs = new Map();
+    constructor(port, processName, instanceName, appContext, mountConfig) {
+        this.router = express.Router();
+        this.port = port;
+        this.expressApplication = express();
+        this.server = http.createServer(this.expressApplication);
+        this.processName = processName;
+        this.instanceName = instanceName;
+        this.apiBasePrefix =
+            normalizeBasePrefix(mountConfig?.apiBasePrefix ?? process.env.UNS_API_BASE_PATH) || "/api";
+        const rawSwaggerBase = normalizeBasePrefix(mountConfig?.swaggerBasePrefix ?? process.env.UNS_SWAGGER_BASE_PATH) ||
+            this.apiBasePrefix;
+        // If someone passed ".../api" as swagger base, strip that to avoid duplicated segments
+        this.swaggerBasePrefix = rawSwaggerBase.endsWith("/api")
+            ? rawSwaggerBase.replace(/\/api\/?$/, "") || "/"
+            : rawSwaggerBase;
+        // Add context
+        this.expressApplication.use((req, _res, next) => {
+            req.appContext = appContext;
+            next();
+        });
+        // Body parser (req.body)
+        this.expressApplication.use(express.json());
+        this.expressApplication.use(express.urlencoded({ extended: false }));
+        // Add cookie parser
+        this.expressApplication.use(cookieParser());
+        // Static / public folder
+        const publicHome = process.env.PUBLIC_HOME === null || process.env.PUBLIC_HOME === undefined
+            ? "public"
+            : process.env.PUBLIC_HOME;
+        this.expressApplication.use(express.static(path.join(basePath, publicHome)));
+        // Map routes
+        this.router.use((_req, _res, next) => {
+            logger.info("Time: ", Date.now());
+            next();
+        });
+        if (!mountConfig?.disableDefaultApiMount) {
+            this.expressApplication.use(this.apiBasePrefix, this.router);
+        }
+        // Swagger specs
+        this.swaggerSpec = {
+            openapi: "3.0.0",
+            info: {
+                title: "UNS API",
+                version: "1.0.0",
+            },
+            paths: {},
+            servers: this.swaggerBasePrefix ? [{ url: this.swaggerBasePrefix }] : undefined,
+        };
+    }
+    static getExternalIPv4() {
+        const interfaces = os.networkInterfaces();
+        for (const name of Object.keys(interfaces)) {
+            for (const iface of interfaces[name] || []) {
+                if (iface.family === 'IPv4' && !iface.internal) {
+                    return iface.address;
+                }
+            }
+        }
+        return null;
+    }
+    getSwaggerSpec() {
+        return this.swaggerSpec;
+    }
+    registerSwaggerDoc(path, doc) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        this.swaggerDocs.set(normalizedPath, doc);
+        this.expressApplication.get(normalizedPath, (_req, res) => res.json(doc));
+    }
+    async start() {
+        // Listen on provided port, on all network interfaces.
+        this.server.listen(this.port);
+        this.server.on("error", (error) => {
+            if (error.syscall !== "listen") {
+                throw error;
+            }
+            const bind = typeof this.port === "string"
+                ? `Pipe ${this.port}`
+                : `Port ${this.port}`;
+            // handle specific listen errors with friendly messages
+            switch (error.code) {
+                case "EACCES":
+                    logger.error(`${bind} requires elevated privileges`);
+                    process.exit(1);
+                    break;
+                case "EADDRINUSE":
+                    logger.error(`${bind} is already in use`);
+                    process.exit(1);
+                    break;
+                default:
+                    throw error;
+            }
+        });
+        this.server.on("listening", () => {
+            App.bind(this);
+            const addressInfo = this.server.address();
+            let ip;
+            let port;
+            if (addressInfo && typeof addressInfo === "object") {
+                ip = App.getExternalIPv4();
+                port = addressInfo.port;
+            }
+            else if (typeof addressInfo === "string") {
+                ip = App.getExternalIPv4();
+                port = "";
+            }
+            logger.info(`API listening on http://${ip}:${port}${this.apiBasePrefix}`);
+            const swaggerPath = buildSwaggerPath(this.swaggerBasePrefix, this.processName, this.instanceName);
+            logger.info(`Swagger openAPI on http://${ip}:${port}${swaggerPath}`);
+            this.expressApplication.get(swaggerPath, (req, res) => res.json(this.getSwaggerSpec()));
+        });
+    }
+}