@mxtommy/kip 3.10.0-beta.30 → 3.10.0-beta.32

package/kip-plugin/README.md

@@ -0,0 +1,64 @@
+# KIP Plugin – Displays API
+
+Base path for plugin routes: `/plugins/kip`
+
+## Endpoints
+
+- GET `/plugins/kip/displays`
+  - Returns: `[{ displayId: string, displayName: string | null }]`
+
+- GET `/plugins/kip/displays/{displayId}`
+  - Returns the raw object stored at `self.displays.{displayId}` (or `null`).
+
+- PUT `/plugins/kip/displays/{displayId}`
+  - Body: arbitrary JSON object to store under `self.displays.{displayId}` (or `null` to clear).
+  - Returns: `{ state: "SUCCESS", statusCode: 200 }` on success.
+
+- GET `/plugins/kip/displays/{displayId}/activeScreen`
+  - Returns: `number | null` – the active screen index.
+
+- PUT `/plugins/kip/displays/{displayId}/activeScreen`
+  - Body: `{ "screenIdx": number | null }`
+  - Returns: `{ state: "SUCCESS", statusCode: 200 }` on success.
+
+## Examples
+
+- List displays
+
+```sh
+curl -s http://localhost:3000/plugins/kip/displays | jq
+```
+
+- Read a display entry
+
+```sh
+curl -s http://localhost:3000/plugins/kip/displays/<displayId> | jq
+```
+
+- Set a display entry
+
+```sh
+curl -s -X PUT \
+  -H 'Content-Type: application/json' \
+  -d '{"displayName":"Mast"}' \
+  http://localhost:3000/plugins/kip/displays/<displayId>
+```
+
+- Get active screen
+
+```sh
+curl -s http://localhost:3000/plugins/kip/displays/<displayId>/activeScreen
+```
+
+- Set active screen
+
+```sh
+curl -s -X PUT \
+  -H 'Content-Type: application/json' \
+  -d '{"screenIdx":1}' \
+  http://localhost:3000/plugins/kip/displays/<displayId>/activeScreen
+```
+
+Notes:
+- Replace `<displayId>` with the KIP instance UUID under `self.displays`.
+- If your Signal K server requires auth, include cookies or bearer token accordingly.

package/kip-plugin/src/index.ts

@@ -1,14 +1,37 @@
 import { Path, Plugin, ServerAPI, SKVersion } from '@signalk/server-api'
