sailkick-boat 0.13.4

package/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 sailkick
+
+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 the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies, subject to the
+above copyright notice and this permission notice being included in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -0,0 +1,197 @@
+# sailkick-boat
+
+> ## ⚠️ Project status: early alpha — no public service yet
+>
+> This plugin is the **boat-side companion of the sailkick platform** (a self-hosted
+> 3D sailing app + a central telemetry sync server). **That platform is not publicly
+> available yet** — there is no public cloud endpoint to point this plugin at, and it
+> is currently developed and tested only against sailkick's own development
+> environment (a private LAN).
+>
+> It is published this early for development visibility and for adventurous
+> **self-hosters**: to use it today you must run your own sailkick app server and
+> central InfluxDB v2. Expect breaking changes while the version is 0.x. If you found
+> this in the Signal K Appstore and don't run a sailkick server, it will not do
+> anything useful yet — watch the repo for the public launch.
+
+One Signal K plugin, independently-toggleable modules — so the boat stays
+"just SignalK + plugins":
+
+- **`sync`** — gapless store-and-forward of self-vessel telemetry to InfluxDB v2
+  (durable spool; survives offline + restarts). Data **out**.
+- **`proxy`** — offline-first caching **mirror of the sailkick host**: fetch once
+  online, serve from disk forever (incl. offline). Data **in**.
+- served alongside the mirror, from the boat's **own** data (so the app uses the
+  same contracts as the cloud, offline-first):
+  - **`/ws/telemetry`** — the app's live telemetry bus, fed from local SignalK.
+  - **`/api/history/{series,track}`** — the app's Trends panel + track, served
+    from the boat's local InfluxDB (or a DB-less telemetry ring) — full local history.
+
+Kept as separate modules so a proxy fault can't wedge the data-critical sync path.
+
+## Proxy: how it works
+```
+laptop -> http://<boat>:3000/plugins/sailkick-boat/p/<anything>
+       -> on disk?  yes -> serve            [X-Sailkick-Cache: HIT]
+                    no  -> fetch <sailkickUrl>/<anything> -> store -> serve   [MISS]
+                    no + offline -> 504
+```
+Any content-type (tiles, JSON, app assets). Query strings cache separately.
+Open the sailkick app *through* the proxy and every relative URL it loads is
+cached automatically. `POST /plugins/sailkick-boat/prefetch` with
+`{"paths":[...]}` warms a region/app-shell ahead of a passage.
+
+## Cache freshness — pinned tiles, auto-refresh on new bakes
+Tiles are **pinned**: once cached they're served from disk forever (online or
+offline), never time-expired — so a big tile store never "goes slow." Freshness
+comes from the cloud **announcing bakes**, not from a clock:
+
+- The cloud publishes a small manifest (default `GET /api/cache-manifest`):
+  ```json
+  { "app": "2026-07-19a",
+    "bakes": { "tiles/osm-standard": "v3", "tiles/seamap": "2026-06", "terrain": "2026-01" } }
+  ```
+- The plugin polls it (only when online; a failed poll is a no-op). When a
+  dataset's id **changes**, files in that family older than the announcement are
+  refreshed **lazily** — refetched on next view when online (`X-Sailkick-Cache:
+  UPDATED`), served stale when offline (`STALE`). Untouched tiles never re-download.
+- First sight of a family does **not** invalidate — your pre-populated store is
+  trusted. Only genuine bake changes refresh anything.
+
+`X-Sailkick-Cache` reports `HIT` / `MISS` / `UPDATED` / `STALE` / `LIVE` per response.
+
+**Static vs dynamic — two strategies.** Tiles and app assets are **cache-first**
+(pinned, offline forever). Dynamic `/api/*` data (AIS, weather) is **network-first**:
+fetched live every time online (so AIS/weather never go stale), with the last
+response kept only as an **offline fallback** (`STALE`). Local `/api/history` and the
+patched `/api/config` are served specially (above).
+
+**Offline circuit breaker.** Some boat routers return errors (or hang) for outbound
+requests when the uplink is down, instead of failing cleanly. Once a fetch fails, the
+mirror marks the upstream down for a short cooldown and **fast-fails uncached
+requests** (no per-request timeout hang) — so a handful of uncached tiles can't
+starve the browser's ~6-connection pool and block the cached tiles. Cached `HIT`s are
+never affected; a single success clears the breaker.
+
+Manual force-refresh (no SSH):
+```
+POST /plugins/sailkick-boat/cache/clear                            # default keep: tiles,terrain,history
+POST /plugins/sailkick-boat/cache/clear?keep=tiles,terrain,history # refresh app shell; keep tiles + ring log
+POST /plugins/sailkick-boat/cache/clear?prefix=tiles/seamap        # nuke one tileset
+```
+(The persistent history ring log lives under `<storeDir>/history`, so keep `history`
+when clearing — the default keep already does. A hand-typed `find` clear should add
+`! -name history` alongside `! -name tiles ! -name terrain`.)
+
+## Offline map coverage — global base seed + region prefetch
+On-demand caching only holds what you browsed. To make a usable map exist offline
+*everywhere*, the plugin seeds a worldwide low-zoom base on start and lets you warm a
+passage area on demand.
+
+- **Global base seed** (default on): caches two worldwide layers, pinned forever —
+  **coastline** (sparse vector `.pbf`, parent-guided descent so it probes ~4× the real
+  tiles, not a full pyramid) and **seabed/bathy** (dense depth raster). Defaults
+  `coastlineMaxZoom 8` (~12k tiles) + `seabedMaxZoom 6` (~5.5k). Idempotent (re-runs
+  hit cache only) and self-throttling — it reuses the circuit breaker, so it goes quiet
+  offline and resumes when back online. Progress shows in the plugin status line.
+  Config: `proxy.seed.{enabled,coastlineMaxZoom,seabedMaxZoom,concurrency}`.
+- **Download around the boat** (settings dropdowns, no token) — the easiest way to
+  cache a passage area: in Plugin Config pick a **Radius around boat** (25/50/100/200 nm)
+  and a **Detail level** (Overview z12 … Harbor z15), then save. The plugin reads the
+  boat's current position from local SignalK, builds a box, and warms the chart layers
+  in the background (progress in the status line). Idempotent; re-saving tops up. An
+  oversized radius+detail is refused (reduce one). Config `proxy.prefetch.{radiusNm,detailZoom,concurrency}`.
+- **Region prefetch (API)** — for scripted/arbitrary boxes, warm the detailed chart layers for an area:
+  ```
+  POST /plugins/sailkick-boat/prefetch/region
+    { "bbox":[w,s,e,n], "minZoom":8, "maxZoom":15,
+      "layers":["osm-standard","bathy","seamap","coastline"] }
+  ```
+  Enumerates the bbox×zoom×layers rectangle and warms it. It **estimates first** and
+  refuses > 50k tiles unless you pass `"force":true` (so a huge box can't run away over
+  the link). Returns `{requested,cached,empty,failed}`.
+- **Empty tiles** (sparse coastline/seamap) are **negative-cached** (`.404` sentinel), so
+  offline they read as "empty" (404) exactly like online instead of stalling.
+
+Note: the app's **Coastline** and depth layers are default-off toggles — enable them in
+the app to see the seeded base.
+
+## No login on the boat (single-tenant)
+The cloud app gates behind a boat-account login (a `Secure` session cookie), which
+can't work over the boat's plain-HTTP offline mirror — the browser drops a `Secure`
+cookie on HTTP, so login just loops. Since the boat is single-tenant and its data
+endpoints aren't server-gated, the proxy serves `/api/config` with `auth.required`
+forced to `false` (and `historyAvailable` forced on when history is served locally),
+so the boat's own app opens with no password, fully offline. Everything else in the
+config passes through untouched. Toggle off with `proxy.openAccess: false` to keep
+the cloud login gate.
+
+## Local history (offline Trends + track)
+Two ways, chosen automatically:
+- **Read token set** → full history queried from a **local InfluxDB** (e.g. a bucket
+  written by `signalk-to-influxdb-v2`).
+- **No token, telemetry on** → a **DB-less ring** sampled from live telemetry (the
+  same BoatState feeding `/ws/telemetry`) — for boats with no local InfluxDB, e.g.
+  **SignalK on a Victron GX / Venus OS**. Same JSON contract, fully offline, no database.
+  (`historyAvailable` reports true either way, so the app shows the Trends panel.)
+  - **Persistent (append-log):** the ring is saved as a JSONL append-log at
+    `<storeDir>/history/history-ring.jsonl` (on the SSD/USB with the tiles; override with
+    `proxy.history.ringDir`), so it **survives restarts**. Each sample appends one line; the file is
+    compacted (atomic rewrite to the current window) only rarely, so a long passage
+    writes < ~1 GB (vs the ~600 GB a full-rewrite snapshot would). Config
+    `proxy.history.ringWindowSec` (default 24 h, up to 2 592 000 = 30 d),
+    `ringSampleSec` (auto-coarsened so the ring stays ≤ ~50 k samples at any window),
+    `ringPersist` (default on; off = in-memory only). NB: the app currently caps
+    history requests at 24 h — a >24 h window needs the app-side clamp raised too.
+
+The sailkick app is deployment-agnostic about history: *central Influx in the
+cloud, in-memory ring on a DB-less edge*. The boat is a third case — an edge that
+serves the app's history endpoints from its **own** data (local InfluxDB or the ring):
+```
+GET /api/history/series?window=3600s&every=30s -> { series: { sog|heading|tws|… : [[tMs,val],…] } }
+GET /api/history/track?window=3600s            -> { track: [{ t, lat, lon }, …] }
+```
+Same JSON the cloud returns, so the browser can't tell the difference — but it
+works **offline** with the boat's own data. Only when neither a local InfluxDB nor
+telemetry is available do these paths **fall through to the cloud mirror**, so an
+online boat is never worse off than before.
+
+## Easiest setup: log in with your sailkick account
+Instead of pasting InfluxDB URL / org / bucket / write-token, fill the **Sailkick
+account** section — **host URL + slug + password** — and the plugin fetches the rest of
+its cloud config on start (`POST <host>/api/boat/config`): the scoped write token,
+bucket, org, and InfluxDB URL for your boat. The bundle is cached (0600) in the plugin
+data dir, so sync keeps working **offline** after the first connect. Leave the account
+section blank to configure `sync`/`proxy` manually (advanced / self-hosted). Account
+values take precedence over the manual sync fields; the mirror upstream (`sailkickUrl`)
+is set from the account host.
+
+## Config (each section toggleable)
+- **Telemetry sync → InfluxDB**: `enabled`, `influxUrl`, `org`, `bucket`, `token`, `spoolDir`, …
+- **Sailkick caching proxy**: `enabled`, `sailkickUrl` (the one upstream), `storeDir`, …
+  - `serveTelemetry` (default on) — provide `/ws/telemetry` from local SignalK.
+  - **Cache manifest** (default on): `path` (default `/api/cache-manifest`),
+    `pollIntervalSec` (default 300) — auto-refresh datasets when the cloud
+    announces a new bake.
+  - **Local history** (default on): `influxUrl` (default `http://127.0.0.1:8086`),
+    `org`, `bucket`, `token` (a read token — set to serve full history from a local
+    InfluxDB; blank = the DB-less telemetry ring), plus the ring settings above.
+
+Point your chart app / browser at:
+`http://<boat>:3000/plugins/sailkick-boat/p/`
+
+## Install (like any Signal K plugin)
+```bash
+cd ~/.signalk && npm install sailkick-boat   # or a packed tarball
+```
+Enable + configure under **Server → Plugin Config → "Sailkick boat companion"**.
+Put `spoolDir`/`storeDir` on the SSD (or leave blank for the plugin data dir).
+
+## Dev / tests
+```bash
+npm install && npm test   # proxy: mirror/cache/offline + Express route; sync: subscribe+buffer
+```
+Supersedes the separate `signalk-to-influxdb-gapless` + `signalk-tile-cache` plugins.
+
+## License
+MIT

