navcore_signalk_client/

resources.rs

//! Standalone waypoints and routes, on the wire.
//!
//! Signal K's own Resources API, at `/signalk/v2/api/resources/waypoints`
//! and `/signalk/v2/api/resources/routes` -- v2, not v1: the route
//! registration (`signalk-server/dist/api/resources/index.js`,
//! `RESOURCES_API_PATH`) is v2-only, and no v1 route exists at all. What
//! a waypoint or route means to this workspace lives in `waypoints` and
//! `routes`, the crates this module exists to serve; nothing here knows
//! either crate exists, the same one-way dependency [`crate::stream`]
//! already keeps toward `signalk` (units, not wire bytes), so that a
//! wire-format module can be reused by a different domain crate later.
//!
//! Both resource kinds answer the same four calls, registered by the
//! same generic code on the server side
//! (`signalk-server/dist/api/resources/index.js` builds identical routes
//! for every resource type it knows about, waypoints and routes alike):
//!
//! 1. `GET /resources/{kind}` -- every one the server holds, keyed by
//!    UUID.
//! 2. `POST /resources/{kind}` -- a new one; the server mints the UUID
//!    and returns it.
//! 3. `PUT /resources/{kind}/{id}` -- creates or replaces one at a
//!    caller-chosen UUID. The server validates `{id}` as a proper UUID
//!    v4 (`signalk-server/dist/api/resources/validate.js`'s own
//!    `uuid` check); an id that is not refuses with `400 Invalid
//!    resource id provided`, not a write.
//! 4. `DELETE /resources/{kind}/{id}` -- removes it. Answers the same
//!    `ActionResult` shape `PUT` does (`state`/`statusCode`/`message`,
//!    the id echoed back in `message` on success), confirmed live
//!    against a real server.
//!
//! A route's own `feature.geometry` is a `LineString`, not a `Point` --
//! the one real shape difference from a waypoint -- and it may name each
//! point along it via `feature.properties.coordinatesMeta`, an array
//! aligned index-for-index with `geometry.coordinates`. Each entry is
//! either `{name}` or `{href}` (the latter pointing at a standalone
//! waypoint resource by uuid, so a route can be built from waypoints
//! already in the library instead of bare positions); only the `name`
//! variant is read or written here -- linking route points back to
//! waypoint resources is a feature of its own, not needed for this
//! crate to carry a route it can round-trip.
//!
//! There is no third, empty variant: each entry's own TypeBox schema
//! (`resources-schemas.d.ts`) is `anyOf [{name}, {href}]`, not nullable,
//! so a placeholder for an unnamed point in the middle of an
//! otherwise-named route is refused outright, confirmed against a real
//! server's own AJV validation error. `write_route` writes
//! `coordinatesMeta` only when every point carries a name, and leaves
//! it out entirely otherwise.
//!
//! Every write needs a token: unlike the stream, whose `allowReadonly`
//! setting can let an unauthenticated client watch position updates, the
//! REST interface refuses an unauthenticated write outright.

use std::time::Duration;

use nav_math::Position;

use crate::access::agent;
use crate::{ClientError, Trust};

/// How long to wait for the server to answer one call -- the same figure
/// [`crate::access::TIMEOUT`] uses, for the same reason: these are calls
/// on a boat's own LAN, not calls to expect a slow answer from.
const TIMEOUT: Duration = Duration::from_secs(10);

/// A standalone waypoint, as the wire carries it.
#[derive(Debug, Clone, PartialEq)]
pub struct Waypoint {
    /// The server's own id, once it has one. `None` for a waypoint not
    /// yet published -- [`Client::publish_waypoint`] reads this to
    /// decide `POST` (mint one) or `PUT` (use this one) accordingly.
    pub uuid: Option<String>,
    /// What the mariner calls it.
    pub name: Option<String>,
    /// Anything they wrote about it.
    pub description: Option<String>,
    /// The mariner's own grouping -- Signal K's own optional `type`
    /// field on a waypoint resource, free text there and here alike.
    pub category: Option<String>,
    /// A platform-neutral marker shape -- `"location"`, `"bookmark"`,
    /// `"hazard"`, `"flag"`, `"favorite"`, or something a newer client
    /// invented that this build does not recognise yet. Carried in
    /// `feature.properties.icon`, not a top-level field, since the
    /// Signal K Waypoint schema itself defines none for this -- the
    /// same reasoning this module's own doc gives for why nothing here
    /// is a Signal K concept to begin with. This one
    /// is not even a borrowed convention the way freeboard-sk's own
    /// `properties.skIcon` is: it names no icon at all, only a shape
    /// each client renders in its own native icon set, whichever that
    /// is on its own platform. What decides
    /// which shape maps to which glyph belongs to `waypoints`, the
    /// crate this module exists to serve, and to each client after
    /// that -- never here, which only carries the string.
    pub icon: Option<String>,
    /// A named accent colour for `icon` -- `"red"`, `"blue"`,
    /// `"green"`, `"orange"`, or, the same as `icon`, something newer.
    /// `feature.properties.color`, the same reasoning as `icon`.
    pub color: Option<String>,
    /// Where it is.
    pub position: Position,
}

/// One named point along a [`Route`], as the wire carries it.
#[derive(Debug, Clone, PartialEq)]
pub struct RoutePoint {
    /// Where it is.
    pub position: Position,
    /// What the mariner called it, if `feature.properties.coordinatesMeta`
    /// carried a `name` entry for this point. `None` either for an
    /// unnamed point or for one whose entry was the `href` variant --
    /// see this module's own doc for why that variant is not read here.
    pub name: Option<String>,
}

/// A standalone route, as the wire carries it.
#[derive(Debug, Clone, PartialEq)]
pub struct Route {
    /// The server's own id, once it has one -- the same `None`-until-
    /// published convention [`Waypoint::uuid`] uses, for the same
    /// reason.
    pub uuid: Option<String>,
    /// What the mariner calls it.
    pub name: Option<String>,
    /// Anything they wrote about it.
    pub description: Option<String>,
    /// Total length, when the caller has one to send or the server sent
    /// one back. Never trusted over a fresh local recomputation --
    /// `routes::signalk`'s own doc gives the reasoning.
    pub distance_m: Option<f64>,
    /// The line itself, in the order it is sailed.
    pub points: Vec<RoutePoint>,
}

