@mxtommy/kip 4.4.0 → 4.5.0

package/plugin/openApi.json

@@ -2,8 +2,8 @@
     "openapi": "3.0.0",
     "info": {
         "version": "1.1.0",
-        "title": "KIP Remote Displays API",
-        "description": "API endpoints to list KIP displays and control dashboard for a given KIP instance via the Signal K self.displays tree.\n\nUsage:\n- List displays:\n  curl -s http://localhost:3000/plugins/kip/displays\n- Read a display's screens:\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 current screen index:\n  curl -s http://localhost:3000/plugins/kip/displays/{displayId}/screenIndex\n- Set current screen index:\n  curl -s -X PUT -H 'Content-Type: application/json' -d '{\"screenIdx\":1}' http://localhost:3000/plugins/kip/displays/{displayId}/screenIndex\n- Get requested screen change index:\n  curl -s http://localhost:3000/plugins/kip/displays/{displayId}/activeScreen\n- Request a screen change:\n  curl -s -X PUT -H 'Content-Type: application/json' -d '{\"screenIdx\":1}' http://localhost:3000/plugins/kip/displays/{displayId}/activeScreen",
+        "title": "KIP Plugin API",
+        "description": "Endpoints\n- List remote displays and control remote dashboard of a given KIP instance.\n- Configure data series for widget framework historical data series and data chart widgets.",
         "termsOfService": "http://signalk.org/terms/",
         "license": {
             "name": "Apache 2.0",
@@ -22,7 +22,11 @@
     "tags": [
         {
             "name": "Displays",
-            "description": "KIP display discovery and control."
+            "description": "KIP remote display discovery and control."
+        },
+        {
+            "name": "Series",
+            "description": "KIP widget history series configuration."
         }
     ],
     "components": {
@@ -63,17 +67,11 @@
                 ]
             },
             "ScreenListOrNull": {
-                "oneOf": [
-                    {
-                        "type": "array",
-                        "items": {
-                            "$ref": "#/components/schemas/ScreenItem"
-                        }
-                    },
-                    {
-                        "type": "null"
-                    }
-                ]
+                "type": "array",
+                "nullable": true,
+                "items": {
+                    "$ref": "#/components/schemas/ScreenItem"
+                }
             },
             "SuccessResponse": {
                 "type": "object",
@@ -129,14 +127,86 @@
                 }
             },
             "AnyObjectOrNull": {
-                "oneOf": [
-                    {
-                        "type": "object",
-                        "additionalProperties": true
+                "type": "object",
+                "nullable": true,
+                "additionalProperties": true
+            },
+            "SeriesDefinition": {
+                "type": "object",
+                "properties": {
+                    "seriesId": {
+                        "type": "string"
+                    },
+                    "datasetUuid": {
+                        "type": "string"
+                    },
+                    "ownerWidgetUuid": {
+                        "type": "string"
+                    },
+                    "ownerWidgetSelector": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "context": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "source": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "timeScale": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "period": {
+                        "type": "integer",
+                        "nullable": true
+                    },
+                    "retentionDurationMs": {
+                        "type": "integer",
+                        "nullable": true
+                    },
+                    "sampleTime": {
+                        "type": "integer",
+                        "nullable": true
+                    },
+                    "enabled": {
+                        "type": "boolean",
+                        "default": true
+                    }
+                },
+                "required": [
+                    "seriesId",
+                    "datasetUuid",
+                    "ownerWidgetUuid",
+                    "path"
+                ]
+            },
+            "SeriesReconcileResult": {
+                "type": "object",
+                "properties": {
+                    "created": {
+                        "type": "integer"
                     },
-                    {
-                        "type": "null"
+                    "updated": {
+                        "type": "integer"
+                    },
+                    "deleted": {
+                        "type": "integer"
+                    },
+                    "total": {
+                        "type": "integer"
                     }
+                },
+                "required": [
+                    "created",
+                    "updated",
+                    "deleted",
+                    "total"
                 ]
             }
         },
@@ -149,6 +219,15 @@
                 "schema": {
                     "type": "string"
                 }
+            },
+            "SeriesIdParam": {
+                "in": "path",
+                "required": true,
+                "name": "seriesId",
+                "description": "Series identifier (dataset UUID)",
+                "schema": {
+                    "type": "string"
+                }
             }
         },
         "securitySchemes": {
@@ -456,6 +535,165 @@
                     }
                 }
             }
