@uns-kit/api 2.0.15 → 2.0.16

package/README.md

@@ -42,6 +42,14 @@ async function main() {
   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) => {
@@ -52,6 +60,9 @@ async function main() {
 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

package/dist/uns-api-proxy.js

@@ -236,18 +236,48 @@ export default class UnsApiProxy extends UnsProxy {
                 this.app.router.get(fullPath, handler);
             }
             if (this.app.swaggerSpec) {
+                const queryParams = options?.queryParams || [];
+                const canonicalParams = queryParams.reduce((acc, param) => {
+                    if (typeof param.chatCanonical === "string" && param.chatCanonical.trim().length) {
+                        acc[param.chatCanonical.trim()] = param.name;
+                    }
+                    return acc;
+                }, {});
+                const chatDefaults = {};
+                for (const param of queryParams) {
+                    if (param.defaultValue !== undefined) {
+                        chatDefaults[param.name] = param.defaultValue;
+                    }
+                }
+                const optionDefaults = options?.chatDefaults ?? {};
+                for (const [key, value] of Object.entries(optionDefaults)) {
+                    if (value !== undefined) {
+                        chatDefaults[key] = value;
+                    }
+                }
+                const unsChatMeta = Object.keys(canonicalParams).length || Object.keys(chatDefaults).length
+                    ? {
+                        canonicalParams,
+                        defaults: chatDefaults,
+                    }
+                    : null;
                 this.app.swaggerSpec.paths = this.app.swaggerSpec.paths || {};
-                this.app.swaggerSpec.paths[`/api${fullPath}`] = {
+                this.app.swaggerSpec.paths[apiPath] = {
                     get: {
                         summary: options?.apiDescription || "No description",
                         tags: options?.tags || [],
-                        parameters: (options?.queryParams || []).map((p) => ({
+                        parameters: queryParams.map((p) => ({
                             name: p.name,
                             in: "query",
                             required: !!p.required,
-                            schema: { type: p.type },
+                            schema: {
+                                type: p.type,
+                                ...(p.defaultValue !== undefined ? { default: p.defaultValue } : {}),
+                            },
                             description: p.description,
+                            ...(p.chatCanonical ? { "x-uns-chat-canonical": p.chatCanonical } : {}),
                         })),
+                        ...(unsChatMeta ? { "x-uns-chat": unsChatMeta } : {}),
                         responses: {
                             "200": { description: "OK" },
                             "400": { description: "Bad Request" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/api",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "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.15"
+    "@uns-kit/core": "2.0.16"
   },
   "devDependencies": {
     "@types/jsonwebtoken": "^9.0.10",