/// A recorded track, as the wire carries it.
///
/// Not a Signal K spec resource type -- confirmed against
/// `signalk-server`'s own `dist/api/resources/index.js`: only
/// `waypoints`/`routes`/`regions`/`notes`/`charts` are ever registered
/// by the server itself. `tracks` only exists at all once a server's own
/// `@signalk/resources-provider` plugin has been configured with it as a
/// "custom" collection -- at which point it answers the exact same
/// generic `GET`/`POST`/`PUT`/`DELETE` shape every resource type here
/// does, this module's own doc already explains why. No `isSignalKResourceType`
/// schema validates a write against this shape server-side the way one
/// does for `routes`/`waypoints`, so it is `tracks`'s crate's own
/// choice, not a spec's -- see `tracks::signalk`'s own doc, which this
/// exists to serve, for the fuller reasoning and for why it is not
/// simply Freeboard-SK's own (undocumented, display-only) `tracks`
/// convention adopted wholesale.
#[derive(Debug, Clone, PartialEq)]
pub struct Track {
    /// The server's own id, once it has one -- the same `None`-until-
    /// published convention [`Route::uuid`] uses, for the same reason.
    pub uuid: Option<String>,
    /// What the mariner calls it.
    pub name: Option<String>,
    /// Anything they wrote about it.
    pub description: Option<String>,
    /// A hex colour (`"#rrggbb"`), `feature.properties.color`, the same
    /// place [`Waypoint::color`] already lives -- but a free hex value
    /// here rather than [`Waypoint::color`]'s own small named palette:
    /// telling several tracks apart on one chart at once wants more
    /// distinct choices than a waypoint marker's four colours give.
    pub color: Option<String>,
    /// Total length, when the caller has one to send or the server sent
    /// one back. Never trusted over a fresh local recomputation --
    /// `tracks::signalk`'s own doc gives the same reasoning
    /// `routes::signalk`'s already does for a route's own distance.
    pub distance_m: Option<f64>,
    /// The line itself, in the order it was recorded. No per-point
    /// names the way [`RoutePoint`] can carry one: a recorded point has
    /// nowhere a name would come from, unlike a route's own waypoints,
    /// which a mariner placed and could label as they went.
    pub points: Vec<Position>,
    /// When the server itself last saved this -- the generic resource
    /// wrapper's own top-level `timestamp`, RFC 3339, confirmed live
    /// (`"$source":"resources-provider"` alongside it in a real `GET`
    /// answer). `None` only for a [`Track`] not yet published, which has
    /// no server-assigned timestamp to carry -- one this crate wrote
    /// itself never sends this back up; it is read-only, the server's
    /// own to set. Kept as the plain string rather than parsed: RFC 3339
    /// UTC timestamps already sort correctly as plain text, and nothing
    /// in this workspace pulls in a date/time crate merely to hold one.
    pub timestamp: Option<String>,
    /// When recording actually started, RFC 3339 --
    /// `feature.properties.startTime`. Unlike [`Self::timestamp`], this
    /// is the mariner's own client's to set, and *is* sent up on a
    /// write.
    pub recorded_from: Option<String>,
    /// When recording actually stopped, RFC 3339 --
    /// `feature.properties.endTime`. Same as [`Self::recorded_from`].
    pub recorded_to: Option<String>,
}

/// A client for one server's own Resources API.
///
/// Built from what [`crate::stream::Connection`] and
/// [`crate::access::request_access`] already needed -- the server's own
/// HTTP base, which authority to trust, and (once one exists) the
/// device's own token -- rather than a new set of credentials this
/// module invents for itself.
pub struct Client {
    http_base: String,
    trust: Trust,
    token: Option<String>,
}

impl Client {
    /// A client for the server at `http_base`, using `trust` to decide
    /// which server may answer and `token` (once one exists) to
    /// authenticate writes.
    #[must_use]
    pub fn new(http_base: String, trust: Trust, token: Option<String>) -> Self {
        Self { http_base, trust, token }
    }

    /// Every waypoint the server currently holds.
    ///
    /// # Errors
    ///
    /// If the server cannot be reached, or answers something this cannot
    /// make sense of.
    pub fn list_waypoints(&self) -> Result<Vec<Waypoint>, ClientError> {
        let mut request = agent(&self.trust)?
            .get(format!("{}/signalk/v2/api/resources/waypoints", self.http_base))
            .config()
            .timeout_global(Some(TIMEOUT))
            .build();
        if let Some(token) = &self.token {
            request = request.header("Authorization", format!("Bearer {token}"));
        }

        let answer: serde_json::Value = request
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let object = answer
            .as_object()
            .ok_or_else(|| ClientError::Protocol(format!("expected an object of waypoints, got {answer}")))?;
        object
            .iter()
            .map(|(uuid, value)| read_waypoint(Some(uuid.clone()), value))
            .collect()
    }

