@mxtommy/kip 3.10.0-beta.3 → 3.10.0-beta.31

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,45 +1,210 @@
-import { Delta, Path, Plugin, ServerAPI, Value } from '@signalk/server-api'
+import { Path, Plugin, ServerAPI, SKVersion } from '@signalk/server-api'
+import { Request, Response } from 'express'
+import * as openapi from './openApi.json';
+
+export default (server: ServerAPI): Plugin => {
+
+  const API_PATHS = {
+    DISPLAYS: `/displays`,
+    INSTANCE: `/displays/:displayId`,
+    ACTIVE_SCREEN: `/displays/:displayId/activeScreen`
+  } as const;
+
+  // Helpers
+  function getDisplaySelfPath(displayId: string, suffix?: string): string {
+    const tail = suffix ? `.${suffix}` : ''
+    return server.getSelfPath(`displays.${displayId}${tail}`)
+  }
+
+  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 })
+  }
 
-export default (app: ServerAPI): Plugin => {
   const plugin: Plugin = {
     id: 'kip',
     name: 'KIP',
     description: 'KIP server plugin',
     start: (settings) => {
-      app.debug(`${plugin.name}: Starting plugin with settings: ${JSON.stringify(settings)}`);
-      app.registerPutHandler('vessels.self', 'plugins.displays.*', displayPutHandler);
+      server.debug(`Starting plugin with settings: ${JSON.stringify(settings)}`);
+      server.setPluginStatus(`Starting...`)
     },
     stop: () => {
-      app.debug(`${plugin.name}: Stopping plugin`);
+      server.debug(`Stopping plugin`);
+      const msg = 'Stopped.'
+      server.setPluginStatus(msg)
     },
     schema: () => {
-    }
-  };
+      return {
+        type: "object",
+        properties: {}
+      };
+    },
+    registerWithRouter(router) {
+      server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS}, ${API_PATHS.INSTANCE}, ${API_PATHS.ACTIVE_SCREEN}`);
+
+      // Validate :displayId where present
+      router.param('displayId', (req, res, next, displayId) => {
+        if (!displayId || typeof displayId !== 'string') {
+          return sendFail(res, 400, 'Missing or invalid displayId parameter')
+        }
+        next()
+      })
+
+      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 { displayId } = req.params as { displayId: string }
+          const fullPath = getDisplaySelfPath(displayId)
+          server.debug(`Updating SK path ${fullPath} with body`)
+          server.handleMessage(
+            plugin.id,
+            {
+              updates: [
+                {
+                  values: [
+                    {
+                      path: fullPath as Path,
+                      value: req.body ?? null
+                    }
+                  ]
+                }
+              ]
+            },
+            SKVersion.v1
+          );
+          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 sendFail(res, 400, (error as Error).message)
+        }
+      });
+
+      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 { displayId } = req.params as { displayId: string }
+          const fullPath = getDisplaySelfPath(displayId, 'activeScreen')
+          server.debug(`Updating SK path ${fullPath} with body.screenIdx`)
+          server.handleMessage(
+            plugin.id,
+            {
+              updates: [
+                {
+                  values: [
+                    {
+                      path: fullPath as Path,
+                      value: req.body.screenIdx !== undefined ? req.body.screenIdx : null
+                    }
+                  ]
+                }
+              ]
+            },
+            SKVersion.v1
+          );
+          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 sendFail(res, 400, (error as Error).message)
+        }
+      });
 
-  function displayPutHandler(context: string, path: string, value: Value): { state: 'COMPLETED'; statusCode: number; message?: string } {
-    app.debug(`${plugin.name}: PUT handler called for context ${context}, path ${path}, value ${value}`);
-    try {
-      const delta: Delta = {
-        updates: [
-          {
-            values: [
-              {
-                path: path as Path,
-                value: value
-              }
-            ]
+      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.params as { displayId?: string };
+          if (!displayId) {
+            return sendFail(res, 400, 'Missing displayId parameter')
           }
-        ]
-      };
-      app.debug(`${plugin.name}: Sending message: `, JSON.stringify(delta));
-      app.handleMessage(plugin.id, delta);
-      return { state: "COMPLETED" as const, statusCode: 200 };
-
-    } catch (error) {
-      app.error(`${plugin.name}: Error in PUT handler: ${error}`);
-      return { state: "COMPLETED" as const, statusCode: 500, message: (error as Error).message };
-    }
-  }
+
+          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.params as { displayId?: string };
+          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)
+        }
+      });
+
+      // List all registered routes for debugging
+      if (router.stack) {
+        router.stack.forEach((layer: { route?: { path?: string; stack: { method: string }[] } }) => {
+          if (layer.route && layer.route.path) {
+            server.debug(`Registered route: ${layer.route.stack[0].method.toUpperCase()} ${layer.route.path}`);
+          }
+        });
+      }
+
+      server.setPluginStatus(`Providing remote display screen control`);
+    },
+    getOpenApi: () => openapi
+  };
 
   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.3",
+  "version": "3.10.0-beta.31",
   "description": "An advanced and versatile marine instrumentation package to display Signal K data.",
   "license": "MIT",
   "author": {
@@ -25,6 +25,7 @@
   "keywords": [
     "signalk-webapp",
     "signalk-category-instruments",
+    "signalk-category-notifications",
     "signalk-node-server-plugin",
     "signal k",
     "signalk",
@@ -46,7 +47,7 @@
     "build:plugin": "tsc -p ./kip-plugin/tsconfig.plugin.json",
     "build:dev": "ng build --configuration=dev",
     "build:prod": "ng build --configuration=production",
-    "build:all": "npm run build:prod && npm run build:plugin",
+    "build:all": "npm run build:plugin && npm run build:prod",
     "e2e": "ng e2e"
   },
   "devDependencies": {