@sailingnaturali/signalk-currents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @sailingnaturali/signalk-currents
+
+A generic [SignalK](https://signalk.org/) server plugin that fetches tidal-current
+predictions from the **CHS** (Canadian Hydrographic Service) and **NOAA** tides &
+currents APIs for a configured list of current stations, and:
+
+- publishes **`environment.current`** — the interpolated current (`drift` in m/s,
+  `setTrue` in radians) at the vessel, using the nearest configured station; and
+- serves a **`/currents`** resource — the full slack / flood / ebb event series for
+  every configured station.
+
+There are **no hardcoded stations or gates** — the station list is plugin config, so
+it works anywhere CHS or NOAA publishes current predictions.
+
+## How it works
+
+On start, and then every `pollMinutes`, the plugin:
+
+1. Fetches each station's events for the next `horizonDays` UTC days (one fetch per
+   station-day, cached in memory — per-day predictions are immutable).
+2. Reads the vessel position (`navigation.position`), picks the nearest configured
+   station, interpolates the current for "now", and publishes an `environment.current`
+   delta.
+3. Keeps the per-station event series available at `/currents`.
+
+Interpolation is a quarter-sine model between each slack (speed 0) and the adjacent
+flood/ebb maximum: ramping up uses `Vmax·sin(π/2·frac)`, ramping down uses
+`Vmax·cos(π/2·frac)`. `setTrue` is the extremum's configured direction (`floodDir`
+when flooding, `ebbDir` when ebbing).
+
+## Configuration
+
+Configured from the SignalK server plugin UI.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `stations` | array | `[]` | Current stations (see below). |
+| `horizonDays` | number | `3` | How many UTC days of predictions to fetch/keep. |
+| `pollMinutes` | number | `60` | How often to refresh and republish. |
+
+Each entry in `stations`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `provider` | `"chs"` \| `"noaa"` | Prediction source. |
+| `stationId` | string | CHS station id, or NOAA station id (e.g. `PUG1717`). |
+| `noaaBin` | number | NOAA current-station bin (NOAA only). |
+| `label` | string | Human-readable name. |
+| `lat` / `lon` | number | Station position (used for nearest-station selection). |
+| `floodDir` | number | Set direction (°true) while flooding. |
+| `ebbDir` | number | Set direction (°true) while ebbing. |
+
+### Example station config
+
+Gillard Passage (CHS) and Boundary Pass (NOAA), drawn from our
+[`tide-mcp`](https://github.com/sailingnaturali) passage database:
+
+```json
+{
+  "stations": [
+    {
+      "provider": "chs",
+      "stationId": "5dd3064fe0fdc4b9b4be6978",
+      "label": "Gillard Passage",
+      "lat": 50.3933,
+      "lon": -125.1567,
+      "floodDir": 160,
+      "ebbDir": 340
+    },
+    {
+      "provider": "noaa",
+      "stationId": "PUG1717",
+      "noaaBin": 35,
+      "label": "Boundary Pass",
+      "lat": 48.6912,
+      "lon": -123.2450,
+      "floodDir": 110,
+      "ebbDir": 290
+    }
+  ],
+  "horizonDays": 3,
+  "pollMinutes": 60
+}
+```
+
+`floodDir` / `ebbDir` are the set (°true) you observe at the station on the flood and
+ebb — fill them from a current atlas or pilot book for your stations.
+
+## Output
+
+### `environment.current` (delta)
+
+```json
+{ "drift": 1.23, "setTrue": 2.79 }
+```
+
+- `drift` — current speed in **m/s**.
+- `setTrue` — direction the current sets **toward**, in **radians true**.
+
+### `/currents` resource
+
+Mounted at `/plugins/signalk-currents/currents`:
+
+```json
+{
+  "stations": [
+    {
+      "stationId": "5dd3064fe0fdc4b9b4be6978",
+      "label": "Gillard Passage",
+      "lat": 50.3933,
+      "lon": -125.1567,
+      "events": [
+        { "utc": "2026-06-06T04:14:00.000Z", "kind": "slack", "speedKn": 0 },
+        { "utc": "2026-06-06T05:40:00.000Z", "kind": "flood", "speedKn": 4.1 }
+      ]
+    }
+  ]
+}
+```
+
+`kind` is `slack` | `flood` | `ebb`; `speedKn` is the event speed magnitude in knots.
+
+## Development
+
+```bash
+npm install
+npm test      # vitest
+npm run build # tsc -> dist/
+```
+
+## License
+
+MIT © 2026 Bryan Clark

package/dist/cache.d.ts

@@ -0,0 +1,3 @@
+import { CurrentEvent } from './types';
+export type DayCache = Map<string, CurrentEvent[]>;
+export declare function createCache(): DayCache;

package/dist/cache.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCache = createCache;
+function createCache() {
+    return new Map();
+}

package/dist/calculations.d.ts

@@ -0,0 +1,7 @@
+import { CurrentEvent, StationConfig } from './types';
+export declare function nearestStation(lat: number, lon: number, stations: StationConfig[]): StationConfig | undefined;
+export interface CurrentValue {
+    drift: number;
+    setTrue: number;
+}
+export declare function interpolateCurrent(now: Date, events: CurrentEvent[], station: StationConfig): CurrentValue | undefined;

package/dist/calculations.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nearestStation = nearestStation;
+exports.interpolateCurrent = interpolateCurrent;
+const geolib_1 = require("geolib");
+function nearestStation(lat, lon, stations) {
+    if (stations.length === 0)
+        return undefined;
+    return stations.reduce((best, s) => (0, geolib_1.getDistance)({ latitude: lat, longitude: lon }, { latitude: s.lat, longitude: s.lon }) <
+        (0, geolib_1.getDistance)({ latitude: lat, longitude: lon }, { latitude: best.lat, longitude: best.lon })
+        ? s : best);
+}
+const KN_TO_MS = 0.514444;
+function interpolateCurrent(now, events, station) {
+    const t = now.getTime();
+    // bracketing consecutive pair e0 <= t <= e1
+    let e0, e1;
+    for (let i = 0; i < events.length - 1; i++) {
+        if (Date.parse(events[i].utc) <= t && t <= Date.parse(events[i + 1].utc)) {
+            e0 = events[i];
+            e1 = events[i + 1];
+            break;
+        }
+    }
+    if (!e0 || !e1)
+        return undefined;
+    const frac = (t - Date.parse(e0.utc)) / (Date.parse(e1.utc) - Date.parse(e0.utc));
+    let speedKn;
+    let extremum;
+    if (e0.kind === 'slack') {
+        speedKn = e1.speedKn * Math.sin((Math.PI / 2) * frac);
+        extremum = e1;
+    }
+    else if (e1.kind === 'slack') {
+        speedKn = e0.speedKn * Math.cos((Math.PI / 2) * frac);
+        extremum = e0;
+    }
+    else {
+        speedKn = e0.speedKn + (e1.speedKn - e0.speedKn) * frac;
+        extremum = e0;
+    } // rare flood↔ebb, linear
+    const dir = extremum.kind === 'ebb' ? station.ebbDir : station.floodDir;
+    return { drift: speedKn * KN_TO_MS, setTrue: (dir * Math.PI) / 180 };
+}

package/dist/fetch.d.ts

@@ -0,0 +1,4 @@
+import { CurrentEvent, StationConfig } from './types';
+type DayFetcher = (s: StationConfig, dayStart: Date, dayEnd: Date) => Promise<CurrentEvent[]>;
+export declare function stationEvents(station: StationConfig, start: Date, horizonDays: number, cache: Map<string, CurrentEvent[]>, fetcher?: DayFetcher): Promise<CurrentEvent[]>;
+export {};

package/dist/fetch.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stationEvents = stationEvents;
+const chs_1 = require("./sources/chs");
+const noaa_1 = require("./sources/noaa");
+const defaultFetcher = (s, a, b) => s.provider === 'chs'
+    ? (0, chs_1.fetchChsEvents)(s.stationId, a, b)
+    : (0, noaa_1.fetchNoaaEvents)(s.stationId, s.noaaBin ?? 0, a, b);
+function utcDays(start, n) {
+    const base = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
+    return Array.from({ length: n }, (_, i) => new Date(base.getTime() + i * 86400000).toISOString().slice(0, 10));
+}
+async function stationEvents(station, start, horizonDays, cache, fetcher = defaultFetcher) {
+    const out = [];
+    for (const day of utcDays(start, horizonDays)) {
+        const key = `${station.provider}:${station.stationId}:${day}`;
+        let events = cache.get(key);
+        if (!events) {
+            const dayStart = new Date(`${day}T00:00:00Z`);
+            const dayEnd = new Date(dayStart.getTime() + 86400000);
+            events = await fetcher(station, dayStart, dayEnd);
+            cache.set(key, events);
+        }
+        out.push(...events);
+    }
+    out.sort((a, b) => a.utc.localeCompare(b.utc));
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin, ServerAPI } from '@signalk/server-api';
+declare const _default: (app: ServerAPI) => Plugin;
+export = _default;

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+const cache_1 = require("./cache");
+const fetch_1 = require("./fetch");
+const calculations_1 = require("./calculations");
+const routes_1 = require("./routes");
+module.exports = function (app) {
+    // Cache of per-day events keyed by `provider:station:YYYY-MM-DD`, and the
+    // current per-station series exposed via /currents. Both live for the
+    // lifetime of the plugin process and are read by the route handler.
+    const cache = (0, cache_1.createCache)();
+    const series = new Map();
+    let timer;
+    const plugin = {
+        id: 'signalk-currents',
+        name: 'Tidal currents (CHS/NOAA)',
+        description: 'Publishes tidal-current predictions to environment.current and a /currents resource.',
+        schema: {
+            type: 'object',
+            properties: {
+                stations: {
+                    type: 'array', title: 'Current stations',
+                    items: { type: 'object', required: ['provider', 'stationId', 'label', 'lat', 'lon', 'floodDir', 'ebbDir'],
+                        properties: {
+                            provider: { type: 'string', enum: ['chs', 'noaa'] },
+                            stationId: { type: 'string' }, noaaBin: { type: 'number' },
+                            label: { type: 'string' }, lat: { type: 'number' }, lon: { type: 'number' },
+                            floodDir: { type: 'number', title: 'Flood set (°true)' },
+                            ebbDir: { type: 'number', title: 'Ebb set (°true)' },
+                        } },
+                },
+                horizonDays: { type: 'number', default: 3 },
+                pollMinutes: { type: 'number', default: 60 },
+            },
+        },
+        start(options) {
+            const stations = options.stations ?? [];
+            const horizonDays = options.horizonDays ?? 3;
+            const pollMinutes = options.pollMinutes ?? 60;
+            async function refresh() {
+                try {
+                    const now = new Date();
+                    // Refresh each station's series from the cached day fetch. Isolate
+                    // per-station failures so one bad CHS/NOAA response can't blank the
+                    // others (or skip the environment.current publish) for the whole cycle.
+                    for (const station of stations) {
+                        try {
+                            const events = await (0, fetch_1.stationEvents)(station, now, horizonDays, cache);
+                            series.set(station.stationId, { station, events });
+                        }
+                        catch (e) {
+                            app.error(`station ${station.label} fetch failed: ${e.message}`);
+                        }
+                    }
+                    // Read the vessel's position (mirrors signalk-tides: reads the
+                    // `.value` of navigation.position via getSelfPath).
+                    const position = app.getSelfPath('navigation.position.value');
+                    if (!position) {
+                        app.debug('No position available; skipping environment.current publish');
+                        app.setPluginStatus(`Fetched ${series.size} station(s); awaiting position`);
+                        return;
+                    }
+                    const station = (0, calculations_1.nearestStation)(position.latitude, position.longitude, stations);
+                    const entry = station ? series.get(station.stationId) : undefined;
+                    if (!station || !entry) {
+                        app.setPluginStatus('No station near vessel position');
+                        return;
+                    }
+                    const current = (0, calculations_1.interpolateCurrent)(now, entry.events, station);
+                    if (!current) {
+                        app.setPluginStatus(`No current data bracketing now for ${station.label}`);
+                        return;
+                    }
+                    // Publish environment.current as a SignalK delta. handleMessage takes
+                    // a Partial<Delta>; the path is a branded type so it is cast.
+                    app.handleMessage(plugin.id, {
+                        updates: [
+                            {
+                                values: [
+                                    {
+                                        path: 'environment.current',
+                                        value: { drift: current.drift, setTrue: current.setTrue },
+                                    },
+                                ],
+                            },
+                        ],
+                    });
+                    app.setPluginStatus(`environment.current from ${station.label}: ${current.drift.toFixed(2)} m/s`);
+                }
+                catch (e) {
+                    // One bad cycle must never kill the loop.
+                    app.error(`refresh failed: ${e.message}`);
+                    app.setPluginError(e.message);
+                }
+            }
+            // Initial fetch, then poll. Errors are swallowed inside refresh().
+            refresh();
+            timer = setInterval(refresh, pollMinutes * 60_000);
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        },
+        // Mounted by the server at /plugins/signalk-currents — so the resource is
+        // served at /plugins/signalk-currents/currents. This is the typed
+        // equivalent of the express-router mounting signalk-tides does via an
+        // app.use() cast; registerWithRouter is the supported Plugin API.
+        registerWithRouter(router) {
+            router.use('/', (0, routes_1.currentsRouter)(() => series));
+        },
+    };
+    return plugin;
+};

package/dist/routes.d.ts

@@ -0,0 +1,16 @@
+import { Router } from 'express';
+import { StationConfig, CurrentEvent } from './types';
+export interface StationSeries {
+    station: StationConfig;
+    events: CurrentEvent[];
+}
+export declare function currentsPayload(series: Map<string, StationSeries>): {
+    stations: {
+        stationId: string;
+        label: string;
+        lat: number;
+        lon: number;
+        events: CurrentEvent[];
+    }[];
+};
+export declare function currentsRouter(getSeries: () => Map<string, StationSeries>): Router;

package/dist/routes.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentsPayload = currentsPayload;
+exports.currentsRouter = currentsRouter;
+const express_1 = require("express");
+function currentsPayload(series) {
+    return {
+        stations: [...series.values()].map(s => ({
+            stationId: s.station.stationId, label: s.station.label,
+            lat: s.station.lat, lon: s.station.lon, events: s.events,
+        })),
+    };
+}
+// Mirror signalk-tides/src/routes.ts for how the router is registered with `app`.
+function currentsRouter(getSeries) {
+    const r = (0, express_1.Router)();
+    r.get('/currents', (_req, res) => res.json(currentsPayload(getSeries())));
+    return r;
+}

package/dist/sources/chs.d.ts

@@ -0,0 +1,2 @@
+import { CurrentEvent } from '../types';
+export declare function fetchChsEvents(stationId: string, start: Date, end: Date, fetchFn?: typeof fetch): Promise<CurrentEvent[]>;

package/dist/sources/chs.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchChsEvents = fetchChsEvents;
+const types_1 = require("../types");
+const CHS_BASE = 'https://api-sine.dfo-mpo.gc.ca/api/v1';
+const KIND = {
+    SLACK: 'slack', EXTREMA_FLOOD: 'flood', EXTREMA_EBB: 'ebb',
+};
+const isoZ = (d) => d.toISOString().replace(/\.\d{3}Z$/, 'Z');
+async function fetchChsEvents(stationId, start, end, fetchFn = fetch) {
+    const params = new URLSearchParams({
+        'time-series-code': 'wcp1-events', from: isoZ(start), to: isoZ(end),
+    });
+    const resp = await fetchFn(`${CHS_BASE}/stations/${stationId}/data?${params}`);
+    if (!resp.ok)
+        throw new Error(`CHS ${resp.status}`);
+    const out = [];
+    for (const row of await resp.json()) {
+        const kind = KIND[row.qualifier];
+        if (!kind)
+            continue;
+        out.push((0, types_1.eventFromParts)(row.eventDate, kind, parseFloat(row.value)));
+    }
+    return out;
+}

package/dist/sources/noaa.d.ts

@@ -0,0 +1,2 @@
+import { CurrentEvent } from '../types';
+export declare function fetchNoaaEvents(stationId: string, bin: number, start: Date, end: Date, fetchFn?: typeof fetch): Promise<CurrentEvent[]>;

package/dist/sources/noaa.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNoaaEvents = fetchNoaaEvents;
+const types_1 = require("../types");
+const NOAA_BASE = 'https://api.tidesandcurrents.noaa.gov/api/prod/datagetter';
+const ymd = (d) => d.toISOString().slice(0, 10).replace(/-/g, '');
+// NOAA "YYYY-MM-DD HH:MM" is UTC when requested with time_zone=gmt.
+function parseNoaaTime(s) {
+    return new Date(s.replace(' ', 'T') + 'Z').toISOString();
+}
+async function fetchNoaaEvents(stationId, bin, start, end, fetchFn = fetch) {
+    const params = new URLSearchParams({
+        product: 'currents_predictions', interval: 'MAX_SLACK', time_zone: 'gmt',
+        units: 'english', format: 'json', application: 'signalk-currents',
+        station: stationId, bin: String(bin), begin_date: ymd(start), end_date: ymd(end),
+    });
+    const resp = await fetchFn(`${NOAA_BASE}?${params}`);
+    if (!resp.ok)
+        throw new Error(`NOAA ${resp.status}`);
+    const cp = (await resp.json())?.current_predictions?.cp ?? [];
+    const out = [];
+    for (const row of cp) {
+        const kind = String(row.Type ?? '').toLowerCase();
+        if (kind !== 'slack' && kind !== 'flood' && kind !== 'ebb')
+            continue;
+        out.push((0, types_1.eventFromParts)(parseNoaaTime(row.Time), kind, parseFloat(row.Velocity_Major)));
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export type CurrentKind = 'slack' | 'flood' | 'ebb';
+export interface CurrentEvent {
+    utc: string;
+    kind: CurrentKind;
+    speedKn: number;
+}
+export interface StationConfig {
+    provider: 'chs' | 'noaa';
+    stationId: string;
+    noaaBin?: number;
+    label: string;
+    lat: number;
+    lon: number;
+    floodDir: number;
+    ebbDir: number;
+}
+export declare function eventFromParts(utc: string, kind: CurrentKind, speed: number): CurrentEvent;

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventFromParts = eventFromParts;
+function eventFromParts(utc, kind, speed) {
+    return { utc: new Date(utc).toISOString(), kind, speedKn: Math.abs(speed) };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sailingnaturali/signalk-currents",
+  "version": "0.1.0",
+  "description": "Publish CHS/NOAA tidal-current predictions to SignalK — environment.current + a /currents resource, for a configured station list.",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "keywords": ["signalk-node-server-plugin", "signalk-category-utility", "tidal-currents", "currents", "marine"],
+  "author": "Bryan Clark",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailingnaturali/signalk-currents.git"
+  },
+  "homepage": "https://github.com/sailingnaturali/signalk-currents#readme",
+  "bugs": {
+    "url": "https://github.com/sailingnaturali/signalk-currents/issues"
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@signalk/server-api": "^2.0.0",
+    "express": "^4.19.0",
+    "geolib": "^3.3.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0",
+    "@types/express": "^4.17.0"
+  }
+}