+        },
+        "/plugins/kip/series": {
+            "get": {
+                "tags": [
+                    "Series"
+                ],
+                "summary": "List all configured history series",
+                "responses": {
+                    "200": {
+                        "description": "Current series definitions",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/SeriesDefinition"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/plugins/kip/series/{seriesId}": {
+            "parameters": [
+                {
+                    "$ref": "#/components/parameters/SeriesIdParam"
+                }
+            ],
+            "put": {
+                "tags": [
+                    "Series"
+                ],
+                "summary": "Create or update a series definition",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/SeriesDefinition"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Series upserted",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SeriesDefinition"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "tags": [
+                    "Series"
+                ],
+                "summary": "Delete a series definition",
+                "responses": {
+                    "200": {
+                        "description": "Series removed",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SuccessResponse"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Series not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/plugins/kip/series/reconcile": {
+            "post": {
+                "tags": [
+                    "Series"
+                ],
+                "summary": "Reconcile full desired series set",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "array",
+                                "items": {
+                                    "$ref": "#/components/schemas/SeriesDefinition"
+                                }
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Reconcile summary",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SeriesReconcileResult"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     }
 }

package/plugin/plugin-auth.service.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUserScope = normalizeUserScope;
+exports.resolveAuthenticatedUserScope = resolveAuthenticatedUserScope;
+exports.resolveReadUserScope = resolveReadUserScope;
+exports.resolveWriteUserScopeOrReject = resolveWriteUserScopeOrReject;
+/**
+ * Normalizes a candidate user scope value.
+ *
+ * @param {unknown} value Candidate scope value.
+ * @returns {string | null} Trimmed scope or null when empty.
+ *
+ * @example
+ * const scope = normalizeUserScope(' demo-user ');
+ */
+function normalizeUserScope(value) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    return normalized.length > 0 ? normalized : null;
+}
+/**
+ * Resolves authenticated user scope from request identity fields.
+ *
+ * @param {Request} req Incoming Express request.
+ * @returns {string | null} Resolved scope or null when unavailable.
+ *
+ * @example
+ * const scope = resolveAuthenticatedUserScope(req);
+ */
+function resolveAuthenticatedUserScope(req) {
+    // Check for skPrincipal.identifier as the primary method for authenticated scope resolution
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const skPrincipal = req.skPrincipal;
+    if (skPrincipal && typeof skPrincipal === 'object') {
+        const skPrincipalId = normalizeUserScope(skPrincipal.identifier);
+        if (skPrincipalId) {
+            return skPrincipalId;
+        }
+    }
+    return null;
+}
+/**
+ * Resolves user scope for read operations, returning a fallback when unauthenticated.
+ *
+ * @param {Request} req Incoming Express request.
+ * @param {string} [fallback='anonymous'] Fallback scope value.
+ * @returns {string} Resolved or fallback scope.
+ *
+ * @example
+ * const scope = resolveReadUserScope(req);
+ */
+function resolveReadUserScope(req, fallback = 'anonymous') {
+    return resolveAuthenticatedUserScope(req) ?? fallback;
+}
+/**
+ * Resolves user scope for write operations and rejects the request when unresolved.
+ *
+ * @param {Request} req Incoming Express request.
+ * @param {Response} res Express response used for rejection.
+ * @param {string} operation Operation label for diagnostics.
+ * @param {(message: string) => void} errorLogger Logger callback for refusal messages.
+ * @param {TAuthFailureResponder} sendFail Response helper callback.
+ * @returns {string | null} Resolved scope or null when rejected.
+ *
+ * @example
+ * const scope = resolveWriteUserScopeOrReject(req, res, 'PUT /series/:seriesId', console.error, sendFail);
+ */
+function resolveWriteUserScopeOrReject(req, res, operation, errorLogger, sendFail) {
+    const userScope = resolveAuthenticatedUserScope(req);
+    if (userScope) {
+        return userScope;
+    }
+    errorLogger(`[SERIES AUTH] Refused ${operation}: unresolved authenticated user scope method=${req.method} path=${req.path} ip=${req.ip}`);
+    sendFail(res, 403, 'Authenticated user scope is required for series write operations');
+    return null;
+}

package/public/assets/help-docs/chartplotter.md

@@ -1,12 +1,10 @@
 ## Chartplotter Mode
 Chartplotter Mode provides a persistent dual‑panel navigation layout: a continuously live Freeboard‑SK chart on one side and an actively switchable KIP dashboard on the other. Switching dashboards never unloads or blinks the chart, giving you an MFD‑style experience powered entirely by Signal K.
 
----
 
 ## When to Use It
 Use Chartplotter Mode when you want uninterrupted situational awareness (chart + vessel motion + routing context) while cycling between specialized dashboards (navigation, engines, energy, racing, night watch, etc.). If you only need a chart on a few dashboards or have very constrained hardware, the standalone Freeboard‑SK widget may be sufficient.
 
----
 
 ## Key Capabilities
 - Persistent Freeboard‑SK chart (no reload on dashboard change)
@@ -16,7 +14,6 @@ Use Chartplotter Mode when you want uninterrupted situational awareness (chart +
 - Remote dashboard switching compatible (chart forced collapse preserved remotely)
 - Optional panel side selection (left or right)
 
----
 
 ## Enabling & Basic Setup
 1. Open Actions → Settings → Display.
@@ -25,9 +22,8 @@ Use Chartplotter Mode when you want uninterrupted situational awareness (chart +
 4. Optionally, enable the per‑dashboard “Auto-collapse Freeboard-SK panel when displaying this dashboard” flag if you want that dashboard to hide the chart and use the full width.
 5. Enter dashboard edit mode if you wish to resize the split (see Resizing section), then Save to persist or Cancel to discard.
 
-Tip: Remove any existing Freeboard‑SK widget instances to avoid redundant chart rendering once mode is enabled.
+>**Tip:** Remove any existing Freeboard‑SK widget instances to avoid redundant chart rendering once mode is enabled.
 
----
 
 ## Orientation & Layout Behavior
 | Environment | Layout |
@@ -37,7 +33,6 @@ Tip: Remove any existing Freeboard‑SK widget instances to avoid redundant char
 
 The transition is automatic; no manual toggle is required. The per‑dashboard collapse still applies regardless of orientation.
 
----
 
 ## Resizing the Split
 1. Enter dashboard edit mode on any dashboard (Actions → Unlock / Edit button).
@@ -46,12 +41,11 @@ The transition is automatic; no manual toggle is required. The per‑dashboard c
 
 <img src="../../assets/help-docs/img/splitdeviderhandle.png" alt="Resize the split" title="Split handle" width="100%">
 
-Notes:
-- Width changes are only committed on Save (prevents accidental layout shifts).
-- Cancel always restores the original ratio before the edit session began.
-- The persisted ratio applies across dashboards (unless a dashboard is collapsed).
+>**Notes:**
+>- Width changes are only committed on Save (prevents accidental layout shifts).
+>- Cancel always restores the original ratio before the edit session began.
+>- The persisted ratio applies across dashboards (unless a dashboard is collapsed).
 
----
 
 ## Per‑Dashboard Collapse
 Each dashboard can force the chart panel closed to maximize data area. This is ideal for engine diagnostics, racing performance pages, or night watch minimalism. When you switch to a collapsed dashboard, the chart panel is hidden; switching back to a normal dashboard restores it instantly with its prior state and zoom.
@@ -61,12 +55,10 @@ Characteristics:
 - No chart reload occurs when re‑expanding—state (position, zoom, layers) persists.
 - Remote control switches respect the same collapse logic.
 
----
 
 ## Selecting Chart Panel Side
 Change side via Settings → Display → “Freeboard‑SK panel side”. This updates the split instantly. If a dashboard is collapsed, the side preference is applied the next time a non‑collapsed dashboard is shown.
 
----
 
 ## Chartplotter Mode vs Freeboard‑SK Widget
 | Aspect | Chartplotter Mode | Freeboard‑SK Widget |
@@ -78,12 +70,10 @@ Change side via Settings → Display → “Freeboard‑SK panel side”. This u
 | Memory footprint | Higher baseline (Freeboard-SK always resident) | Lower when dashboard lack the widget |
 | Best for | Continuous nav + multi‑dashboard workflow (MFD) | Occasional chart reference |
 
----
 
 ## Remote Control Integration
 When another KIP instance changes your active dashboard (Remote Control feature), the chartplotter mode and collapsed dashboard settings are respected. No special configuration is required.
 
----
 
 ## Performance & Resource Notes
 - The persistent chart consumes GPU/CPU continuously; on very low‑power hardware consider disabling Chartplotter Mode for purely data dashboards.
@@ -91,7 +81,6 @@ When another KIP instance changes your active dashboard (Remote Control feature)
 - Avoid unnecessary high‑frequency (sub‑500 ms) widget sampling if chart responsiveness matters.
 - Keep embedded iframes (Embed widget) minimal when running persistent chart + heavy datasets.
 
----
 
 ## Troubleshooting
 | Issue | Possible Cause | Fix |
@@ -102,7 +91,6 @@ When another KIP instance changes your active dashboard (Remote Control feature)
 | Freeboard‑SK widget shows duplicate chart | Legacy widget still on a dashboard | Remove the Freeboard‑SK widget when using Chartplotter Mode |
 | Performance feels sluggish | High widget sampling or heavy embeds | Increase sample times, remove unused widgets, collapse non‑nav dashboards, investigate hardware resource consumption |
 
----
 
 ## FAQs
 **Does the chart keep its zoom and layers when collapsed dashboards are shown?**  Yes. The panel is hidden, not destroyed.
@@ -115,7 +103,6 @@ When another KIP instance changes your active dashboard (Remote Control feature)
 
 **Will remote control commands interrupt a resize session?**  If remote switching occurs mid‑edit, the Drag resize session ends when you Save or Cancel; uncommitted changes do not apply until you explicitly save.
 
----
 
 ## Related Help
 - Dashboards and Layout

package/public/assets/help-docs/community.md

@@ -17,7 +17,6 @@ Curated videos created by community members. Ordered to highlight broad onboardi
 
 Improve or add entries: PR or Discord #showcase.
 
----
 
 ## Authors & Channels
 Creator channels producing helpful KIP or Signal K related content.
@@ -53,7 +52,6 @@ Open a PR or post in Discord #showcase with:
 - Focus summary (1 line)
 - One featured video (link + short purpose sentence)
 
----
 
 ## More Community Resources
 
@@ -63,6 +61,5 @@ Open a PR or post in Discord #showcase with:
 - [SensESP](https://signalk.org/SensESP/) — A Signal K sensor development toolkit for the ESP32 platform
 - [OpenMarine Community](https://openmarine.net/) — OpenPlotter, MacArthur HAT and open source marine tech
 
----
 
 > Want to contribute a video or resource? Share your link in the Discord #showcase channel or open a GitHub issue!

package/public/assets/help-docs/configuration.md

@@ -19,7 +19,7 @@ To log in to Signal K, you must first create a user. Follow these steps to creat
 
 ## Login to Server Mode
 
-*In this mode, your configuration is shared across all devices **as long as you authenticate to Signal K using the same User ID**. It's that simple!*
+>In this mode, your configuration is shared across all devices **as long as you authenticate to Signal K using the same User ID**. It's that simple!
 
 On the **Configurations** page, you can perform the following actions:
 

package/public/assets/help-docs/contact-us.md

@@ -6,7 +6,6 @@ We’d love to hear from you. The KIP community is active and friendly—whether
 
 Use Discord for quick questions, sharing dashboards, comparing hardware setups, and learning how others integrate KIP with Signal K.
 
----
 
 ## When to Use GitHub Issues
 
@@ -42,7 +41,6 @@ Tell us:
 
 If you’re willing to help test or prototype—say so. That speeds things up.
 
----
 
 ## Response Expectations
 - Discord: often same-day community responses; core maintainer availability may vary.
@@ -51,14 +49,12 @@ If you’re willing to help test or prototype—say so. That speeds things up.
 
 If something critical slips through, feel free to politely bump the issue after about a week.
 
----
 
 ## Contributing Beyond Issues
 - Share dashboards, layouts, or usage patterns. Use the Discord #showcase chanel with a few pictures (great inspiration for others!).
 - Help answer other users’ questions on Discord.
 - Test new widgets or configuration flows and give feedback.
 
----
 
 ## Thank You
 Your feedback, curiosity, and ideas directly shape KIP. Whether it’s a tiny typo fix or a major feature concept—every contribution moves the project forward.