@uns-kit/api 2.0.29 → 2.0.31

package/README.md

@@ -1,21 +1,18 @@
 # @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.
+`@uns-kit/api` exposes Express-based HTTP endpoints for UNS deployments. The plugin attaches a `createApiProxy` method to `UnsProxyProcess`, handles JWT/JWKS access control, automatically publishes API metadata back into the Unified Namespace, and serves a Swagger UI for every registered endpoint.
 
 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/core`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-core) | Base runtime (UnsProxyProcess, MQTT helpers, config tooling, gRPC gateway). |
+| [`@uns-kit/api`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-api) | Express plugin — HTTP endpoints, JWT/JWKS auth, Swagger, UNS metadata. |
 | [`@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. |
+| [`@uns-kit/cli`](https://github.com/uns-datahub/uns-kit/tree/main/packages/uns-cli) | CLI for scaffolding new UNS applications. |
 
 ## Installation
 
@@ -25,43 +22,141 @@ pnpm add @uns-kit/api
 npm install @uns-kit/api
 ```
 
-Make sure `@uns-kit/core` is also installed; the plugin augments its runtime types.
+`@uns-kit/core` must also be present — the plugin augments its `UnsProxyProcess` type.
 
-## Example
+## How it works
 
-```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
+1. Import `@uns-kit/api` as a side-effect to register the plugin.
+2. Call `process.createApiProxy(instanceName, options)` to start an Express server.
+3. Register endpoints with `api.get(...)` or `api.post(...)`.
+4. Listen to `apiGetEvent` / `apiPostEvent` to handle incoming requests.
 
-async function main() {
-  const process = new UnsProxyProcess("mqtt-broker:1883", { processName: "api-gateway" }) as UnsProxyProcessWithApi;
+Every registered endpoint is:
+- Automatically secured with JWT/JWKS or a shared secret.
+- Published to the UNS controller as an API metadata record (topic, host, path, method).
+- Added to the Swagger spec served at `/<processName>/<instanceName>/swagger.json`.
 
-  const api = await process.createApiProxy("gateway", { jwtSecret: "super-secret" });
+## GET endpoint example
 
-  api.get("factory/", "status", {
-    apiDescription: "Factory status endpoint",
-    tags: ["status"],
+```ts
+import UnsProxyProcess from "@uns-kit/core/uns/uns-proxy-process";
+import type { UnsEvents } from "@uns-kit/core";
+import "@uns-kit/api";
+import { type UnsProxyProcessWithApi } from "@uns-kit/api";
+
+const config = await ConfigFile.loadConfig();
+const proc = new UnsProxyProcess(config.infra.host!, { processName: config.uns.processName }) as UnsProxyProcessWithApi;
+
+const api = await proc.createApiProxy("my-service", {
+  jwks: { wellKnownJwksUrl: config.uns.jwksWellKnownUrl },
+  // or for simple/dev deployments: jwtSecret: "CHANGEME"
+});
+
+// Register a GET endpoint
+// Signature: api.get(topic, asset, objectType, objectId, attribute, options?)
+await api.get(
+  "enterprise/site/area/line/",
+  "line-3-furnace",
+  "energy-resource",
+  "main-bus",
+  "current",
+  {
+    tags: ["Energy"],
+    apiDescription: "Current reading for line-3-furnace main-bus",
     queryParams: [
-      { name: "from", type: "string", chatCanonical: "from" },
-      { name: "to", type: "string", chatCanonical: "to" },
-      { name: "limit", type: "number", chatCanonical: "limit", defaultValue: 200 },
+      { name: "from",  type: "string", required: false, description: "Start of time range (ISO 8601)", chatCanonical: "from" },
+      { name: "to",    type: "string", required: false, description: "End of time range (ISO 8601)",   chatCanonical: "to"   },
+      { name: "limit", type: "number", required: false, description: "Maximum records",                chatCanonical: "limit", defaultValue: 100 },
     ],
-    chatDefaults: {
-      limit: 200,
+    chatDefaults: { limit: 100 },
+  }
+);
+
+// Handle incoming GET requests
+api.event.on("apiGetEvent", (event: UnsEvents["apiGetEvent"]) => {
+  const { from, to, limit } = event.req.query;
+  // fetch your data here
+  event.res.json({ status: "ok", data: [] });
+});
+```
+
+## POST endpoint example
+
+```ts
+// Register a POST endpoint
+// Signature: api.post(topic, asset, objectType, objectId, attribute, options?)
+await api.post(
+  "enterprise/site/area/line/",
+  "line-3-furnace",
+  "energy-resource",
+  "main-bus",
+  "setpoint",
+  {
+    tags: ["Energy"],
+    apiDescription: "Write a new setpoint for line-3-furnace main-bus",
+    requestBody: {
+      description: "Setpoint payload",
+      required: true,
+      schema: {
+        type: "object",
+        required: ["value"],
+        properties: {
+          value: { type: "number", description: "Target setpoint value" },
+          unit:  { type: "string", description: "Unit of measurement, e.g. A" },
+        },
+      },
     },
-  });
+  }
+);
+
+// Handle incoming POST requests — body is pre-parsed JSON
+api.event.on("apiPostEvent", (event: UnsEvents["apiPostEvent"]) => {
+  const { value, unit } = event.req.body;
+  // write/command logic here
+  event.res.json({ status: "ok", received: { value, unit } });
+});
+```
 
-  api.event.on("apiGetEvent", (event) => {
-    event.res.json({ status: "ok" });
-  });
-}
+## Endpoint signature
 
-void main();
 ```
+api.get(topic, asset, objectType, objectId, attribute, options?)
+api.post(topic, asset, objectType, objectId, attribute, options?)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `topic` | `UnsTopics` | UNS topic path prefix (e.g. `"enterprise/site/area/line/"`) |
+| `asset` | `UnsAsset` | Asset identifier (e.g. `"line-3-furnace"`) |
+| `objectType` | `UnsObjectType` | UNS object type (e.g. `"energy-resource"`) |
+| `objectId` | `UnsObjectId` | Object instance id (e.g. `"main-bus"`) |
+| `attribute` | `UnsAttribute` | Attribute name (e.g. `"current"`) |
+| `options` | `IGetEndpointOptions` / `IPostEndpointOptions` | Tags, description, query params / request body |
+
+## Auth options
+
+| Option | When to use |
+|---|---|
+| `jwks.wellKnownJwksUrl` | Production — verifies RS256 tokens from the UNS controller JWKS endpoint |
+| `jwks.activeKidUrl` | Optional companion to JWKS — narrows which key ID is active |
+| `jwtSecret` | Development / simple deployments — symmetric secret |
+
+Requests that fail auth return `401 Unauthorized`. Requests whose token `accessRules` do not match the endpoint path return `403 Forbidden`.
+
+## Unregistering an endpoint
+
+```ts
+await api.unregister(topic, asset, objectType, objectId, attribute, "GET");
+await api.unregister(topic, asset, objectType, objectId, attribute, "POST");
+```
+
+This removes the route from Express, the Swagger spec, and the internal UNS endpoint registry.
+
+## registerCatchAll (uns-api-global only)
 
-`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.
+`api.registerCatchAll()` is reserved for the **uns-api-global** microservice, which acts as a
+catch-all gateway for an entire topic namespace. **Regular microservices must not call this** —
+use `api.get()` / `api.post()` for per-attribute endpoints instead.
 
 ## Scripts
 

package/dist/uns-api-proxy.d.ts

@@ -1,7 +1,7 @@
 import { UnsAttribute } from "@uns-kit/core/uns/uns-interfaces.js";
 import UnsProxy from "@uns-kit/core/uns/uns-proxy.js";
 import { UnsTopics } from "@uns-kit/core/uns/uns-topics.js";
-import { IApiProxyOptions, IGetEndpointOptions } from "@uns-kit/core/uns/uns-interfaces.js";
+import { IApiProxyOptions, IGetEndpointOptions, IPostEndpointOptions } from "@uns-kit/core/uns/uns-interfaces.js";
 import { UnsAsset } from "@uns-kit/core/uns/uns-asset.js";
 import { UnsObjectType, UnsObjectId } from "@uns-kit/core/uns/uns-object.js";
 export default class UnsApiProxy extends UnsProxy {
@@ -37,6 +37,10 @@ export default class UnsApiProxy extends UnsProxy {
     /**
      * Register a catch-all API mapping for a topic prefix (e.g., "sij/acroni/#").
      * Does not create individual API attribute nodes; the controller treats this as a fallback.
+     *
+     * This is intended for use by the uns-api-global microservice, which acts as a
+     * catch-all gateway for an entire topic namespace. Regular microservices should
+     * NOT call this — use registerGetEndpoint() for individual attribute endpoints instead.
      */
     registerCatchAll(topicPrefix: string, options?: {
         apiBase?: string;
@@ -47,7 +51,15 @@ export default class UnsApiProxy extends UnsProxy {
         tags?: string[];
         queryParams?: IGetEndpointOptions["queryParams"];
     }): Promise<void>;
-    post(..._args: any[]): any;
+    /**
+     * Register a POST endpoint.
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param options.apiDescription - Optional description.
+     * @param options.tags - Optional tags.
+     * @param options.requestBody - Optional request body schema for Swagger.
+     */
+    post(topic: UnsTopics, asset: UnsAsset, objectType: UnsObjectType, objectId: UnsObjectId, attribute: UnsAttribute, options?: IPostEndpointOptions): Promise<void>;
     private emitStatusMetrics;
     private registerHealthEndpoint;
     private extractBearerToken;

package/dist/uns-api-proxy.js

@@ -296,6 +296,10 @@ export default class UnsApiProxy extends UnsProxy {
     /**
      * Register a catch-all API mapping for a topic prefix (e.g., "sij/acroni/#").
      * Does not create individual API attribute nodes; the controller treats this as a fallback.
+     *
+     * This is intended for use by the uns-api-global microservice, which acts as a
+     * catch-all gateway for an entire topic namespace. Regular microservices should
+     * NOT call this — use registerGetEndpoint() for individual attribute endpoints instead.
      */
     async registerCatchAll(topicPrefix, options) {
         while (this.app.server.listening === false) {
@@ -379,9 +383,141 @@ export default class UnsApiProxy extends UnsProxy {
             swaggerPath,
         });
     }
-    post(..._args) {
-        // Implement POST logic or route binding here
-        return "POST called";
+    /**
+     * Register a POST endpoint.
+     * @param topic - The API topic
+     * @param attribute - The attribute for the topic.
+     * @param options.apiDescription - Optional description.
+     * @param options.tags - Optional tags.
+     * @param options.requestBody - Optional request body schema for Swagger.
+     */
+    async post(topic, asset, objectType, objectId, attribute, options) {
+        while (this.app.server.listening === false) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        const time = UnsPacket.formatToISO8601(new Date());
+        const fullPath = buildUnsRoutePath(topic, asset, objectType, objectId, attribute);
+        const apiPath = `${this.apiBasePrefix}${fullPath}`.replace(/\/{2,}/g, "/");
+        const swaggerPath = buildSwaggerPath(this.swaggerBasePrefix, this.processName, this.instanceName);
+        try {
+            const addressInfo = this.app.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 = "";
+            }
+            this.registerApiEndpoint({
+                timestamp: time,
+                topic,
+                attribute,
+                apiHost: `http://${ip}:${port}`,
+                apiEndpoint: apiPath,
+                apiMethod: "POST",
+                apiQueryParams: [],
+                apiDescription: options?.apiDescription,
+                attributeType: UnsAttributeType.Api,
+                apiSwaggerEndpoint: swaggerPath,
+                asset,
+                objectType,
+                objectId,
+            });
+            const handler = (req, res) => {
+                this.event.emit("apiPostEvent", { req, res });
+            };
+            if (this.options?.jwks?.wellKnownJwksUrl) {
+                this.app.router.post(fullPath, async (req, res) => {
+                    try {
+                        const token = this.extractBearerToken(req, res);
+                        if (!token)
+                            return;
+                        const publicKey = await this.getPublicKeyFromJwks(token);
+                        const algorithms = this.options.jwks.algorithms || ["RS256"];
+                        const decoded = jwt.verify(token, publicKey, { algorithms });
+                        const accessRules = Array.isArray(decoded?.accessRules)
+                            ? decoded.accessRules
+                            : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
+                                ? [decoded.pathFilter]
+                                : undefined);
+                        const allowed = Array.isArray(accessRules)
+                            ? accessRules.some((rule) => UnsTopicMatcher.matches(rule, fullPath))
+                            : false;
+                        if (!allowed) {
+                            return res.status(403).json({ error: "Path not allowed by token access rules" });
+                        }
+                        handler(req, res);
+                    }
+                    catch (err) {
+                        return res.status(401).json({ error: "Invalid token" });
+                    }
+                });
+            }
+            else if (this.options?.jwtSecret) {
+                this.app.router.post(fullPath, (req, res) => {
+                    const authHeader = req.headers["authorization"];
+                    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+                        return res.status(401).json({ error: "Missing or invalid Authorization header" });
+                    }
+                    const token = authHeader.slice(7);
+                    try {
+                        const decoded = jwt.verify(token, process.env.JWT_SECRET || this.options.jwtSecret);
+                        const accessRules = Array.isArray(decoded?.accessRules)
+                            ? decoded.accessRules
+                            : (typeof decoded?.pathFilter === "string" && decoded.pathFilter.length > 0
+                                ? [decoded.pathFilter]
+                                : undefined);
+                        const allowed = Array.isArray(accessRules)
+                            ? accessRules.some((rule) => UnsTopicMatcher.matches(rule, fullPath))
+                            : false;
+                        if (!allowed) {
+                            return res.status(403).json({ error: "Path not allowed by token access rules" });
+                        }
+                        handler(req, res);
+                    }
+                    catch (err) {
+                        return res.status(401).json({ error: "Invalid token" });
+                    }
+                });
+            }
+            else {
+                this.app.router.post(fullPath, handler);
+            }
+            if (this.app.swaggerSpec) {
+                const requestBody = options?.requestBody;
+                this.app.swaggerSpec.paths = this.app.swaggerSpec.paths || {};
+                this.app.swaggerSpec.paths[apiPath] = this.app.swaggerSpec.paths[apiPath] || {};
+                this.app.swaggerSpec.paths[apiPath].post = {
+                    summary: options?.apiDescription || "No description",
+                    tags: options?.tags || [],
+                    ...(requestBody
+                        ? {
+                            requestBody: {
+                                description: requestBody.description,
+                                required: requestBody.required ?? true,
+                                content: {
+                                    "application/json": {
+                                        schema: requestBody.schema ?? { type: "object" },
+                                    },
+                                },
+                            },
+                        }
+                        : {}),
+                    responses: {
+                        "200": { description: "OK" },
+                        "400": { description: "Bad Request" },
+                        "401": { description: "Unauthorized" },
+                        "403": { description: "Forbidden" },
+                    },
+                };
+            }
+        }
+        catch (error) {
+            logger.error(`${this.instanceNameWithSuffix} - Error registering POST route ${fullPath}: ${error.message}`);
+        }
     }
     emitStatusMetrics() {
         const uptimeMinutes = Math.round((Date.now() - this.startedAt) / 60000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/api",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "Express-powered API gateway plugin for UnsProxyProcess with JWT/JWKS support.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "cookie-parser": "^1.4.7",
     "express": "^5.1.0",
     "multer": "^2.0.2",
-    "@uns-kit/core": "2.0.29"
+    "@uns-kit/core": "2.0.31"
   },
   "devDependencies": {
     "@types/jsonwebtoken": "^9.0.10",