signalk-tides 1.2.0 → 1.2.1

package/dist/index.js

@@ -0,0 +1,153 @@
+"use strict";
+/*
+ * Copyright 2017 Scott Bender <scott@scottbender.net> and Joachim Bakke
+ * Copyright 2025 Brandon Keepers <brandon@opensoul.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const noaa_js_1 = __importDefault(require("./sources/noaa.js"));
+const stormglass_js_1 = __importDefault(require("./sources/stormglass.js"));
+const worldtides_js_1 = __importDefault(require("./sources/worldtides.js"));
+module.exports = function (app) {
+    // Interval to update tide data
+    const defaultPeriod = 60; // 1 hour
+    let unsubscribes = [];
+    const sources = [
+        (0, noaa_js_1.default)(app),
+        (0, stormglass_js_1.default)(app),
+        (0, worldtides_js_1.default)(app),
+    ];
+    const plugin = {
+        id: "tides",
+        name: "Tides",
+        // @ts-expect-error: TODO[TS]: fix Plugin type upstream
+        description: "Tidal predictions for the vessel's position from various online sources.",
+        schema: () => ({
+            title: "Tides API",
+            type: "object",
+            properties: {
+                source: {
+                    title: "Data source",
+                    type: "string",
+                    "anyOf": sources.map(({ id, title }) => ({
+                        const: id,
+                        title
+                    })),
+                    default: sources[0].id,
+                },
+                // Update plugin schema with sources
+                ...sources.reduce((properties, source) => Object.assign(properties, source.properties ?? {}), {}),
+                period: {
+                    title: "Update frequency",
+                    type: "number",
+                    description: "How often to update tide data (minutes)",
+                    default: 60,
+                    minimum: 1,
+                },
+            }
+        }),
+        stop() {
+            unsubscribes.forEach((f) => f());
+            unsubscribes = [];
+        }
+    };
+    plugin.start = async function (props) {
+        app.debug("Starting tides-api: " + JSON.stringify(props));
+        // Use the selected source, or the first one if not specified
+        const source = sources.find(source => source.id === props.source) || sources[0];
+        // Load the selected source
+        const provider = await source.start(props);
+        // Register the source as a resource provider
+        app.registerResourceProvider({
+            type: "tides",
+            methods: {
+                async listResources(query) {
+                    return provider(query);
+                },
+                getResource() {
+                    throw new Error("Not implemented");
+                },
+                setResource() {
+                    throw new Error("Not implemented");
+                },
+                deleteResource() {
+                    throw new Error("Not implemented");
+                }
+            }
+        });
+        app.subscriptionmanager.subscribe({
+            context: "vessels." + app.selfId,
+            subscribe: [
+                {
+                    path: "navigation.position",
+                    period: (props.period ?? defaultPeriod) * 60 * 1000,
+                    policy: "fixed",
+                },
+            ],
+        }, unsubscribes, (subscriptionError) => {
+            app.error("Error:" + subscriptionError);
+        }, (delta) => {
+            // @ts-expect-error: TODO[TS]: fix Delta type upstream
+            delta.updates.forEach(({ values }) => {
+                // @ts-expect-error: TODO[TS]: fix Delta type upstream
+                values.forEach(({ path }) => {
+                    if (path === "navigation.position") {
+                        performUpdate();
+                    }
+                });
+            });
+        });
+        async function performUpdate() {
+            try {
+                const { extremes } = await provider();
+                // Use server date, or current date if not available
+                const now = new Date(app.getSelfPath("navigation.datetime.value") ?? Date.now());
+                const nextTide = {};
+                extremes.forEach(({ type, value, time }) => {
+                    // Get the first tide of this type after now
+                    if (!nextTide[type] && new Date(time) > now) {
+                        nextTide[type] = { time, value };
+                    }
+                });
+                const delta = {
+                    context: "vessels." + app.selfId,
+                    updates: [
+                        {
+                            timestamp: now.toISOString(),
+                            values: Object.entries(nextTide).flatMap(([type, { time, value }]) => {
+                                return [
+                                    { path: `environment.tide.height${type}`, value: value },
+                                    { path: `environment.tide.time${type}`, value: time },
+                                ];
+                            }),
+                        },
+                    ],
+                };
+                app.debug("Sending delta: " + JSON.stringify(delta));
+                app.handleMessage(plugin.id, delta);
+                app.setPluginStatus("Updated tide data");
+            }
+            catch (e) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                app.setPluginError(e.message);
+                // @ts-expect-error: TODO[TS] this accepts more than just a string: https://github.com/bkeepers/signalk-server/blob/d6845ee1f915e6b729d66d2b08b15dc2e0da8e51/src/interfaces/plugins.ts#L517-L519
+                app.error(e);
+            }
+        }
+        // Perform initial update on startup
+        performUpdate();
+    };
+    return plugin;
+};

package/dist/sources/noaa.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("fs/promises"));
+const geolib_1 = require("geolib");
+const moment_1 = __importDefault(require("moment"));
+const stationsUrl = `https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json?type=tidepredictions`;
+const dataGetterUrl = 'https://api.tidesandcurrents.noaa.gov/api/prod/datagetter';
+const datum = 'MLLW';
+function default_1(app) {
+    return {
+        id: 'noaa',
+        title: 'NOAA (US only)',
+        async start() {
+            const stations = await StationList.load(app);
+            return async ({ date } = {}) => {
+                const position = app.getSelfPath("navigation.position.value");
+                if (!position)
+                    throw new Error("no position");
+                const station = stations.closestTo(position);
+                const endpoint = new URL(dataGetterUrl);
+                endpoint.search = new URLSearchParams({
+                    product: "predictions",
+                    application: "signalk.org/node-server",
+                    begin_date: (0, moment_1.default)(date).format("YYYYMMDD"),
+                    end_date: (0, moment_1.default)(date).add(7, "days").format("YYYYMMDD"),
+                    datum,
+                    station: station.id,
+                    time_zone: "gmt",
+                    units: "metric",
+                    interval: "hilo",
+                    format: "json",
+                }).toString();
+                app.debug(`Fetching tides from NOAA: ${endpoint}`);
+                try {
+                    const res = await fetch(endpoint.toString());
+                    if (!res.ok)
+                        throw new Error("Failed to fetch NOAA tides: " + res.statusText);
+                    const body = await res.json();
+                    app.debug("NOAA response: \n" + JSON.stringify(body, null, 2));
+                    if (body.error)
+                        throw new Error(body.error.message);
+                    return {
+                        station: {
+                            name: station.name,
+                            position: {
+                                latitude: station.lat,
+                                longitude: station.lng,
+                            },
+                        },
+                        extremes: body.predictions.map(({ t, v, type }) => ({
+                            type: type === "H" ? "High" : "Low",
+                            value: Number(v),
+                            time: new Date(`${t}Z`).toISOString(),
+                        })),
+                    };
+                }
+                catch (err) {
+                    app.setPluginError(`Failed to fetch NOAA tides: ${err}`);
+                    // @ts-expect-error: app.error should accept more than just a string
+                    app.error(err);
+                    throw err;
+                }
+            };
+        }
+    };
+}
+;
+class StationList extends Map {
+    static async load(app) {
+        const filename = path_1.default.join(app.config.configPath, "noaastations.json");
+        let data;
+        try {
+            data = JSON.parse(await promises_1.default.readFile(filename, 'utf-8'));
+            app.debug("NOAA: Loaded cached tide stations from " + filename);
+        }
+        catch (e) {
+            app.debug(`NOAA: failed to load cached tide stations: ${e}`);
+            app.debug('NOAA: Downloading tide stations');
+            const res = await fetch(stationsUrl);
+            if (!res.ok)
+                throw new Error(`Failed to download stations: ${res.statusText}`);
+            data = await res.json();
+            await promises_1.default.writeFile(filename, JSON.stringify(data));
+        }
+        return new this(data.stations);
+    }
+    constructor(data) {
+        super(data.map((station) => [station.id, station]));
+    }
+    closestTo(position) {
+        return this.near(position, 1)[0];
+    }
+    near(position, limit = 10) {
+        const stationsWithDistances = Array.from(this.values()).map((station) => ({
+            ...station,
+            distance: (0, geolib_1.getDistance)(position, { latitude: station.lat, longitude: station.lng })
+        }));
+        return stationsWithDistances.sort((a, b) => a.distance - b.distance).slice(0, limit);
+    }
+}

package/dist/sources/stormglass.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const moment_1 = __importDefault(require("moment"));
+function default_1(app) {
+    return {
+        id: 'stormglass',
+        title: 'StormGlass.io',
+        properties: {
+            stormglassApiKey: {
+                type: 'string',
+                title: 'StormGlass.io API key'
+            }
+        },
+        start({ stormglassApiKey } = {}) {
+            app.debug("Using StormGlass.io API");
+            return async (params = {}) => {
+                const { date = (0, moment_1.default)().subtract(1, "days").toISOString() } = params;
+                const endPoint = new URL("https://api.stormglass.io/v2/tide/extremes/point");
+                const position = app.getSelfPath("navigation.position.value");
+                if (!position)
+                    throw new Error("no position");
+                endPoint.search = new URLSearchParams({
+                    start: (0, moment_1.default)(date).format("YYYY-MM-DD"),
+                    end: (0, moment_1.default)(date).add(7, "days").format("YYYY-MM-DD"),
+                    // datum: "CD",
+                    lat: position.latitude,
+                    lng: position.longitude,
+                }).toString();
+                app.debug("Fetching StormGlass.io: " + endPoint.toString());
+                const res = await fetch(endPoint, {
+                    headers: { Authorization: stormglassApiKey ?? '' },
+                });
+                if (!res.ok)
+                    throw new Error('Failed to fetch StormGlass.io: ' + res.statusText);
+                const data = await res.json();
+                app.debug(JSON.stringify(data, null, 2));
+                return {
+                    station: {
+                        name: data.meta.station.name,
+                        position: {
+                            latitude: data.meta.station.lat,
+                            longitude: data.meta.station.lng,
+                        },
+                    },
+                    extremes: data.data.map(({ type, time, height }) => {
+                        return {
+                            type: type === "high" ? "High" : "Low",
+                            value: height,
+                            time: new Date(time).toISOString(),
+                        };
+                    }),
+                };
+            };
+        }
+    };
+}

package/dist/sources/worldtides.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const moment_1 = __importDefault(require("moment"));
+function default_1(app) {
+    return {
+        id: 'WorldTides.info',
+        title: 'worldtides.info',
+        properties: {
+            worldtidesApiKey: {
+                type: 'string',
+                title: 'worldtides.info API key'
+            }
+        },
+        start({ worldtidesApiKey = '' } = {}) {
+            app.debug("Using WorldTides API");
+            return async (params = {}) => {
+                const { date = (0, moment_1.default)().subtract(1, "days") } = params;
+                const endPoint = new URL("https://www.worldtides.info/api/v3");
+                const position = app.getSelfPath("navigation.position.value");
+                if (!position)
+                    throw new Error("no position");
+                endPoint.search = new URLSearchParams({
+                    date: (0, moment_1.default)(date).format("YYYY-MM-DD"),
+                    datum: "CD",
+                    days: "7",
+                    extremes: "true",
+                    key: worldtidesApiKey,
+                    lat: position.latitude,
+                    lon: position.longitude,
+                }).toString();
+                app.debug("Fetching worldtides: " + endPoint.toString());
+                const res = await fetch(endPoint);
+                if (!res.ok)
+                    throw new Error('Failed to fetch worldtides: ' + res.statusText);
+                const data = await res.json();
+                app.debug(JSON.stringify(data, null, 2));
+                if (data.status != 200)
+                    throw new Error("worldtides data: " + data.error ? data.error : "none");
+                return {
+                    station: {
+                        name: "WorldTides",
+                        position: {
+                            latitude: data.responseLat,
+                            longitude: data.responseLon,
+                        },
+                    },
+                    extremes: data.extremes.map(({ type, dt, height }) => {
+                        return {
+                            type,
+                            value: height,
+                            time: new Date(dt * 1000).toISOString(),
+                        };
+                    }),
+                };
+            };
+        }
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-tides",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Tidal predictions for the vessel's position from various online sources.",
   "main": "./dist/index.js",
   "scripts": {