    /// Creates a new waypoint (`waypoint.uuid` is `None`) or replaces one
    /// at its own known id (`Some`). Either way, answers the id the
    /// waypoint now has on the server.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one -- if the server
    /// cannot be reached, or if it refuses the write.
    pub fn publish_waypoint(&self, waypoint: &Waypoint) -> Result<String, ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: publishing a waypoint needs one, the same as any other resource write".to_owned(),
            ));
        };

        let body = write_waypoint(waypoint);
        let agent = agent(&self.trust)?;

        // http_status_as_error(false), the same reason
        // access::request_access's own doc gives: the server's answer to
        // a refused write is meaningful, not just a status code to react
        // to, and reading it needs the body of a 4xx/5xx response, which
        // ureq discards by default.
        let mut response = if let Some(uuid) = &waypoint.uuid {
            agent
                .put(format!("{}/signalk/v2/api/resources/waypoints/{uuid}", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        } else {
            agent
                .post(format!("{}/signalk/v2/api/resources/waypoints", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        };

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer)
    }

    /// Deletes a waypoint by id.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one, the same as
    /// [`Client::publish_waypoint`] -- if the server cannot be reached,
    /// or if it refuses the delete.
    pub fn delete_waypoint(&self, uuid: &str) -> Result<(), ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: deleting a waypoint needs one, the same as any other resource write".to_owned(),
            ));
        };

        let mut response = agent(&self.trust)?
            .delete(format!("{}/signalk/v2/api/resources/waypoints/{uuid}", self.http_base))
            .header("Authorization", format!("Bearer {token}"))
            .config()
            .timeout_global(Some(TIMEOUT))
            .http_status_as_error(false)
            .build()
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer).map(|_id| ())
    }

    /// Every route the server currently holds.
    ///
    /// # Errors
    ///
    /// If the server cannot be reached, or answers something this cannot
    /// make sense of.
    pub fn list_routes(&self) -> Result<Vec<Route>, ClientError> {
        let mut request = agent(&self.trust)?
            .get(format!("{}/signalk/v2/api/resources/routes", self.http_base))
            .config()
            .timeout_global(Some(TIMEOUT))
            .build();
        if let Some(token) = &self.token {
            request = request.header("Authorization", format!("Bearer {token}"));
        }

        let answer: serde_json::Value = request
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let object = answer
            .as_object()
            .ok_or_else(|| ClientError::Protocol(format!("expected an object of routes, got {answer}")))?;
        object
            .iter()
            .map(|(uuid, value)| read_route(Some(uuid.clone()), value))
            .collect()
    }

    /// Creates a new route (`route.uuid` is `None`) or replaces one at
    /// its own known id (`Some`). Either way, answers the id the route
    /// now has on the server.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one -- if the server
    /// cannot be reached, or if it refuses the write.
    pub fn publish_route(&self, route: &Route) -> Result<String, ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: publishing a route needs one, the same as any other resource write".to_owned(),
            ));
        };

        let body = write_route(route);
        let agent = agent(&self.trust)?;

        let mut response = if let Some(uuid) = &route.uuid {
            agent
                .put(format!("{}/signalk/v2/api/resources/routes/{uuid}", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        } else {
            agent
                .post(format!("{}/signalk/v2/api/resources/routes", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        };

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer)
    }

    /// Deletes a route by id.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one, the same as
    /// [`Client::publish_route`] -- if the server cannot be reached, or
    /// if it refuses the delete.
    pub fn delete_route(&self, uuid: &str) -> Result<(), ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: deleting a route needs one, the same as any other resource write".to_owned(),
            ));
        };

        let mut response = agent(&self.trust)?
            .delete(format!("{}/signalk/v2/api/resources/routes/{uuid}", self.http_base))
            .header("Authorization", format!("Bearer {token}"))
            .config()
            .timeout_global(Some(TIMEOUT))
            .http_status_as_error(false)
            .build()
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer).map(|_id| ())
    }

    /// Every track the server currently holds. See [`Client::list_routes`]'s
    /// own doc for the identical shape; the only difference is the path.
    ///
    /// # Errors
    ///
    /// If the server cannot be reached, or it refuses the read --
    /// including a server whose `tracks` custom collection was never
    /// enabled at all, see [`Track`]'s own doc.
    pub fn list_tracks(&self) -> Result<Vec<Track>, ClientError> {
        let mut request = agent(&self.trust)?
            .get(format!("{}/signalk/v2/api/resources/tracks", self.http_base))
            .config()
            .timeout_global(Some(TIMEOUT))
            .build();
        if let Some(token) = &self.token {
            request = request.header("Authorization", format!("Bearer {token}"));
        }

        let answer: serde_json::Value = request
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let object = answer
            .as_object()
            .ok_or_else(|| ClientError::Protocol(format!("expected an object of tracks, got {answer}")))?;
        object.iter().map(|(uuid, value)| read_track(Some(uuid.clone()), value)).collect()
    }

    /// Creates a new track (`track.uuid` is `None`) or replaces one at
    /// its own known id (`Some`). Either way, answers the id the track
    /// now has on the server. See [`Client::publish_route`]'s own doc
    /// for the identical shape; the only difference is the path.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one -- if the server
    /// cannot be reached, or if it refuses the write (including a
    /// server whose `tracks` custom collection was never enabled at
    /// all, see [`Track`]'s own doc).
    pub fn publish_track(&self, track: &Track) -> Result<String, ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: publishing a track needs one, the same as any other resource write".to_owned(),
            ));
        };

        let body = write_track(track);
        let agent = agent(&self.trust)?;

        let mut response = if let Some(uuid) = &track.uuid {
            agent
                .put(format!("{}/signalk/v2/api/resources/tracks/{uuid}", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        } else {
            agent
                .post(format!("{}/signalk/v2/api/resources/tracks", self.http_base))
                .header("Authorization", format!("Bearer {token}"))
                .config()
                .timeout_global(Some(TIMEOUT))
                .http_status_as_error(false)
                .build()
                .send_json(&body)
                .map_err(|error| ClientError::Http(error.to_string()))?
        };

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer)
    }

    /// Deletes a track by id. See [`Client::delete_route`]'s own doc for
    /// the identical shape; the only difference is the path.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one, the same as
    /// [`Client::publish_track`] -- if the server cannot be reached, or
    /// if it refuses the delete.
    pub fn delete_track(&self, uuid: &str) -> Result<(), ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: deleting a track needs one, the same as any other resource write".to_owned(),
            ));
        };

        let mut response = agent(&self.trust)?
            .delete(format!("{}/signalk/v2/api/resources/tracks/{uuid}", self.http_base))
            .header("Authorization", format!("Bearer {token}"))
            .config()
            .timeout_global(Some(TIMEOUT))
            .http_status_as_error(false)
            .build()
            .call()
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_action_response(&answer).map(|_id| ())
    }
}

