signalk-chiplog 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to Chiplog are documented here. The format follows
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-09-18
+
+### Added
+
+- **Import a PostgSail logbook.** `node scripts/import-postgsail.js <trips.geojson> --url <server>` reads PostgSail's
+  GeoJSON export and adds each trip as a passage — track, wind, engine and sail periods, place names, fuel level, house
+  battery, instrument snapshots — through the API, so the logbook can be on the boat's server. It is safe to run again:
+  a passage already on record is skipped. The route it uses, `POST /entries` (administrator), adds any finished passage
+  and answers `409 entry_overlaps` when it overlaps one on record. See the README's _Importing from PostgSail_.
+
 ## [2.4.0] - 2026-09-18
 
 ### Added
@@ -307,7 +317,8 @@ First release.
 - REST API under `/plugins/signalk-chiplog/api`, documented in [docs/API.md](docs/API.md).
 - Single SQLite database through Node's built-in `node:sqlite`: no native module to build.
 
-[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.4.0...HEAD
+[Unreleased]: https://github.com/ricard33/signalk-chiplog/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.1...v2.4.0
 [2.3.1]: https://github.com/ricard33/signalk-chiplog/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/ricard33/signalk-chiplog/compare/v2.2.0...v2.3.0

package/README.md

@@ -30,6 +30,7 @@ English and French, chosen from the browser's language.
 - [Signal K data used](#signal-k-data-used-)
 - [Backups and abandon ship](#backups-and-abandon-ship-)
 - [Retrospective analysis](#retrospective-analysis-)
+- [Importing from PostgSail](#importing-from-postgsail-)
 - [Privacy and online services](#privacy-and-online-services-)
 - [Troubleshooting](#troubleshooting-)
 - [Limitations](#limitations-)
@@ -417,6 +418,32 @@ at the time.
   track has one point per **Track point interval**. Everything else read from a continuously published path — position,
   speed, wind, engine, autopilot, depth, barometer — is reconstructed the same as live.
 
+## Importing from PostgSail 📥
+
+Kept your logbook with [PostgSail](https://github.com/xbgmsharp/postgsail) until now? Its GeoJSON export — one trip or
+several — comes into Chiplog with the script `scripts/import-postgsail.js`, run from a checkout of this repository (Node
+22.13 or later, nothing to install). It talks to the plugin's REST API, so the logbook can be on the boat's Signal K
+server while you run it from your own computer.
+
+```bash
+node scripts/import-postgsail.js PostgSail_Trip.geojson --url http://boat.local:3000 --token <token>
+```
+
+- **Administrator access.** Give the token of an administrator with `--token` (or `CHIPLOG_TOKEN`), or sign in with
+  `--user` and `--password` (or `CHIPLOG_PASSWORD`); a server without Signal K security needs neither.
+- **Each trip becomes a passage**, with its track, wind and speed, the engine and sail periods read from PostgSail's
+  _sailing_ and _motoring_ status, the places from the trip name, and instrument snapshots every hour on the clock
+  (`--observation-interval <minutes>`, `0` for none).
+- **Safe to run again.** A passage that overlaps one already in the logbook is skipped, so a run cut short is finished
+  by running the same command; nothing is duplicated. `--dry-run` lists what the file holds without sending anything.
+- **Boat state at departure.** PostgSail's tank level is taken as the fuel tank, and its voltage and state of charge as
+  the house battery, noted like Chiplog does live.
+- **Not imported:** PostgSail's own distance — Chiplog sums the track, as for every passage, which lands within a few
+  percent of it.
+- Place names come as PostgSail has them. Passages near a place Chiplog already knows are named the same; the countries
+  and landmarks are then looked up in the background, like for any passage. Tide and weather forecasts are not fetched
+  for passages this old.
+
 ## Privacy and online services 🔒
 
 - **Place names.** With geocoding on, the position of each departure and arrival that matches no known place is sent to
@@ -549,6 +576,7 @@ npm install          # also copies the browser libraries into public/vendor/
 npm test
 npm run lint
 npm run demo:seed -- /tmp/chiplog-demo   # a demo logbook to try the webapps with
+npm run import:postgsail -- <trips.geojson> --url <server>   # see Importing from PostgSail
 ```
 
 The functional specification is in [docs/SPEC.md](docs/SPEC.md), the data model in

package/lib/api.js

@@ -8,6 +8,7 @@ const { listEntryLandmarks } = require('./landmarks');
 const { isTimeZone, PDF_LANGUAGES } = require('./logbook-pdf');
 const { toGeoJson, toGpx } = require('./formats');
 const manoeuvreTypes = require('./manoeuvre-types');
+const { importPassage, TRACK_READINGS, OBSERVATION_READINGS } = require('./passage-import');
 const places = require('./places');
 const propulsion = require('./propulsion');
 const { getTideForecast } = require('./tide-forecaster');
@@ -81,6 +82,112 @@ function parseRange(query) {
   };
 }
 
+const TRACK_POINT_FIELDS = ['time', 'lat', 'lon', ...TRACK_READINGS];
+const OBSERVATION_FIELD_READINGS = OBSERVATION_READINGS.map(([, field]) => field);
+const OBSERVATION_FIELDS = ['time', 'reason', 'position', ...OBSERVATION_FIELD_READINGS];
+const OBSERVATION_REASONS = ['periodic', 'entry_start', 'entry_end', 'event'];
+
+const nullableNumber = (value, name) => (value === null ? null : v.parseNumber(value, name));
+
+// A list of objects in a request body, each checked field by field; an absent
+// list is an empty one.
+function parseList(body, field, parseItem) {
+  if (!(field in body)) {
+    return [];
+  }
+  if (!Array.isArray(body[field])) {
+    throw badRequest(`${field} must be an array`);
+  }
+  return body[field].map((item, index) => parseItem(item, `${field}[${index}]`));
+}
+
+function parseTrackPoint(item, name) {
+  const point = v.requireBody(item, TRACK_POINT_FIELDS);
+  const { lat, lon } = v.parsePosition({ lat: point.lat, lon: point.lon }, name);
+  return {
+    time: v.parseTimestamp(point.time, `${name}.time`),
+    lat,
+    lon,
+    ...Object.fromEntries(
+      TRACK_READINGS.filter((reading) => reading in point).map((reading) => [
+        reading,
+        nullableNumber(point[reading], `${name}.${reading}`)
+      ])
+    )
+  };
+}
+
+function parseObservation(item, name) {
+  const observation = v.requireBody(item, OBSERVATION_FIELDS);
+  return {
+    time: v.parseTimestamp(observation.time, `${name}.time`),
+    reason: v.parseEnum(observation.reason, `${name}.reason`, OBSERVATION_REASONS),
+    position: optional(observation, 'position', v.parsePosition),
+    ...Object.fromEntries(
+      OBSERVATION_FIELD_READINGS.filter((reading) => reading in observation).map((reading) => [
+        reading,
+        nullableNumber(observation[reading], `${name}.${reading}`)
+      ])
+    )
+  };
+}
+
+// A tank as noted at departure: level as a ratio, volume and capacity in m³.
+function parseTank(item, name) {
+  const tank = v.requireBody(item, ['type', 'id', 'name', 'level', 'volume', 'capacity']);
+  const readings = ['level', 'volume', 'capacity'].filter((field) => tank[field] != null);
+  if (!('level' in tank || 'volume' in tank)) {
+    throw badRequest(`${name} needs a level or a volume`);
+  }
+  return {
+    type: v.parseString(tank.type, `${name}.type`, { maxLength: 40 }),
+    id: v.parseString(tank.id, `${name}.id`, { maxLength: 40 }),
+    ...(tank.name == null
+      ? {}
+      : { name: v.parseString(tank.name, `${name}.name`, { maxLength: 100 }) }),
+    ...Object.fromEntries(
+      readings.map((field) => [field, v.parseNonNegativeNumber(tank[field], `${name}.${field}`)])
+    )
+  };
+}
+
+// A battery as noted at departure: volts, amps (negative discharging), state of
+// charge as a ratio, kelvin.
+function parseBattery(item, name) {
+  const battery = v.requireBody(item, [
+    'id',
+    'name',
+    'voltage',
+    'current',
+    'stateOfCharge',
+    'temperature'
+  ]);
+  const readings = ['voltage', 'current', 'stateOfCharge', 'temperature'].filter(
+    (field) => battery[field] != null
+  );
+  if (readings.length === 0) {
+    throw badRequest(`${name} needs at least one reading`);
+  }
+  return {
+    id: v.parseString(battery.id, `${name}.id`, { maxLength: 40 }),
+    ...(battery.name == null
+      ? {}
+      : { name: v.parseString(battery.name, `${name}.name`, { maxLength: 100 }) }),
+    ...Object.fromEntries(
+      readings.map((field) => [field, v.parseNumber(battery[field], `${name}.${field}`)])
+    )
+  };
+}
+
+function parsePropulsionPeriod(item, name) {
+  const segment = v.requireBody(item, ['type', 'startTime', 'endTime']);
+  return {
+    type: v.parseEnum(segment.type, `${name}.type`, ['engine', 'sail']),
+    startTime: v.parseTimestamp(segment.startTime, `${name}.startTime`),
+    endTime: v.parseTimestamp(segment.endTime, `${name}.endTime`)
+  };
+}
+
 function registerRoutes(router, { getContext, logError }) {
   const readonly = scoped(router, 'readonly');
   const readwrite = scoped(router, 'readwrite');
@@ -143,6 +250,47 @@ function registerRoutes(router, { getContext, logError }) {
     handle(({ db }, req) => entries.getEntry(db, entryId(req)))
   );
 
+  // A finished passage recorded elsewhere, such as another logbook's export.
+  admin.post(
+    '/api/entries',
+    handle(({ db, config, now }, req, res) => {
+      const body = v.requireBody(req.body, [
+        'startTime',
+        'endTime',
+        'startPosition',
+        'endPosition',
+        'startPlaceName',
+        'endPlaceName',
+        'distance',
+        'startTanks',
+        'startBatteries',
+        'trackPoints',
+        'observations',
+        'propulsion'
+      ]);
+      const entry = importPassage(
+        db,
+        {
+          startTime: v.parseTimestamp(body.startTime, 'startTime'),
+          endTime: v.parseTimestamp(body.endTime, 'endTime'),
+          startPosition: optional(body, 'startPosition', v.parsePosition) ?? null,
+          endPosition: optional(body, 'endPosition', v.parsePosition) ?? null,
+          startPlaceName: optional(body, 'startPlaceName', nullableString(200)) ?? null,
+          endPlaceName: optional(body, 'endPlaceName', nullableString(200)) ?? null,
+          distance: optional(body, 'distance', v.parseNonNegativeNumber),
+          startTanks: parseList(body, 'startTanks', parseTank),
+          startBatteries: parseList(body, 'startBatteries', parseBattery),
+          trackPoints: parseList(body, 'trackPoints', parseTrackPoint),
+          observations: parseList(body, 'observations', parseObservation),
+          propulsion: parseList(body, 'propulsion', parsePropulsionPeriod)
+        },
+        { placeMatchRadius: config.placeMatchRadius, now: now() }
+      );
+      res.status(201);
+      return entry;
+    })
+  );
+
   readwrite.patch(
     '/api/entries/:id',
     handle(({ db, config, now }, req) => {

package/lib/passage-import.js

@@ -0,0 +1,190 @@
+const { withTransaction } = require('./database');
+const { badRequest, conflict } = require('./errors');
+const { getEntry, recomputeDurations } = require('./entries');
+const { initialPlaceName } = require('./place-names');
+const { distanceBetween, findNearestPlace } = require('./places');
+
+const TRACK_READINGS = ['sog', 'cog', 'stw', 'heading', 'tws', 'twd', 'aws', 'awa'];
+// [column, request field]
+const OBSERVATION_READINGS = [
+  ...TRACK_READINGS.map((reading) => [reading, reading]),
+  ['depth', 'depth'],
+  ['pressure', 'pressure'],
+  ['air_temp', 'airTemp'],
+  ['water_temp', 'waterTemp'],
+  ['trip_log', 'tripLog'],
+  ['engine_runtime', 'engineRuntime']
+];
+
+// An anchorage is not left at the same spot twice: a place of the same name this close
+// is the same place, though further than the matching radius.
+const SAME_NAME_REACH_METRES = 500;
+
+// A passage recorded elsewhere is only ever added next to the ones on record,
+// never on top of them: the vessel was in one place at a time, so an overlap
+// means the passage is already there, or that one of the two is wrong.
+function requireNoOverlap(db, startTime, endTime) {
+  const clash = db
+    .prepare(
+      `SELECT id FROM log_entries
+       WHERE start_time < ? AND COALESCE(end_time, '9999-12-31T23:59:59.999Z') > ?
+       ORDER BY start_time LIMIT 1`
+    )
+    .get(endTime, startTime);
+  if (clash) {
+    throw conflict('entry_overlaps', `The passage overlaps entry ${clash.id} already on record`);
+  }
+}
+
+// The name comes from the source, so it is kept as given; the position is tied
+// to a known place when there is one in reach, or made into one, so a later
+// departure from the same spot is named the same way. Without a name it is
+// named as a passage detected live would be.
+function resolvePlace(db, position, name, radius, now) {
+  if (!position) {
+    return { id: null, name: name ?? null, pending: 0 };
+  }
+  if (name === null || name === undefined) {
+    return initialPlaceName(db, position, radius);
+  }
+  const known =
+    findNearestPlace(db, position, radius) ??
+    db
+      .prepare('SELECT * FROM places WHERE name = ? COLLATE NOCASE')
+      .all(name)
+      .find((place) => distanceBetween(position, place) <= SAME_NAME_REACH_METRES);
+  if (known) {
+    return { id: known.id, name, pending: 0 };
+  }
+  const { lastInsertRowid } = db
+    .prepare(
+      `INSERT INTO places (name, lat, lon, source, created_at, updated_at)
+       VALUES (?, ?, ?, 'manual', ?, ?)`
+    )
+    .run(name, position.lat, position.lon, now, now);
+  return { id: Number(lastInsertRowid), name, pending: 0 };
+}
+
+function requireWithin(startTime, endTime, time, name) {
+  if (time < startTime || time > endTime) {
+    throw badRequest(`${name} must fall between startTime and endTime`);
+  }
+}
+
+function trackDistance(points) {
+  let total = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    total += distanceBetween(points[i - 1], points[i]);
+  }
+  return total;
+}
+
+// Adds a finished passage recorded elsewhere -- another logbook's export --
+// with its track, instrument readings and engine/sail periods. All or nothing.
+// Unlike anything detection writes, its `closed_by` stays empty, so a departure
+// soon after it never reopens it. Without a `distance`, the passage's is the
+// sum over its track, as it is for one logged live.
+function importPassage(db, input, { placeMatchRadius, now }) {
+  const { startTime, endTime } = input;
+  if (endTime < startTime) {
+    throw badRequest('endTime must not be earlier than startTime');
+  }
+  input.trackPoints.forEach((point, index) =>
+    requireWithin(startTime, endTime, point.time, `trackPoints[${index}].time`)
+  );
+  input.observations.forEach((observation, index) =>
+    requireWithin(startTime, endTime, observation.time, `observations[${index}].time`)
+  );
+  input.propulsion.forEach((segment, index) => {
+    requireWithin(startTime, endTime, segment.startTime, `propulsion[${index}].startTime`);
+    requireWithin(startTime, endTime, segment.endTime, `propulsion[${index}].endTime`);
+    if (segment.endTime < segment.startTime) {
+      throw badRequest(`propulsion[${index}].endTime must not be earlier than its startTime`);
+    }
+  });
+
+  return withTransaction(db, () => {
+    requireNoOverlap(db, startTime, endTime);
+
+    const start = resolvePlace(
+      db,
+      input.startPosition,
+      input.startPlaceName,
+      placeMatchRadius,
+      now
+    );
+    const end = resolvePlace(db, input.endPosition, input.endPlaceName, placeMatchRadius, now);
+    const { lastInsertRowid } = db
+      .prepare(
+        `INSERT INTO log_entries (
+           state, start_time, end_time, start_lat, start_lon, end_lat, end_lon,
+           start_place_id, end_place_id, start_place_name, end_place_name,
+           start_place_pending, end_place_pending, distance, start_tanks, start_batteries, created_at,
+           updated_at
+         ) VALUES ('closed', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(
+        startTime,
+        endTime,
+        input.startPosition?.lat ?? null,
+        input.startPosition?.lon ?? null,
+        input.endPosition?.lat ?? null,
+        input.endPosition?.lon ?? null,
+        start.id,
+        end.id,
+        start.name,
+        end.name,
+        start.pending,
+        end.pending,
+        input.distance ?? trackDistance(input.trackPoints),
+        input.startTanks.length > 0 ? JSON.stringify(input.startTanks) : null,
+        input.startBatteries.length > 0 ? JSON.stringify(input.startBatteries) : null,
+        now,
+        now
+      );
+    const entryId = Number(lastInsertRowid);
+
+    const insertPoint = db.prepare(
+      `INSERT INTO track_points (entry_id, time, lat, lon, ${TRACK_READINGS.join(', ')})
+       VALUES (?, ?, ?, ?, ${TRACK_READINGS.map(() => '?').join(', ')})`
+    );
+    for (const point of input.trackPoints) {
+      insertPoint.run(
+        entryId,
+        point.time,
+        point.lat,
+        point.lon,
+        ...TRACK_READINGS.map((reading) => point[reading] ?? null)
+      );
+    }
+
+    const insertObservation = db.prepare(
+      `INSERT INTO observations (
+         entry_id, time, reason, lat, lon, ${OBSERVATION_READINGS.map(([column]) => column).join(', ')}
+       ) VALUES (?, ?, ?, ?, ?, ${OBSERVATION_READINGS.map(() => '?').join(', ')})`
+    );
+    for (const observation of input.observations) {
+      insertObservation.run(
+        entryId,
+        observation.time,
+        observation.reason,
+        observation.position?.lat ?? null,
+        observation.position?.lon ?? null,
+        ...OBSERVATION_READINGS.map(([, field]) => observation[field] ?? null)
+      );
+    }
+
+    const insertSegment = db.prepare(
+      `INSERT INTO propulsion_segments (entry_id, type, start_time, end_time, source)
+       VALUES (?, ?, ?, ?, 'auto')`
+    );
+    for (const segment of input.propulsion) {
+      insertSegment.run(entryId, segment.type, segment.startTime, segment.endTime);
+    }
+    recomputeDurations(db, entryId, now);
+
+    return getEntry(db, entryId);
+  });
+}
+
+module.exports = { importPassage, TRACK_READINGS, OBSERVATION_READINGS };

package/lib/validation.js

@@ -44,6 +44,13 @@ function parseNonNegativeNumber(value, name) {
   return value;
 }
 
+function parseNumber(value, name) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw badRequest(`${name} must be a number`);
+  }
+  return value;
+}
+
 function parsePosition(value, name) {
   if (value === null) {
     return null;
@@ -98,6 +105,7 @@ module.exports = {
   parseTimestamp,
   parseOptionalTimestamp,
   parseNonNegativeNumber,
+  parseNumber,
   parsePosition,
   parseString,
   parsePagination,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-chiplog",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Nautical logbook for Signal K: automatic entries, handwritten notes",
   "main": "index.js",
   "files": [
@@ -17,6 +17,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "demo:seed": "node scripts/seed-demo.js",
+    "import:postgsail": "node scripts/import-postgsail.js",
     "prepare": "husky && node scripts/vendor.js"
   },
   "keywords": [