-import { Request, Response } from 'express'
-//import * as openapi from './openApi.json';
+import { Request, Response, NextFunction } from 'express'
+import * as openapi from './openApi.json';
 
 export default (server: ServerAPI): Plugin => {
 
   const API_PATHS = {
-    DISPLAYS_PATH: `/displays/:kipId`,
-    ACTIVESCREEN_PATH: `/displays/:kipId/activeScreen`
+    DISPLAYS: `/displays`,
+    INSTANCE: `/displays/:displayId`,
+    ACTIVE_SCREEN: `/displays/:displayId/activeScreen`
   } as const;
 
+  // Helpers
+  function getDisplaySelfPath(displayId: string, suffix?: string): string {
+    const tail = suffix ? `.${suffix}` : ''
+    const full = server.getSelfPath(`displays.${displayId}${tail}`)
+    server.debug(`getDisplaySelfPath: displayId=${displayId}, suffix=${suffix}, fullPath transform output=${full}`)
+    return full
+  }
+
+  function readSelfDisplays(): Record<string, { displayName?: string }> | undefined {
+    const fullPath = server.getSelfPath('displays'); // e.g., vessels.self.displays
+    return server.getPath(fullPath) as Record<string, { displayName?: string }> | undefined;
+  }
+
+  function sendOk(res: Response, body?: unknown) {
+    if (body === undefined) return res.status(204).end()
+    return res.status(200).json(body)
+  }
+
+  function sendFail(res: Response, statusCode: number, message: string) {
+    return res.status(statusCode).json({ state: 'FAILED', statusCode, message })
+  }
+
   const plugin: Plugin = {
     id: 'kip',
     name: 'KIP',
@@ -16,9 +39,6 @@ export default (server: ServerAPI): Plugin => {
     start: (settings) => {
       server.debug(`Starting plugin with settings: ${JSON.stringify(settings)}`);
       server.setPluginStatus(`Starting...`)
-
-      const p = server.getSelfPath('displays.*');
-      server.debug(`Self path for displays.*: ${p}`);
     },
     stop: () => {
       server.debug(`Stopping plugin`);
@@ -26,19 +46,55 @@ export default (server: ServerAPI): Plugin => {
       server.setPluginStatus(msg)
     },
     schema: () => {
-        return {
-          type: "object",
-          properties: {}
-        };
+      return {
+        type: "object",
+        properties: {}
+      };
     },
     registerWithRouter(router) {
-      server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS_PATH}`);
+      server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS}, ${API_PATHS.INSTANCE}, ${API_PATHS.ACTIVE_SCREEN}`);
+
+      // Validate/normalize :displayId where present
+      router.param('displayId', (req: Request & { displayId?: string }, res: Response, next: NextFunction, displayId: string) => {
+        if (displayId == null) return sendFail(res, 400, 'Missing displayId parameter')
+        try {
+          let id = String(displayId)
+          // Decode percent-encoding if present
+          try {
+            id = decodeURIComponent(id)
+          } catch {
+            // ignore decode errors, keep original id
+          }
+          // If someone sent JSON as the path segment, try to recover {"displayId":"..."}
+          if (id.trim().startsWith('{')) {
+            try {
+              const parsed = JSON.parse(id)
+              if (parsed && typeof parsed.displayId === 'string') {
+                id = parsed.displayId
+              } else {
+                return sendFail(res, 400, 'Invalid displayId format in JSON')
+              }
+            } catch {
+              return sendFail(res, 400, 'Invalid displayId JSON')
+            }
+          }
+          // Basic safety: allow UUID-like strings (alphanum + dash)
+          if (!/^[A-Za-z0-9-]+$/.test(id)) {
+            return sendFail(res, 400, 'Invalid displayId format')
+          }
+          req.displayId = id
+          next()
+        } catch {
+          return sendFail(res, 400, 'Missing or invalid displayId parameter')
+        }
+      })
 
-      router.put(`${API_PATHS.DISPLAYS_PATH}`, async (req: Request, res: Response) => {
-        server.debug(`** PUT path ${API_PATHS.DISPLAYS_PATH}. Request Params: ${JSON.stringify(req.params)}, Body: ${JSON.stringify(req.body)}, Method: ${req.method}, Path: ${req.path}`);
+      router.put(`${API_PATHS.INSTANCE}`, async (req: Request, res: Response) => {
+        server.debug(`** PUT ${API_PATHS.INSTANCE}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
         try {
-          const dottedPath = pathToDotNotation(req.path);
-          server.debug(`Converted request path ${req.path} to dot notation ${dottedPath} and updating SK path with req.body`);
+          const displayId = (req as Request & { displayId: string }).displayId
+          const fullPath = getDisplaySelfPath(displayId)
+          server.debug(`Updating SK path ${fullPath} with body`)
           server.handleMessage(
             plugin.id,
             {
@@ -46,8 +102,8 @@ export default (server: ServerAPI): Plugin => {
                 {
                   values: [
                     {
-                      path: dottedPath as Path,
-                      value: req.body ? req.body : null
+                      path: fullPath as Path,
+                      value: req.body ?? null
                     }
                   ]
                 }
@@ -55,29 +111,23 @@ export default (server: ServerAPI): Plugin => {
             },
             SKVersion.v1
           );
-          return res.status(200).json({
-            state: 'SUCCESS',
-            statusCode: 200
-          });
+          return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
 
         } catch (error) {
           const msg = `HandleMessage failed with errors!`
           server.setPluginError(msg)
           server.error(`Error in HandleMessage: ${error}`);
 
-          return res.status(400).json({
-            state: 'FAILED',
-            statusCode: 400,
-            message: (error as Error).message
-          });
+          return sendFail(res, 400, (error as Error).message)
         }
       });
 
-      router.put(`${API_PATHS.ACTIVESCREEN_PATH}`, async (req: Request, res: Response) => {
-        server.debug(`** PUT path ${API_PATHS.ACTIVESCREEN_PATH}. Request Params: ${JSON.stringify(req.params)}, Body: ${JSON.stringify(req.body)}, Method: ${req.method}, Path: ${req.path}`);
+      router.put(`${API_PATHS.ACTIVE_SCREEN}`, async (req: Request, res: Response) => {
+        server.debug(`** PUT ${API_PATHS.ACTIVE_SCREEN}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
         try {
-          const dottedPath = pathToDotNotation(req.path);
-          server.debug(`Converted request path ${req.path} to dot notation ${dottedPath} and updating SK path with req.body`);
+          const displayId = (req as Request & { displayId: string }).displayId
+          const fullPath = getDisplaySelfPath(displayId, 'activeScreen')
+          server.debug(`Updating SK path ${fullPath} with body.screenIdx`)
           server.handleMessage(
             plugin.id,
             {
@@ -85,8 +135,8 @@ export default (server: ServerAPI): Plugin => {
                 {
                   values: [
                     {
-                      path: dottedPath as Path,
-                      value: req.body.screenId
+                      path: fullPath as Path,
+                      value: req.body.screenIdx !== undefined ? req.body.screenIdx : null
                     }
                   ]
                 }
@@ -94,21 +144,80 @@ export default (server: ServerAPI): Plugin => {
             },
             SKVersion.v1
           );
-          return res.status(200).json({
-            state: 'SUCCESS',
-            statusCode: 200
-          });
+          return res.status(200).json({ state: 'SUCCESS', statusCode: 200 });
 
         } catch (error) {
           const msg = `HandleMessage failed with errors!`
           server.setPluginError(msg)
           server.error(`Error in HandleMessage: ${error}`);
 
-          return res.status(400).json({
-            state: 'FAILED',
-            statusCode: 400,
-            message: (error as Error).message
-          });
+          return sendFail(res, 400, (error as Error).message)
+        }
+      });
+
+      router.get(API_PATHS.DISPLAYS, (req: Request, res: Response) => {
+        server.debug(`** GET ${API_PATHS.DISPLAYS}. Params: ${JSON.stringify(req.params)}`);
+        try {
+          const displays = readSelfDisplays();
+          const items =
+            displays && typeof displays === 'object'
+              ? Object.entries(displays)
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                .filter(([_, v]) => v && typeof v === 'object')
+                .map(([displayId, v]: [string, { displayName?: string }]) => ({
+                  displayId,
+                  displayName: v.displayName ?? null
+                }))
+              : [];
+
+          return res.status(200).json(items);
+        } catch (error) {
+          server.error(`Error reading displays: ${String((error as Error).message || error)}`);
+          return sendFail(res, 400, (error as Error).message)
+        }
+      });
+
+      router.get(`${API_PATHS.INSTANCE}`, (req: Request, res: Response) => {
+        server.debug(`** GET ${API_PATHS.INSTANCE}. Params: ${JSON.stringify(req.params)}`);
+        try {
+          const displayId = (req as Request & { displayId?: string }).displayId
+          if (!displayId) {
+            return sendFail(res, 400, 'Missing displayId parameter')
+          }
+
+          const fullPath = getDisplaySelfPath(displayId);
+          const value = server.getPath(fullPath);
+
+          if (value === undefined) {
+            return sendFail(res, 404, `Display ${displayId} not found`)
+          }
+
+          return sendOk(res, value);
+        } catch (error) {
+          server.error(`Error reading display ${req.params?.displayId}: ${String((error as Error).message || error)}`);
+          return sendFail(res, 400, (error as Error).message)
+        }
+      });
+
+      router.get(`${API_PATHS.ACTIVE_SCREEN}`, (req: Request, res: Response) => {
+        server.debug(`** GET ${API_PATHS.ACTIVE_SCREEN}. Params: ${JSON.stringify(req.params)}`);
+        try {
+          const displayId = (req as Request & { displayId?: string }).displayId
+          if (!displayId) {
+            return sendFail(res, 400, 'Missing displayId parameter')
+          }
+
+          const fullPath = getDisplaySelfPath(displayId, 'activeScreen');
+          const value = server.getPath(fullPath);
+
+          if (value === undefined) {
+            return sendFail(res, 404, `Active screen for display ${displayId} not found`)
+          }
+
+          return sendOk(res, value);
+        } catch (error) {
+          server.error(`Error reading activeScreen for ${req.params?.displayId}: ${String((error as Error).message || error)}`);
+          return sendFail(res, 400, (error as Error).message)
         }
       });
 
@@ -121,16 +230,10 @@ export default (server: ServerAPI): Plugin => {
         });
       }
 
-      server.setPluginStatus(`Providing remote display control`);
-    }
+      server.setPluginStatus(`Providing remote display screen control`);
+    },
+    getOpenApi: () => openapi
   };
 
-  /*
-  * Replace all / with . and remove leading.
-  */
-  function pathToDotNotation(path: string): string {
-    return path.replace(/\//g, '.').replace(/^\./, '');
-  }
-
   return plugin;
 }

package/kip-plugin/src/openApi.json

@@ -0,0 +1,141 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "KIP Remote Displays API",
+    "description": "API endpoints to list KIP displays and control the active screen for a given KIP instance via Signal K self.displays tree.\n\nUsage:\n- List displays:\n  curl -s http://localhost:3000/plugins/kip/displays\n- Read a display entry:\n  curl -s http://localhost:3000/plugins/kip/displays/{displayId}\n- Set a display entry:\n  curl -s -X PUT -H 'Content-Type: application/json' -d '{\"displayName\":\"Mast\"}' http://localhost:3000/plugins/kip/displays/{displayId}\n- Get active screen:\n  curl -s http://localhost:3000/plugins/kip/displays/{displayId}/activeScreen\n- Set active screen:\n  curl -s -X PUT -H 'Content-Type: application/json' -d '{\"screenIdx\":1}' http://localhost:3000/plugins/kip/displays/{displayId}/activeScreen",
+    "termsOfService": "http://signalk.org/terms/",
+    "license": {
+      "name": "Apache 2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "externalDocs": {
+    "url": "http://signalk.org/specification/",
+    "description": "Signal K specification."
+  },
+  "servers": [
+    { "url": "/" }
+  ],
+  "tags": [
+    { "name": "Displays", "description": "KIP display discovery and control." }
+  ],
+  "components": {
+    "schemas": {
+      "DisplayInfo": {
+        "type": "object",
+        "properties": {
+          "displayId": { "type": "string", "description": "KIP instance UUID" },
+          "displayName": { "type": "string", "nullable": true }
+        },
+        "required": ["displayId"]
+      },
+      "SuccessResponse": {
+        "type": "object",
+        "properties": {
+          "state": { "type": "string", "enum": ["SUCCESS"] },
+          "statusCode": { "type": "integer", "enum": [200] }
+        },
+        "required": ["state", "statusCode"]
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "state": { "type": "string", "enum": ["FAILED"] },
+          "statusCode": { "type": "integer" },
+          "message": { "type": "string" }
+        },
+        "required": ["state", "statusCode", "message"]
+      },
+      "ActiveScreenSetRequest": {
+        "type": "object",
+        "properties": {
+          "screenIdx": { "type": "integer", "nullable": true, "description": "Index of active screen or null to clear" }
+        }
+      },
+      "AnyObjectOrNull": {
+        "oneOf": [
+          { "type": "object", "additionalProperties": true },
+          { "type": "null" }
+        ]
+      }
+    },
+    "parameters": {
+      "DisplayIdParam": {
+        "in": "path",
+        "required": true,
+        "name": "displayId",
+        "description": "KIP instance UUID",
+        "schema": { "type": "string" }
+      }
+    },
+    "securitySchemes": {
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
+      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "JAUTHENTICATION" }
+    }
+  },
+  "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }],
+  "paths": {
+    "/plugins/kip/displays": {
+      "get": {
+        "tags": ["Displays"],
+        "summary": "List available KIP displays",
+        "responses": {
+          "200": {
+            "description": "List of KIP instances discovered under self.displays",
+            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DisplayInfo" } } } }
+          },
+          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
+  "/plugins/kip/displays/{displayId}": {
+      "parameters": [ { "$ref": "#/components/parameters/DisplayIdParam" } ],
+      "get": {
+        "tags": ["Displays"],
+        "summary": "Get raw display entry under self.displays.{displayId}",
+        "responses": {
+          "200": { "description": "Display object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyObjectOrNull" } } } },
+          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      },
+      "put": {
+        "tags": ["Displays"],
+        "summary": "Set display entry under self.displays.{displayId}",
+        "requestBody": {
+          "required": false,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnyObjectOrNull" } } }
+        },
+        "responses": {
+          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } },
+          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
+  "/plugins/kip/displays/{displayId}/activeScreen": {
+      "parameters": [ { "$ref": "#/components/parameters/DisplayIdParam" } ],
+      "get": {
+        "tags": ["Displays"],
+        "summary": "Get active screen index for display",
+        "responses": {
+          "200": { "description": "Active screen index or null", "content": { "application/json": { "schema": { "type": "integer", "nullable": true } } } },
+          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      },
+      "put": {
+        "tags": ["Displays"],
+        "summary": "Set active screen index for display",
+        "requestBody": {
+          "required": false,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveScreenSetRequest" } } }
+        },
+        "responses": {
+          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } },
+          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxtommy/kip",
-  "version": "3.10.0-beta.30",
+  "version": "3.10.0-beta.32",
   "description": "An advanced and versatile marine instrumentation package to display Signal K data.",
   "license": "MIT",
   "author": {