/// Reads one waypoint out of the shape the server's own `GET` answers
/// with -- `uuid` comes from the map key the caller already has, not
/// from inside `value` itself, which never repeats it.
fn read_waypoint(uuid: Option<String>, value: &serde_json::Value) -> Result<Waypoint, ClientError> {
    let name = value.get("name").and_then(serde_json::Value::as_str).map(str::to_owned);
    let description = value.get("description").and_then(serde_json::Value::as_str).map(str::to_owned);
    let category = value.get("type").and_then(serde_json::Value::as_str).map(str::to_owned);
    let properties = value.get("feature").and_then(|feature| feature.get("properties"));
    let icon = properties
        .and_then(|properties| properties.get("icon"))
        .and_then(serde_json::Value::as_str)
        .map(str::to_owned);
    let color = properties
        .and_then(|properties| properties.get("color"))
        .and_then(serde_json::Value::as_str)
        .map(str::to_owned);

    let coordinates = value
        .get("feature")
        .and_then(|feature| feature.get("geometry"))
        .and_then(|geometry| geometry.get("coordinates"))
        .and_then(serde_json::Value::as_array)
        .ok_or_else(|| ClientError::Protocol(format!("waypoint has no feature.geometry.coordinates: {value}")))?;
    let lon = coordinates
        .first()
        .and_then(serde_json::Value::as_f64)
        .ok_or_else(|| ClientError::Protocol(format!("coordinates has no longitude: {value}")))?;
    let lat = coordinates
        .get(1)
        .and_then(serde_json::Value::as_f64)
        .ok_or_else(|| ClientError::Protocol(format!("coordinates has no latitude: {value}")))?;

    Ok(Waypoint {
        uuid,
        name,
        description,
        category,
        icon,
        color,
        position: Position::new(lat, lon),
    })
}

/// The request body a `POST`/`PUT` sends -- Signal K's own `Waypoint`
/// shape, `coordinates` written `[lon, lat]`, GeoJSON's own order and the
/// opposite of `Position`'s own field order, which is why this is not a
/// plain derive.
fn write_waypoint(waypoint: &Waypoint) -> serde_json::Value {
    let mut body = serde_json::json!({
        "feature": {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [waypoint.position.lon_deg, waypoint.position.lat_deg],
            },
        },
    });
    if let Some(name) = &waypoint.name {
        body["name"] = serde_json::Value::String(name.clone());
    }
    if let Some(description) = &waypoint.description {
        body["description"] = serde_json::Value::String(description.clone());
    }
    if let Some(category) = &waypoint.category {
        body["type"] = serde_json::Value::String(category.clone());
    }
    if let Some(icon) = &waypoint.icon {
        // `feature.properties` does not exist yet at this point --
        // `serde_json::Value`'s own `IndexMut` auto-vivifies each
        // missing key along the chain as an object, so this alone is
        // enough to build it rather than needing a separate
        // `json!({"properties": {"icon": icon}})` merge step.
        body["feature"]["properties"]["icon"] = serde_json::Value::String(icon.clone());
    }
    if let Some(color) = &waypoint.color {
        body["feature"]["properties"]["color"] = serde_json::Value::String(color.clone());
    }
    body
}

/// Reads one route out of the shape the server's own `GET` answers with
/// -- `uuid` comes from the map key the caller already has, the same as
/// [`read_waypoint`].
fn read_route(uuid: Option<String>, value: &serde_json::Value) -> Result<Route, ClientError> {
    let name = value.get("name").and_then(serde_json::Value::as_str).map(str::to_owned);
    let description = value.get("description").and_then(serde_json::Value::as_str).map(str::to_owned);
    let distance_m = value.get("distance").and_then(serde_json::Value::as_f64);

    let feature = value.get("feature");
    let coordinates = feature
        .and_then(|feature| feature.get("geometry"))
        .and_then(|geometry| geometry.get("coordinates"))
        .and_then(serde_json::Value::as_array)
        .ok_or_else(|| ClientError::Protocol(format!("route has no feature.geometry.coordinates: {value}")))?;

    // `coordinatesMeta` is aligned index-for-index with `coordinates`,
    // when it is present at all -- an unnamed point is one whose index
    // has no entry, not one whose entry is null.
    let names = feature
        .and_then(|feature| feature.get("properties"))
        .and_then(|properties| properties.get("coordinatesMeta"))
        .and_then(serde_json::Value::as_array);

    let points = coordinates
        .iter()
        .enumerate()
        .map(|(index, point)| {
            let point = point
                .as_array()
                .ok_or_else(|| ClientError::Protocol(format!("route coordinate {index} is not [lon, lat]: {value}")))?;
            let lon = point
                .first()
                .and_then(serde_json::Value::as_f64)
                .ok_or_else(|| ClientError::Protocol(format!("route coordinate {index} has no longitude: {value}")))?;
            let lat = point
                .get(1)
                .and_then(serde_json::Value::as_f64)
                .ok_or_else(|| ClientError::Protocol(format!("route coordinate {index} has no latitude: {value}")))?;
            let name = names
                .and_then(|names| names.get(index))
                .and_then(|meta| meta.get("name"))
                .and_then(serde_json::Value::as_str)
                .map(str::to_owned);
            Ok(RoutePoint { position: Position::new(lat, lon), name })
        })
        .collect::<Result<Vec<_>, ClientError>>()?;

    Ok(Route { uuid, name, description, distance_m, points })
}

/// The request body a `POST`/`PUT` sends -- Signal K's own `Route`
/// shape, each point's `coordinates` written `[lon, lat]`, the same
/// `GeoJSON` order [`write_waypoint`] already uses.
fn write_route(route: &Route) -> serde_json::Value {
    let coordinates: Vec<serde_json::Value> = route
        .points
        .iter()
        .map(|point| serde_json::json!([point.position.lon_deg, point.position.lat_deg]))
        .collect();

    let mut body = serde_json::json!({
        "feature": {
            "type": "Feature",
            "geometry": {
                "type": "LineString",
                "coordinates": coordinates,
            },
        },
    });
    if let Some(name) = &route.name {
        body["name"] = serde_json::Value::String(name.clone());
    }
    if let Some(description) = &route.description {
        body["description"] = serde_json::Value::String(description.clone());
    }
    if let Some(distance_m) = route.distance_m {
        body["distance"] = serde_json::json!(distance_m);
    }
    // Only when every point has a name: the schema's own entry shape has
    // no stand-in for "this one has none" -- see this module's own doc.
    if !route.points.is_empty() && route.points.iter().all(|point| point.name.is_some()) {
        let meta: Vec<serde_json::Value> = route
            .points
            .iter()
            .map(|point| serde_json::json!({ "name": point.name.as_deref().unwrap_or_default() }))
            .collect();
        body["feature"]["properties"]["coordinatesMeta"] = serde_json::Value::Array(meta);
    }
    body
}

