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

package/plugin/index.js

@@ -1,12 +1,65 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_api_1 = require("@signalk/server-api");
-//import * as openapi from './openApi.json';
+const openapi = __importStar(require("./openApi.json"));
 exports.default = (server) => {
     const API_PATHS = {
-        DISPLAYS_PATH: `/displays/:kipId`,
-        ACTIVESCREEN_PATH: `/displays/:kipId/activeScreen`
+        DISPLAYS: `/displays`,
+        INSTANCE: `/displays/:displayId`,
+        ACTIVE_SCREEN: `/displays/:displayId/activeScreen`
     };
+    // Helpers
+    function getDisplaySelfPath(displayId, suffix) {
+        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() {
+        const fullPath = server.getSelfPath('displays'); // e.g., vessels.self.displays
+        return server.getPath(fullPath);
+    }
+    function sendOk(res, body) {
+        if (body === undefined)
+            return res.status(204).end();
+        return res.status(200).json(body);
+    }
+    function sendFail(res, statusCode, message) {
+        return res.status(statusCode).json({ state: 'FAILED', statusCode, message });
+    }
     const plugin = {
         id: 'kip',
         name: 'KIP',
@@ -14,8 +67,6 @@ exports.default = (server) => {
         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`);
@@ -29,71 +80,156 @@ exports.default = (server) => {
             };
         },
         registerWithRouter(router) {
-            server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS_PATH}`);
-            router.put(`${API_PATHS.DISPLAYS_PATH}`, async (req, res) => {
-                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}`);
+            server.debug(`Registering plugin routes: ${API_PATHS.DISPLAYS}, ${API_PATHS.INSTANCE}, ${API_PATHS.ACTIVE_SCREEN}`);
+            // Validate/normalize :displayId where present
+            router.param('displayId', (req, res, next, displayId) => {
+                if (displayId == null)
+                    return sendFail(res, 400, 'Missing displayId parameter');
                 try {
-                    const dottedPath = pathToDotNotation(req.path);
-                    server.debug(`Converted request path ${req.path} to dot notation ${dottedPath} and updating SK path with req.body`);
+                    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.INSTANCE}`, async (req, res) => {
+                server.debug(`** PUT ${API_PATHS.INSTANCE}. Params: ${JSON.stringify(req.params)} Body: ${JSON.stringify(req.body)}`);
+                try {
+                    const displayId = req.displayId;
+                    const fullPath = getDisplaySelfPath(displayId);
+                    server.debug(`Updating SK path ${fullPath} with body`);
                     server.handleMessage(plugin.id, {
                         updates: [
                             {
                                 values: [
                                     {
-                                        path: dottedPath,
-                                        value: req.body ? req.body : null
+                                        path: fullPath,
+                                        value: req.body ?? null
                                     }
                                 ]
                             }
                         ]
                     }, server_api_1.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.message
-                    });
+                    return sendFail(res, 400, error.message);
                 }
             });
-            router.put(`${API_PATHS.ACTIVESCREEN_PATH}`, async (req, res) => {
-                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, res) => {
+                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.displayId;
+                    const fullPath = getDisplaySelfPath(displayId, 'activeScreen');
+                    server.debug(`Updating SK path ${fullPath} with body.screenIdx`);
                     server.handleMessage(plugin.id, {
                         updates: [
                             {
                                 values: [
                                     {
-                                        path: dottedPath,
-                                        value: req.body.screenId
+                                        path: fullPath,
+                                        value: req.body.screenIdx !== undefined ? req.body.screenIdx : null
                                     }
                                 ]
                             }
                         ]
                     }, server_api_1.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.message
-                    });
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(API_PATHS.DISPLAYS, (req, res) => {
+                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]) => ({
+                            displayId,
+                            displayName: v.displayName ?? null
+                        }))
+                        : [];
+                    return res.status(200).json(items);
+                }
+                catch (error) {
+                    server.error(`Error reading displays: ${String(error.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(`${API_PATHS.INSTANCE}`, (req, res) => {
+                server.debug(`** GET ${API_PATHS.INSTANCE}. Params: ${JSON.stringify(req.params)}`);
+                try {
+                    const displayId = req.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.message || error)}`);
+                    return sendFail(res, 400, error.message);
+                }
+            });
+            router.get(`${API_PATHS.ACTIVE_SCREEN}`, (req, res) => {
+                server.debug(`** GET ${API_PATHS.ACTIVE_SCREEN}. Params: ${JSON.stringify(req.params)}`);
+                try {
+                    const displayId = req.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.message || error)}`);
+                    return sendFail(res, 400, error.message);
                 }
             });
             // List all registered routes for debugging
@@ -104,14 +240,9 @@ exports.default = (server) => {
                     }
                 });
             }
-            server.setPluginStatus(`Providing remote display control`);
-        }
+            server.setPluginStatus(`Providing remote display screen control`);
+        },
+        getOpenApi: () => openapi
     };
-    /*
-    * Replace all / with . and remove leading.
-    */
-    function pathToDotNotation(path) {
-        return path.replace(/\//g, '.').replace(/^\./, '');
-    }
     return plugin;
 };

package/plugin/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" } } } }
+                }
+            }
+        }
+    }
+}