package/index.js

@@ -0,0 +1,252 @@
+'use strict'
+
+const { createSync } = require('./lib/sync')
+const { createProxy } = require('./lib/proxy')
+const { createTelemetry } = require('./lib/telemetry')
+const { createHistory } = require('./lib/history')
+const { resolveAccountConfig, accountConfigured } = require('./lib/account')
+
+// sailkick-boat: one Signal K plugin, two independently-toggleable modules —
+//   sync : gapless store-and-forward of self telemetry to InfluxDB (data OUT)
+//   proxy: offline-first caching mirror of the sailkick host (data IN)
+// Kept as separate modules so a proxy fault can't wedge the data-critical sync.
+
+module.exports = function (app) {
+  let sync = null
+  let proxy = null
+  let telemetry = null
+  let history = null
+  let statusTimer = null
+  let accountStatus = null
+
+  const plugin = {
+    id: 'sailkick-boat',
+    name: 'Sailkick boat companion',
+    description:
+      'Boat-side sailkick: gapless telemetry sync to InfluxDB + an offline-first ' +
+      'caching mirror of the sailkick host. Each feature can be toggled on/off.'
+  }
+
+  plugin.schema = {
+    type: 'object',
+    properties: {
+      account: {
+        type: 'object',
+        title: 'Sailkick account (auto-configure)',
+        description: 'Log in with your sailkick account and the plugin fetches its cloud config (write token, bucket, org, InfluxDB URL) automatically — no manual token entry. Leave blank to configure sync/mirror manually below. The last-good config is cached, so sync keeps working offline.',
+        properties: {
+          sailkickUrl: { type: 'string', title: 'Sailkick host URL', description: 'e.g. https://app.sailkick.com — used for login and as the mirror upstream.' },
+          slug: { type: 'string', title: 'Boat slug (username)' },
+          password: { type: 'string', title: 'Password' }
+        }
+      },
+      sync: {
+        type: 'object',
+        title: 'Telemetry sync → InfluxDB',
+        properties: {
+          enabled: { type: 'boolean', title: 'Enable telemetry sync', default: true },
+          influxUrl: { type: 'string', title: 'InfluxDB URL' },
+          org: { type: 'string', title: 'Organization', default: 'sailkick' },
+          bucket: { type: 'string', title: 'Bucket (your <slug>_raw)' },
+          token: { type: 'string', title: 'Write token (scoped to your bucket)' },
+          spoolDir: { type: 'string', title: 'Buffer directory', description: 'Default: plugin data dir. Put on the SSD.' },
+          batchSize: { type: 'number', title: 'Batch size (points/file)', default: 1000 },
+          flushIntervalMs: { type: 'number', title: 'Flush interval (ms)', default: 1000 },
+          maxBufferBytes: { type: 'number', title: 'Max on-disk buffer (bytes)', default: 524288000 },
+          subscribePeriodMs: { type: 'number', title: 'Min interval per path (ms)', default: 1000 },
+          requestTimeoutMs: { type: 'number', title: 'Upload timeout (ms)', default: 30000 },
+          retryMinMs: { type: 'number', title: 'Retry backoff min (ms)', default: 1000 },
+          retryMaxMs: { type: 'number', title: 'Retry backoff max (ms)', default: 60000 }
+        }
+      },
+      proxy: {
+        type: 'object',
+        title: 'Sailkick caching proxy',
+        properties: {
+          enabled: { type: 'boolean', title: 'Enable caching proxy', default: true },
+          serveTelemetry: { type: 'boolean', title: 'Serve /ws/telemetry from local SignalK', description: 'Provide the app\'s telemetry bus from the boat\'s SignalK, so the app uses the same contract as the cloud server.', default: true },
+          openAccess: { type: 'boolean', title: 'No login on the boat', description: 'Serve /api/config with the cloud login disabled, so the boat\'s own app opens without a password (single-tenant, offline-first). Turn off to keep the cloud login gate.', default: true },
+          sailkickUrl: { type: 'string', title: 'Sailkick host URL', description: 'The one upstream this boat mirrors (usually set automatically from the account section). e.g. https://app.sailkick.com' },
+          proxyPort: { type: 'number', title: 'Mirror server port', description: 'Standalone HTTP server serving the mirror at origin root (no SignalK auth). With host networking it is directly on the Pi. 0 = disable.', default: 8080 },
+          localSignalkUrl: { type: 'string', title: 'Local SignalK URL (live telemetry)', description: 'Live data + WebSocket stream are proxied here (not cached, not mirrored).', default: 'http://127.0.0.1:3000' },
+          localPaths: { type: 'array', title: 'Paths served by LOCAL SignalK', description: 'Prefixes routed to local SignalK instead of the mirror.', items: { type: 'string' }, default: ['/signalk'] },
+          storeDir: { type: 'string', title: 'Cache directory', description: 'Default: plugin data dir. Put on the SSD.' },
+          requestTimeoutMs: { type: 'number', title: 'Fetch timeout (ms)', default: 20000 },
+          manifest: {
+            type: 'object',
+            title: 'Auto-refresh on new bakes (cache manifest)',
+            description: 'Poll the cloud\'s bake manifest so tiles/app refresh lazily when a dataset is re-baked. Tiles are otherwise pinned (never expire by time).',
+            properties: {
+              enabled: { type: 'boolean', title: 'Poll the cache manifest', default: true },
+              path: { type: 'string', title: 'Manifest path on the sailkick host', default: '/api/cache-manifest' },
+              pollIntervalSec: { type: 'number', title: 'Poll interval (s)', default: 300 }
+            }
+          },
+          history: {
+            type: 'object',
+            title: 'Local history (app Trends panel + track)',
+            description: 'Serve the app\'s /api/history endpoints locally so trends + track work offline. With a read token → full history from a local InfluxDB. Without one → a DB-less ~1h ring sampled from live telemetry (e.g. SignalK on a Victron GX with no InfluxDB).',
+            properties: {
+              enabled: { type: 'boolean', title: 'Serve /api/history locally', default: true },
+              influxUrl: { type: 'string', title: 'Local InfluxDB URL', default: 'http://127.0.0.1:8086' },
+              org: { type: 'string', title: 'Organization', default: 'signalk' },
+              bucket: { type: 'string', title: 'Bucket', default: 'signalk' },
+              token: { type: 'string', title: 'Read token (scoped to the bucket)', description: 'Set to serve full history from a local InfluxDB. Leave blank to use the DB-less live-telemetry ring (Victron GX / no InfluxDB).' },
+              requestTimeoutMs: { type: 'number', title: 'Query timeout (ms)', default: 15000 },
+              ringPersist: { type: 'boolean', title: 'Persist the DB-less ring across restarts', description: 'Append-log in the plugin data dir. Off = in-memory only (lost on restart). Ignored when a token is set (InfluxDB is used).', default: true },
+              ringWindowSec: { type: 'number', title: 'DB-less ring window (s)', description: 'How much history the ring keeps: 86400 = 24h (default), up to 2592000 = 30d for long passages. Resolution auto-coarsens for large windows. NB: the app currently caps history requests at 24h.', default: 86400 },
+              ringSampleSec: { type: 'number', title: 'DB-less ring sample interval (s)', description: 'Auto-raised for large windows so the ring stays bounded (~50k samples).', default: 15 },
+              ringDir: { type: 'string', title: 'Ring log directory (override)', description: 'Where the persistent ring log lives. Default: a "history" folder under the cache directory (storeDir), so it sits on the SSD/USB with the tiles. Set to override.' }
+            }
+          },
+          seed: {
+            type: 'object',
+            title: 'Offline base seed (global coastline + seabed)',
+            description: 'On start, cache a worldwide low-zoom base so a usable map exists offline everywhere. Idempotent; self-throttles when offline. Enable the "Coastline"/depth layers in the app to see it.',
+            properties: {
+              enabled: { type: 'boolean', title: 'Seed the global base on start', default: true },
+              coastlineMaxZoom: { type: 'number', title: 'Coastline max zoom', description: 'Sparse vector coastline z0..N (z8 ≈ 12k tiles).', default: 8 },
+              seabedMaxZoom: { type: 'number', title: 'Seabed (bathy) max zoom', description: 'Dense depth raster z0..N (z6 ≈ 5.5k tiles).', default: 6 },
+              concurrency: { type: 'number', title: 'Parallel fetches', default: 4 }
+            }
+          },
+          prefetch: {
+            type: 'object',
+            title: 'Offline area download (around the boat)',
+            description: 'On save, cache the detailed chart layers for a radius around the boat\'s current position (from local SignalK), so a passage area is fully offline. Progress shows in the status line above.',
+            properties: {
+              radiusNm: {
+                type: 'number',
+                title: 'Radius around boat',
+                enum: [0, 25, 50, 100, 200],
+                enumNames: ['Off', '25 nm', '50 nm', '100 nm', '200 nm'],
+                default: 0
+              },
+              detailZoom: {
+                type: 'number',
+                title: 'Detail level',
+                enum: [12, 13, 14, 15],
+                enumNames: ['Overview (z12)', 'Coastal (z13)', 'Detailed (z14)', 'Harbor (z15)'],
+                default: 13
+              },
+              concurrency: { type: 'number', title: 'Parallel fetches', default: 4 }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  plugin.start = function (options) {
+    const opts = options || {}
+    // If a sailkick account is configured, fetch the cloud config first (write token,
+    // bucket, org, InfluxDB URL) and merge it in — then start the modules. Otherwise
+    // start immediately with the manually-entered config (unchanged behaviour).
+    ;(async () => {
+      if (accountConfigured(opts.account)) {
+        const r = await resolveAccountConfig(app, opts.account)
+        if (r.bundle) {
+          opts.sync = { ...(opts.sync || {}), influxUrl: r.bundle.influxUrl, org: r.bundle.org, bucket: r.bundle.bucket, token: r.bundle.writeToken }
+          opts.proxy = { ...(opts.proxy || {}), sailkickUrl: opts.account.sailkickUrl }
+          accountStatus = `account: ${opts.account.slug} (${r.source})`
+        } else {
+          accountStatus = `account: ${opts.account.slug} — no config (${r.error || 'not reachable, no cache'})`
+        }
+      }
+      startModules(opts)
+    })().catch((e) => (app.error || console.error)('[sailkick-boat] start failed: ' + e.message))
+  }
+
+  function startModules (opts) {
+    // --- sync module (isolated: its failure must not affect the proxy) ---
+    if (opts.sync && opts.sync.enabled !== false && opts.sync.influxUrl) {
+      try { sync = createSync(app, opts.sync); sync.start() } catch (e) {
+        (app.error || console.error)('[sailkick-boat] sync start failed: ' + e.message)
+        sync = null
+      }
+    }
+
+    // --- proxy module (+ /ws/telemetry provider and /api/history from local sources) ---
+    if (!opts.proxy || opts.proxy.enabled !== false) {
+      const pOpts = { ...(opts.proxy || {}) }
+      if (pOpts.serveTelemetry !== false) {
+        try {
+          telemetry = createTelemetry(app, {})
+          telemetry.start()
+          pOpts.telemetryUpgrade = (req, s, h) => telemetry.handleUpgrade(req, s, h)
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] telemetry start failed: ' + e.message)
+          telemetry = null
+        }
+      }
+      if (!pOpts.history || pOpts.history.enabled !== false) {
+        try {
+          // ringSource = the telemetry module: when no local InfluxDB is configured
+          // (e.g. a Victron GX), history serves a DB-less ring from live telemetry.
+          // storeDir lets the persistent ring log default onto the SSD with the tiles.
+          history = createHistory(app, { ...(pOpts.history || {}), ringSource: telemetry, storeDir: pOpts.storeDir })
+          history.start()
+          pOpts.history = history // proxy dispatches /api/history to it when available()
+        } catch (e) {
+          (app.error || console.error)('[sailkick-boat] history start failed: ' + e.message)
+          history = null
+        }
+      }
+      try { proxy = createProxy(app, pOpts); proxy.start() } catch (e) {
+        (app.error || console.error)('[sailkick-boat] proxy start failed: ' + e.message)
+        proxy = null
+      }
+    }
+
+    statusTimer = setInterval(updateStatus, 5000)
+    updateStatus()
+  }
+
+  function updateStatus () {
+    if (!app.setPluginStatus) return
+    const parts = []
+    if (accountStatus) parts.push(accountStatus)
+    if (sync) parts.push(sync.status())
+    if (proxy) parts.push(proxy.status())
+    if (telemetry) parts.push(telemetry.status())
+    if (history) parts.push(history.status())
+    try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
+  }
+
+  plugin.stop = function () {
+    if (statusTimer) clearInterval(statusTimer)
+    statusTimer = null
+    try { if (sync) sync.stop() } catch {}
+    try { if (telemetry) telemetry.stop() } catch {}
+    try { if (history) history.stop() } catch {}
+    try { if (proxy) proxy.stop() } catch {}
+    sync = null
+    telemetry = null
+    history = null
+    proxy = null
+    accountStatus = null
+  }
+
+  // Mounted by Signal K at /plugins/sailkick-boat. Handlers dispatch to the live
+  // proxy module (created in start), so enable/disable works at request time.
+  plugin.registerWithRouter = function (router) {
+    router.get('/p/*', (req, res) => {
+      if (proxy) proxy.handleGet(req, res)
+      else res.status(503).send('proxy not enabled')
+    })
+    router.post('/prefetch', (req, res) => {
+      if (proxy) proxy.handlePrefetch(req, res)
+      else res.status(503).send('proxy not enabled')
+    })
+    router.post('/prefetch/region', (req, res) => {
+      if (proxy) proxy.handlePrefetchRegion(req, res)
+      else res.status(503).send('proxy not enabled')
+    })
+    router.post('/cache/clear', (req, res) => {
+      if (proxy) proxy.handleClear(req, res)
+      else res.status(503).send('proxy not enabled')
+    })
+  }
+
+  return plugin
+}

package/lib/account/index.js

@@ -0,0 +1,65 @@
+'use strict'
+
+// Sailkick account auto-config. Instead of pasting InfluxDB URL/org/bucket/write-token
+// into the plugin, the owner enters host + slug + password; on start the plugin POSTs
+// them to the sailkick app's /api/boat/config and gets its cloud config back. The
+// last-good bundle is cached (0600) so sync keeps working offline after the first
+// connect. Dependency-free; never throws.
+
+const fs = require('fs')
+const path = require('path')
+
+function accountConfigured (account) {
+  return !!(account && account.sailkickUrl && account.slug && account.password)
+}
+
+function cacheFileFor (app) {
+  const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
+  return path.join(dataDir, 'account.json')
+}
+
+function readCache (file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return (j && j.writeToken) ? j : null
+  } catch { return null }
+}
+
+function writeCache (file, bundle) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const tmp = `${file}.tmp-${process.pid}`
+    fs.writeFileSync(tmp, JSON.stringify(bundle), { mode: 0o600 })
+    fs.renameSync(tmp, file)
+  } catch {}
+}
+
+// Returns { bundle, source: 'live'|'cache'|null, error? }.
+// bundle = { influxUrl, org, bucket, writeToken, readToken }.
+async function resolveAccountConfig (app, account, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 15000
+  const file = cacheFileFor(app)
+  const url = String(account.sailkickUrl).replace(/\/+$/, '') + '/api/boat/config'
+  const fallback = (error) => { const c = readCache(file); return { bundle: c, source: c ? 'cache' : null, error } }
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ slug: account.slug, password: account.password }),
+      signal: AbortSignal.timeout(timeoutMs)
+    })
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => '')
+      return fallback(`HTTP ${resp.status}: ${body.slice(0, 120)}`) // offline-safe: keep the cached bundle
+    }
+    const j = await resp.json().catch(() => null)
+    if (!j || j.ok === false || !j.writeToken) return fallback('unexpected /api/boat/config response')
+    const bundle = { influxUrl: j.influxUrl, org: j.org, bucket: j.bucket, writeToken: j.writeToken, readToken: j.readToken }
+    writeCache(file, bundle)
+    return { bundle, source: 'live' }
+  } catch (e) {
+    return fallback(e.message) // offline / unreachable → use the cached bundle
+  }
+}
+
+module.exports = { resolveAccountConfig, accountConfigured }