/// Reads one track out of the shape the server's own `GET` answers with
/// -- `uuid` comes from the map key the caller already has, the same as
/// [`read_route`].
fn read_track(uuid: Option<String>, value: &serde_json::Value) -> Result<Track, ClientError> {
    let name = value.get("name").and_then(serde_json::Value::as_str).map(str::to_owned);
    let description = value.get("description").and_then(serde_json::Value::as_str).map(str::to_owned);
    let distance_m = value.get("distance").and_then(serde_json::Value::as_f64);
    let timestamp = value.get("timestamp").and_then(serde_json::Value::as_str).map(str::to_owned);

    let feature = value.get("feature");
    let properties = feature.and_then(|feature| feature.get("properties"));
    let color = properties.and_then(|properties| properties.get("color")).and_then(serde_json::Value::as_str).map(str::to_owned);
    let recorded_from =
        properties.and_then(|properties| properties.get("startTime")).and_then(serde_json::Value::as_str).map(str::to_owned);
    let recorded_to =
        properties.and_then(|properties| properties.get("endTime")).and_then(serde_json::Value::as_str).map(str::to_owned);

    let coordinates = feature
        .and_then(|feature| feature.get("geometry"))
        .and_then(|geometry| geometry.get("coordinates"))
        .and_then(serde_json::Value::as_array)
        .ok_or_else(|| ClientError::Protocol(format!("track has no feature.geometry.coordinates: {value}")))?;

    let points = coordinates
        .iter()
        .enumerate()
        .map(|(index, point)| {
            let point = point
                .as_array()
                .ok_or_else(|| ClientError::Protocol(format!("track coordinate {index} is not [lon, lat]: {value}")))?;
            let lon = point
                .first()
                .and_then(serde_json::Value::as_f64)
                .ok_or_else(|| ClientError::Protocol(format!("track coordinate {index} has no longitude: {value}")))?;
            let lat = point
                .get(1)
                .and_then(serde_json::Value::as_f64)
                .ok_or_else(|| ClientError::Protocol(format!("track coordinate {index} has no latitude: {value}")))?;
            Ok(Position::new(lat, lon))
        })
        .collect::<Result<Vec<_>, ClientError>>()?;

    Ok(Track { uuid, name, description, color, distance_m, points, timestamp, recorded_from, recorded_to })
}

/// The request body a `POST`/`PUT` sends -- this crate's own `Track`
/// shape (see [`Track`]'s own doc for why it is not a Signal K spec
/// shape), each point's `coordinates` written `[lon, lat]`, the same
/// `GeoJSON` order [`write_route`] already uses.
fn write_track(track: &Track) -> serde_json::Value {
    let coordinates: Vec<serde_json::Value> =
        track.points.iter().map(|position| serde_json::json!([position.lon_deg, position.lat_deg])).collect();

    let mut body = serde_json::json!({
        "feature": {
            "type": "Feature",
            "geometry": {
                "type": "LineString",
                "coordinates": coordinates,
            },
        },
    });
    if let Some(name) = &track.name {
        body["name"] = serde_json::Value::String(name.clone());
    }
    if let Some(description) = &track.description {
        body["description"] = serde_json::Value::String(description.clone());
    }
    if let Some(distance_m) = track.distance_m {
        body["distance"] = serde_json::json!(distance_m);
    }
    if let Some(color) = &track.color {
        // `feature.properties` does not exist yet at this point --
        // see write_waypoint's own comment on the same auto-vivifying
        // behaviour this leans on too.
        body["feature"]["properties"]["color"] = serde_json::Value::String(color.clone());
    }
    if let Some(recorded_from) = &track.recorded_from {
        body["feature"]["properties"]["startTime"] = serde_json::Value::String(recorded_from.clone());
    }
    if let Some(recorded_to) = &track.recorded_to {
        body["feature"]["properties"]["endTime"] = serde_json::Value::String(recorded_to.clone());
    }
    body
}

