Seamark

Read a trip's ordered legs: list them, or get one by id. A leg's `statsSource` is 'track' when its stats, coordinates and times are computed from a GPX track, 'manual' otherwise. On a trip someone else shared with the caller, `get` reads a leg but `list` does not — its legs are in `trip_read`'s `get`. The weather fields are hand-entered observations, except the wind pair when `weatherSource` is 'open_meteo': windSpeedKn is true wind speed in knots, windDirDeg an integer 0-359 in meteorological convention (the direction the wind blows FROM), seaState the Douglas degree of sea 0-9. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change a trip's ordered legs: create, update, delete, reorder (a full leg-id permutation, reassigning seq 1..N), and fill a leg's wind from a weather service (fetch_weather). A leg backed by a track (statsSource: 'track') rejects an update that touches any computed stats/coordinate/time field with a stats_readonly error — its startName/endName/notes stay editable regardless. The weather fields are hand-entered observations, except the wind pair when `weatherSource` is 'open_meteo': windSpeedKn is true wind speed in knots, windDirDeg an integer 0-359 in meteorological convention (the direction the wind blows FROM), seaState the Douglas degree of sea 0-9. They stay editable on EVERY leg, track-backed or not, because no GPX file records them. `fetch_weather` fills the leg's WIND (speed and direction, never sea state) from the free Open-Meteo service: it resolves the position and time window from the leg's own data (its track's middle point, else its endpoint midpoint, else its start) and stores the arithmetic mean of the hourly speeds over that window plus their SPEED-WEIGHTED circular mean direction, stamping weatherSource 'open_meteo' and weatherFetchedAt — except when the window was a dead calm, which yields no direction: a hand-entered windDirDeg then survives and the response says weatherSource 'manual' instead, because the stamp must never attribute a hand-typed value to the provider. This is the ONLY action that makes an outbound network call on the caller's behalf, it is rate-limited to 30 per hour per user, and it overwrites whatever wind the leg already had, hand-entered included. A later hand-edit of either WIND field flips weatherSource back to 'manual' and clears weatherFetchedAt; writing seaState does NOT, because the pair records where the wind came from and sea state is never fetched. A leg with no usable coordinates or no usable time window is weather_no_position (422); an upstream failure or a date the provider does not cover is weather_unavailable (503). IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's private address book of people — crew and contacts: list them all, or get one by id. Personal data (birth date, passport) is never shared across users. `linkedAccount` reports whether this person has accepted an invitation and is linked to a Seamark account. `isSelf` marks the ONE person in the caller's book that is the caller, so voyages with them on the crew list count as the caller's own. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change the caller's private address book of people — crew and contacts (create, update, delete, unlink_account, mark_self, unmark_self, invite, accept_invitation). Personal data (birth date, passport) is never shared across users. `linkedAccount` reports whether this person has accepted an invitation and is linked to a Seamark account. `isSelf` marks the ONE person in the caller's book that is the caller, so voyages with them on the crew list count as the caller's own. `invite` mails a Seamark invitation to a person who crews at least one of the caller's trips (409 `invitation_no_trips` otherwise — the person must be on a trip's crew first); accepting it links their account to this person, which opens EVERY trip of the caller's they crew, past and future, so the mail lists all of them. It is rate-limited to one send per person per minute and 3 sends per recipient address per hour (a budget shared with trip_write's `announce`, keyed on the address rather than the feature), remembers the address on the person's `email` (advancing the person's `updatedAt` version token — the response carries the new value), and re-inviting replaces the previous invitation, so a mistyped address's link stops working. `accept_invitation` is the other side: it binds the CALLER's own account to the person named by the token, requires the caller's address to match the one invited, and returns every trip it opened. `unlink_account` revokes a person's account link everywhere at once AND cancels any invitation to that person that has not been accepted yet — a pending invite mail stops working, which is what makes the revocation final rather than something the other party can undo by re-clicking their link. It is idempotent, and on someone who was never linked its only effect is to cancel a pending invitation. `mark_self` sets `isSelf` (marking someone new moves the marker off whoever held it — at most one person is the caller), `unmark_self` clears it. Both are idempotent and unrelated to `linkedAccount`/invitations — "this is me" is the caller's own identity, not an access grant. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The caller's sailing résumé — the record a charter company asks for before handing over a boat: one row per voyage the caller sailed with a known role, newest first, each with start and end date, the boat (name, model, length overall in centimeters as `loaCm`, hull type, or null when the voyage has no boat), the caller's role ('skipper' or 'crew'), ports-of-call countries (ISO 3166-1 alpha-2) and sea areas in voyage order, distance in meters, days at sea and night time in seconds. Totals cover the returned rows, overall and per role. Optional `role` ('all', 'skipper', 'crew') filters the rows; optional `from`/`to` (YYYY-MM-DD, inclusive) bound them by start date. Voyages where the caller is not on the crew have no role, are left out, and are counted as `unattributedTripsCount`. The figures come from the caller's own log and are not verified by anyone else. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's boats — a reusable, per-owner registry: list them all, or get one by id. The optional `flag` field is a ship's flag state as an uppercase ISO 3166-1 alpha-2 country code (e.g. "HR", "CZ"), or null. The optional `hullType` is 'monohull', 'catamaran' or 'trimaran', or null when unknown. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Create, update or delete one of the caller's boats. The optional `flag` field is a ship's flag state as an uppercase ISO 3166-1 alpha-2 country code (e.g. "HR", "CZ"), or null. The optional `hullType` is 'monohull', 'catamaran' or 'trimaran', or null when unknown. Sending null for `flag` or `hullType` clears it. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The caller's lifetime logbook statistics across their whole log — the trips they own AND the trips shared with them as linked crew. Returns totals (distance in meters, moving/total time in seconds, days at sea, distinct shipmates, best sustained 1/5/10-minute speeds in knots, average speed, earliest trip date), a per-year breakdown (by trip start-date year, newest first), and a per-boat breakdown (own and shared boats, each flagged `owned`; by distance, largest first). The optional `role` filters every figure by the role the caller held on each trip: 'all' (default) counts every voyage, 'skipper' or 'crew' count only voyages where the caller held that role. Voyages where the caller is not on the crew have no role: they count only under 'all' and are reported as `unattributedTripsCount`. `ownedTripsCount` and `sharedTripsCount` split the whole log into voyages the caller owns and voyages shared with them, whatever the `role`. All distances are meters and all durations seconds — never nmi/hours; speeds are knots or null. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read a leg's GPX track: get the current track, and audit every kept/dropped point with its drop reason. Audit results are paged with offset/limit; a long track has many points. On a trip someone else shared with the caller, `get` reads the track; the audit stays the owner's. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change a leg's GPX track: import raw GPX text (inline, capped at 5 Mi UTF-16 code units — that is what the schema counts, so it is roughly 5 MB for plain-ASCII GPX and no less for a file full of non-ASCII names; the server-side pipeline caps are separate: 32 MB of bytes AND at most 75,000 trackpoints per file (#191) — a file over the inline cap goes through the REST upload route instead, and one over the point cap has to be split or simplified first), reprocess the leg's stored raw file at the current pipeline version, and delete the track (the leg reverts to statsSource 'manual', retaining its last computed stats). IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Read the caller's voyages: list (the caller's OWN log), list the trips others shared with the caller (list_shared), get one trip, get its combined map, and get its public share link (get_share). `get` composes trip metadata with its crew, charter, and legs (there is no separate crew or charter read). `map` returns a GeoJSON FeatureCollection with one feature per mappable leg — track-backed, or manual with both endpoints set; a leg with no geometry is omitted. A trip someone else shared with the caller is readable with `get` and `map` and listed by `list_shared`, never by `list`; its charter is withheld, and so is the `pickupBase` summary field. `get_share` returns the trip's public, read-only, no-login link or null. Charter price/deposit are integer minor units plus an ISO 4217 currency code — never a float. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

Change the caller's own voyages: create, update, delete, replace the full crew set (set_crew, PUT semantics), set or clear the charter (set_charter — a null charter clears it), announce the trip to its crew by email (announce), and turn its public link on or off (create_share, revoke_share). Charter price/deposit are integer minor units plus an ISO 4217 currency code — never a float. Inviting a crew member to the app is person_write's `invite`/`accept_invitation`: an invitation is person-scoped, and accepting one shares every trip of that owner whose crew that person is on, past and future. `announce` mails the trip's particulars to crew who have a linked account and have not switched that category off in Settings; it reports how many actually went out, and is rate-limited per trip and per recipient address. `create_share` turns on a public, read-only, no-login link to one of the caller's OWN trips and returns its URL (idempotent — one link per trip, calling it again returns the same URL); `revoke_share` turns it off. The public view is redacted — no charter, crew shown as initials only, no owner details — but anyone with the link can open it, so the URL is semi-public. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.

The authenticated caller's own profile (id, email, name, language). Takes no arguments. IDs are 6-character case-sensitive alphanumeric strings. Timestamps are UTC ISO 8601. Distances are integer meters. Durations are integer seconds.