/// Reads a `200`/`201 ActionResponse` for the id it names, or an
/// `ErrorResponse` for the message explaining why there is none -- the
/// one reader shared by `POST`, `PUT` and `DELETE`, since all three
/// answer with the same `ActionResult` shape.
///
/// Not simply "an `id` field, or else an error": a real server's `PUT`
/// (and `DELETE`) answer on success carries no `id` field at all --
/// only `POST` does -- and instead puts the id in `message`, the very
/// field a refusal also uses for its own explanation, confirmed live
/// against a real server. The one field that tells the two apart is
/// `state`: `"COMPLETED"` for success, `"FAILED"` for a refusal, the
/// same field [`crate::access::read_requested`] already leans on for
/// the same reason.
fn read_action_response(answer: &serde_json::Value) -> Result<String, ClientError> {
    if let Some(id) = answer.get("id").and_then(serde_json::Value::as_str) {
        return Ok(id.to_owned());
    }
    let message = answer.get("message").and_then(serde_json::Value::as_str);
    let completed = answer.get("state").and_then(serde_json::Value::as_str) == Some("COMPLETED");
    match message {
        Some(text) if completed => Ok(text.to_owned()),
        Some(text) => Err(ClientError::Protocol(text.to_owned())),
        None => Err(ClientError::Protocol(
            "the server's answer named no id and no message".to_owned(),
        )),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_listed_waypoint_is_read_from_its_own_map_entry() {
        // The shape a real server answers GET /resources/waypoints with,
        // kept verbatim -- one entry of the uuid-keyed object.
        let value: serde_json::Value = serde_json::from_str(
            r#"{"name":"Fuel dock","description":"Diesel only","type":"fuel",
                "feature":{"type":"Feature","geometry":{"type":"Point","coordinates":[13.568,45.515]}},
                "timestamp":"2026-08-16T09:00:00Z","$source":"client"}"#,
        )
        .unwrap();

        let waypoint = read_waypoint(Some("94052456-65fa-48ce-a85d-41b78a9d2111".to_owned()), &value).unwrap();
        assert_eq!(waypoint.uuid.as_deref(), Some("94052456-65fa-48ce-a85d-41b78a9d2111"));
        assert_eq!(waypoint.name.as_deref(), Some("Fuel dock"));
        assert_eq!(waypoint.description.as_deref(), Some("Diesel only"));
        assert_eq!(waypoint.category.as_deref(), Some("fuel"));
        assert!((waypoint.position.lat_deg - 45.515).abs() < 1e-9);
        assert!((waypoint.position.lon_deg - 13.568).abs() < 1e-9);
    }

    #[test]
    fn a_waypoint_with_no_name_or_description_is_still_read() {
        let value: serde_json::Value = serde_json::from_str(
            r#"{"feature":{"type":"Feature","geometry":{"type":"Point","coordinates":[1.0,2.0]}}}"#,
        )
        .unwrap();
        let waypoint = read_waypoint(None, &value).unwrap();
        assert_eq!(waypoint.name, None);
        assert_eq!(waypoint.description, None);
        assert_eq!(waypoint.category, None);
        assert_eq!(waypoint.icon, None);
        assert_eq!(waypoint.color, None);
    }

    #[test]
    fn icon_and_color_round_trip_through_feature_properties() {
        let value: serde_json::Value = serde_json::from_str(
            r#"{"name":"Fuel dock",
                "feature":{"type":"Feature","geometry":{"type":"Point","coordinates":[13.568,45.515]},
                           "properties":{"icon":"location","color":"red"}}}"#,
        )
        .unwrap();
        let waypoint = read_waypoint(None, &value).unwrap();
        assert_eq!(waypoint.icon.as_deref(), Some("location"));
        assert_eq!(waypoint.color.as_deref(), Some("red"));

        let body = write_waypoint(&waypoint);
        assert_eq!(body["feature"]["properties"]["icon"], "location");
        assert_eq!(body["feature"]["properties"]["color"], "red");
    }

    #[test]
    fn a_waypoint_with_no_geometry_is_a_protocol_error() {
        let value: serde_json::Value = serde_json::from_str(r#"{"name":"nowhere"}"#).unwrap();
        assert!(matches!(read_waypoint(None, &value), Err(ClientError::Protocol(_))));
    }

    #[test]
    fn coordinates_are_written_lon_then_lat_geojsons_own_order() {
        let waypoint = Waypoint {
            uuid: None,
            name: Some("Fuel dock".to_owned()),
            description: None,
            category: Some("fuel".to_owned()),
            icon: None,
            color: None,
            position: Position::new(45.515, 13.568),
        };
        let body = write_waypoint(&waypoint);
        assert_eq!(body["feature"]["geometry"]["coordinates"][0], 13.568);
        assert_eq!(body["feature"]["geometry"]["coordinates"][1], 45.515);
        assert_eq!(body["name"], "Fuel dock");
        assert_eq!(body["type"], "fuel");
        assert!(body.get("description").is_none());
        assert!(body["feature"].get("properties").is_none());
    }

    #[test]
    fn a_successful_post_response_names_its_id() {
        // A real POST /resources/waypoints 201 answer, captured live
        // against a real server.
        let answer: serde_json::Value =
            serde_json::from_str(r#"{"state":"COMPLETED","statusCode":201,"id":"c5c310ed"}"#).unwrap();
        assert_eq!(read_action_response(&answer).unwrap(), "c5c310ed");
    }

    #[test]
    fn a_successful_put_response_names_its_id_via_message() {
        // A real PUT /resources/waypoints/{id} 200 answer, captured live
        // against a real server -- no `id` field at all here, unlike POST's own
        // answer; the id comes back in `message`, the exact field a
        // refusal also uses for its own explanation. `state` is what
        // tells the two apart, not which field is present -- see
        // read_action_response's own doc.
        let answer: serde_json::Value = serde_json::from_str(
            r#"{"state":"COMPLETED","statusCode":200,"message":"c0ffee00-1234-4abc-89ab-c0ffeec0ffee"}"#,
        )
        .unwrap();
        assert_eq!(
            read_action_response(&answer).unwrap(),
            "c0ffee00-1234-4abc-89ab-c0ffeec0ffee"
        );
    }

    #[test]
    fn a_refused_publish_is_read_as_an_error_with_the_servers_own_message() {
        let answer: serde_json::Value =
            serde_json::from_str(r#"{"state":"FAILED","statusCode":400,"message":"Invalid waypoint"}"#).unwrap();
        let error = read_action_response(&answer).unwrap_err();
        assert!(matches!(error, ClientError::Protocol(ref message) if message == "Invalid waypoint"));
    }

    #[test]
    fn a_refused_put_names_the_invalid_id_it_was_given() {
        // A real PUT refusal, captured live against a real server for a
        // non-v4-shaped id -- state FAILED is what makes this an error
        // despite carrying a message that looks like it could be data.
        let answer: serde_json::Value = serde_json::from_str(
            r#"{"state":"FAILED","statusCode":400,"message":"Invalid resource id provided (11111111-2222-3333-4444-555555555555)"}"#,
        )
        .unwrap();
        let error = read_action_response(&answer).unwrap_err();
        assert!(matches!(error, ClientError::Protocol(ref message) if message.contains("Invalid resource id")));
    }

    #[test]
    fn a_successful_delete_response_is_read_the_same_way_a_put_is() {
        // A real DELETE /resources/waypoints/{id} 200 answer, captured
        // live against a real server -- the exact same ActionResult shape a PUT
        // success carries, id echoed back in `message`.
        let answer: serde_json::Value = serde_json::from_str(
            r#"{"state":"COMPLETED","statusCode":200,"message":"c0ffee00-1234-4abc-89ab-c0ffeec0ffee"}"#,
        )
        .unwrap();
        assert_eq!(
            read_action_response(&answer).unwrap(),
            "c0ffee00-1234-4abc-89ab-c0ffeec0ffee"
        );
    }

    #[test]
    fn deleting_without_a_token_is_refused_before_any_request_is_made() {
        let client = Client::new("https://example.invalid".to_owned(), Trust::plaintext(), None);
        let error = client.delete_waypoint("c0ffee00-1234-4abc-89ab-c0ffeec0ffee").unwrap_err();
        assert!(matches!(error, ClientError::Http(ref message) if message.contains("no token")));
    }

    #[test]
    fn a_listed_route_is_read_from_its_own_map_entry() {
        // The shape a real server answers GET /resources/routes with,
        // kept verbatim -- one entry of the uuid-keyed object.
        let value: serde_json::Value = serde_json::from_str(
            r#"{"name":"Piran to Koper","description":"Coastal hop","distance":9260.5,
                "feature":{"type":"Feature",
                    "geometry":{"type":"LineString","coordinates":[[13.568,45.515],[13.620,45.550],[13.730,45.548]]},
                    "properties":{"coordinatesMeta":[{"name":"Piran"},null,{"name":"Koper"}]}},
                "timestamp":"2026-08-16T09:00:00Z","$source":"client"}"#,
        )
        .unwrap();

        let route = read_route(Some("94052456-65fa-48ce-a85d-41b78a9d2111".to_owned()), &value).unwrap();
        assert_eq!(route.uuid.as_deref(), Some("94052456-65fa-48ce-a85d-41b78a9d2111"));
        assert_eq!(route.name.as_deref(), Some("Piran to Koper"));
        assert_eq!(route.description.as_deref(), Some("Coastal hop"));
        assert_eq!(route.distance_m, Some(9260.5));
        assert_eq!(route.points.len(), 3);
        assert_eq!(route.points[0].name.as_deref(), Some("Piran"));
        assert_eq!(route.points[1].name, None);
        assert_eq!(route.points[2].name.as_deref(), Some("Koper"));
        assert!((route.points[0].position.lat_deg - 45.515).abs() < 1e-9);
        assert!((route.points[0].position.lon_deg - 13.568).abs() < 1e-9);
    }

    #[test]
    fn a_route_with_no_point_names_is_still_read() {
        let value: serde_json::Value = serde_json::from_str(
            r#"{"feature":{"type":"Feature","geometry":{"type":"LineString","coordinates":[[1.0,2.0],[3.0,4.0]]}}}"#,
        )
        .unwrap();
        let route = read_route(None, &value).unwrap();
        assert_eq!(route.name, None);
        assert_eq!(route.description, None);
        assert_eq!(route.distance_m, None);
        assert_eq!(route.points.len(), 2);
        assert_eq!(route.points[0].name, None);
        assert_eq!(route.points[1].name, None);
    }

    #[test]
    fn a_route_with_no_geometry_is_a_protocol_error() {
        let value: serde_json::Value = serde_json::from_str(r#"{"name":"nowhere"}"#).unwrap();
        assert!(matches!(read_route(None, &value), Err(ClientError::Protocol(_))));
    }

    #[test]
    fn a_route_with_a_single_point_is_still_read() {
        // Geometrically odd -- a `LineString` of one point draws nothing
        // -- but not this reader's place to refuse it; `routes::Route`
        // is what decides a route needs at least two points to have any
        // legs, not the wire layer.
        let value: serde_json::Value = serde_json::from_str(
            r#"{"feature":{"type":"Feature","geometry":{"type":"LineString","coordinates":[[13.568,45.515]]}}}"#,
        )
        .unwrap();
        let route = read_route(None, &value).unwrap();
        assert_eq!(route.points.len(), 1);
    }

    #[test]
    fn a_malformed_route_coordinate_is_a_protocol_error() {
        // The first point parses; the second is a bare number, not a
        // `[lon, lat]` pair -- caught per-point rather than assuming
        // every entry in `coordinates` shares the first one's shape.
        let value: serde_json::Value = serde_json::from_str(
            r#"{"feature":{"type":"Feature","geometry":{"type":"LineString","coordinates":[[13.568,45.515],42]}}}"#,
        )
        .unwrap();
        assert!(matches!(read_route(None, &value), Err(ClientError::Protocol(_))));
    }

    #[test]
    fn an_href_linked_route_point_is_read_as_unnamed_not_an_error() {
        // The `{href}` variant `coordinatesMeta` may carry instead of
        // `{name}` -- a point linking back to a standalone waypoint
        // resource, which this crate does not resolve (see this
        // module's own doc). A server holding routes built by a client
        // that *does* use that variant must not make this one choke on
        // them; it just reads such a point as unnamed, the same as one
        // with no `coordinatesMeta` entry at all.
        let value: serde_json::Value = serde_json::from_str(
            r#"{"feature":{"type":"Feature",
                "geometry":{"type":"LineString","coordinates":[[13.568,45.515],[13.730,45.548]]},
                "properties":{"coordinatesMeta":[{"href":"/resources/waypoints/94052456-65fa-48ce-a85d-41b78a9d2111"},{"name":"Koper"}]}}}"#,
        )
        .unwrap();
        let route = read_route(None, &value).unwrap();
        assert_eq!(route.points[0].name, None);
        assert_eq!(route.points[1].name.as_deref(), Some("Koper"));
    }

    #[test]
    fn route_points_are_written_lon_then_lat_and_a_fully_named_route_carries_coordinatesmeta() {
        let route = Route {
            uuid: None,
            name: Some("Piran to Koper".to_owned()),
            description: None,
            distance_m: Some(9260.5),
            points: vec![
                RoutePoint { position: Position::new(45.515, 13.568), name: Some("Piran".to_owned()) },
                RoutePoint { position: Position::new(45.548, 13.730), name: Some("Koper".to_owned()) },
            ],
        };
        let body = write_route(&route);
        assert_eq!(body["feature"]["geometry"]["coordinates"][0][0], 13.568);
        assert_eq!(body["feature"]["geometry"]["coordinates"][0][1], 45.515);
        assert_eq!(body["feature"]["geometry"]["coordinates"][1][0], 13.730);
        assert_eq!(body["feature"]["geometry"]["coordinates"][1][1], 45.548);
        assert_eq!(body["name"], "Piran to Koper");
        assert_eq!(body["distance"], 9260.5);
        assert!(body.get("description").is_none());
        assert_eq!(body["feature"]["properties"]["coordinatesMeta"][0]["name"], "Piran");
        assert_eq!(body["feature"]["properties"]["coordinatesMeta"][1]["name"], "Koper");
    }

    #[test]
    fn a_route_with_no_named_points_writes_no_coordinatesmeta_at_all() {
        let route = Route {
            uuid: None,
            name: None,
            description: None,
            distance_m: None,
            points: vec![RoutePoint { position: Position::new(45.515, 13.568), name: None }],
        };
        let body = write_route(&route);
        assert!(body["feature"].get("properties").is_none());
        assert!(body.get("distance").is_none());
    }

    #[test]
    fn a_route_with_some_but_not_all_points_named_writes_no_coordinatesmeta_either() {
        // The schema's own entry shape is `{name}` or `{href}`, never a
        // third "nothing to say about this one" variant -- see this
        // module's own doc for the live refusal that established that.
        // Partial fidelity is not attempted; the whole property is left
        // out rather than reaching for a stand-in the schema does not
        // offer.
        let route = Route {
            uuid: None,
            name: None,
            description: None,
            distance_m: None,
            points: vec![
                RoutePoint { position: Position::new(45.515, 13.568), name: Some("Piran".to_owned()) },
                RoutePoint { position: Position::new(45.548, 13.730), name: None },
            ],
        };
        let body = write_route(&route);
        assert!(body["feature"].get("properties").is_none());
    }

    #[test]
    fn deleting_a_route_without_a_token_is_refused_before_any_request_is_made() {
        let client = Client::new("https://example.invalid".to_owned(), Trust::plaintext(), None);
        let error = client.delete_route("c0ffee00-1234-4abc-89ab-c0ffeec0ffee").unwrap_err();
        assert!(matches!(error, ClientError::Http(ref message) if message.contains("no token")));
    }

    #[test]
    fn a_listed_track_is_read_from_its_own_map_entry() {
        let value: serde_json::Value = serde_json::from_str(
            r##"{"name":"Passage to Piran","distance":9260.5,
                "feature":{"type":"Feature",
                    "geometry":{"type":"LineString","coordinates":[[13.568,45.515],[13.730,45.548]]},
                    "properties":{"color":"#3584e4","startTime":"2026-09-12T14:00:00.000Z","endTime":"2026-09-12T14:14:52.032Z"}},
                "timestamp":"2026-09-12T14:14:52.032Z","$source":"resources-provider"}"##,
        )
        .unwrap();
        let track = read_track(Some("94052456-65fa-48ce-a85d-41b78a9d2111".to_owned()), &value).unwrap();
        assert_eq!(track.uuid.as_deref(), Some("94052456-65fa-48ce-a85d-41b78a9d2111"));
        assert_eq!(track.name.as_deref(), Some("Passage to Piran"));
        assert_eq!(track.color.as_deref(), Some("#3584e4"));
        assert_eq!(track.distance_m, Some(9260.5));
        assert_eq!(track.points.len(), 2);
        assert!((track.points[0].lat_deg - 45.515).abs() < 1e-9);
        assert!((track.points[0].lon_deg - 13.568).abs() < 1e-9);
        assert_eq!(track.timestamp.as_deref(), Some("2026-09-12T14:14:52.032Z"));
        assert_eq!(track.recorded_from.as_deref(), Some("2026-09-12T14:00:00.000Z"));
        assert_eq!(track.recorded_to.as_deref(), Some("2026-09-12T14:14:52.032Z"));
    }

    #[test]
    fn a_track_with_no_geometry_is_a_protocol_error() {
        let value: serde_json::Value = serde_json::from_str(r#"{"name":"nowhere"}"#).unwrap();
        assert!(matches!(read_track(None, &value), Err(ClientError::Protocol(_))));
    }

    #[test]
    fn track_points_are_written_lon_then_lat_with_colour_in_feature_properties() {
        let track = Track {
            uuid: None,
            name: Some("Passage to Piran".to_owned()),
            description: None,
            color: Some("#3584e4".to_owned()),
            distance_m: Some(9260.5),
            points: vec![Position::new(45.515, 13.568), Position::new(45.548, 13.730)],
            timestamp: None,
            recorded_from: Some("2026-09-12T14:00:00.000Z".to_owned()),
            recorded_to: Some("2026-09-12T14:14:52.032Z".to_owned()),
        };
        let body = write_track(&track);
        assert_eq!(body["feature"]["geometry"]["coordinates"][0][0], 13.568);
        assert_eq!(body["feature"]["geometry"]["coordinates"][0][1], 45.515);
        assert_eq!(body["name"], "Passage to Piran");
        assert_eq!(body["distance"], 9260.5);
        assert_eq!(body["feature"]["properties"]["color"], "#3584e4");
        assert_eq!(body["feature"]["properties"]["startTime"], "2026-09-12T14:00:00.000Z");
        assert_eq!(body["feature"]["properties"]["endTime"], "2026-09-12T14:14:52.032Z");
        assert!(body.get("description").is_none());
    }

    #[test]
    fn a_track_with_no_colour_writes_no_properties_at_all() {
        let track = Track {
            uuid: None,
            name: None,
            description: None,
            color: None,
            distance_m: None,
            points: vec![Position::new(45.515, 13.568)],
            timestamp: None,
            recorded_from: None,
            recorded_to: None,
        };
        let body = write_track(&track);
        assert!(body["feature"].get("properties").is_none());
    }

    #[test]
    fn deleting_a_track_without_a_token_is_refused_before_any_request_is_made() {
        let client = Client::new("https://example.invalid".to_owned(), Trust::plaintext(), None);
        let error = client.delete_track("c0ffee00-1234-4abc-89ab-c0ffeec0ffee").unwrap_err();
        assert!(matches!(error, ClientError::Http(ref message) if message.contains("no token")));
    }
}