import os
import io
import time
import csv
import requests

HOST = "https://routematching.hereapi.com/v8/match/routelinks"
API_KEY = os.environ["HERE_API_KEY"]

# Below this, the matched link is a guess. Surface it; do not persist as fact.
MIN_CONFIDENCE = 0.6


class EntitlementError(Exception): ...


def trace_to_csv(points: list[dict]) -> str:
    """
    points: [{"lat": .., "lon": .., "timestamp": epoch_ms, "speedMps": ..}, ...]
    Points MUST be in temporal order. A trace is a sequence, not a set.
    """
    buf = io.StringIO()
    w = csv.writer(buf)
    w.writerow(["latitude", "longitude", "timestamp", "speedMps"])
    for p in points:
        w.writerow([p["lat"], p["lon"], p.get("timestamp", 0), p.get("speedMps", 0)])
    return buf.getvalue()


def match_trace(csv_body: str, mode: str = "fastest;truck;traffic:disabled") -> dict:
    """
    Map-match a GPS trace to road links.

    `routeMatch=1` requests a fully drivable, gap-free route path.
    `legal=...` requests warnings for traffic-rule violations along the match.
    """
    params = {
        "routeMatch": 1,
        "mode": mode,
        # Warn on access restrictions, one-ways, through-traffic, illegal turns.
        "legal": "access,oneway,thrutraf,turn",
        "apiKey": API_KEY,
    }

    backoff = 2.0
    for _ in range(3):
        resp = requests.post(
            HOST, params=params,
            data=csv_body.encode("utf-8"),
            headers={"Content-Type": "text/plain"},
            # HERE cancels waypoint requests exceeding ~50s of computation.
            timeout=70,
        )
        if resp.status_code == 403:
            raise EntitlementError("Route Matching not entitled")
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(backoff); backoff *= 2; continue
        resp.raise_for_status()
        break
    else:
        raise RuntimeError("Route matching failed after retries")

    return resp.json()


def audit_artifact(raw_points: list[dict], response: dict) -> dict:
    """
    THE thing you must be able to produce for a regulator.

    Matched output is a DERIVATION. Keep the source, and record the map
    version that produced it — a trip matched in March against a March map
    may match differently in September. Both can be correct.
    """
    trace_points = response.get("TracePoints", [])
    low_conf = [
        tp for tp in trace_points
        if tp.get("confidenceValue", 0) < MIN_CONFIDENCE
    ]
    return {
        "raw_trace": raw_points,                        # immutable source
        "route_links": response.get("RouteLinks", []),  # the segments driven
        "map_version": response.get("MapVersion"),      # ← cite this
        "matched_at": int(time.time()),
        "warnings": response.get("Warnings", []),
        "low_confidence_count": len(low_conf),
    }


if __name__ == "__main__":
    points = [
        {"lat": 50.4552744, "lon": 30.5213118, "timestamp": 1479954513000, "speedMps": 10.7},
        {"lat": 50.4550313, "lon": 30.5205023, "timestamp": 1479954523000, "speedMps": 11.1},
        # ... a full trip, segmented and downsampled BEFORE submission
    ]
    resp = match_trace(trace_to_csv(points))
    artifact = audit_artifact(points, resp)

    print(f"Matched against map version {artifact['map_version']}")
    print(f"{len(artifact['route_links'])} road links")
    if artifact["low_confidence_count"]:
        print(f"⚠ {artifact['low_confidence_count']} low-confidence points — review")

const HOST = "https://routematching.hereapi.com/v8/match/routelinks";
const API_KEY = process.env.HERE_API_KEY;
const MIN_CONFIDENCE = 0.6;

class EntitlementError extends Error {}

function traceToCsv(points) {
  const header = "latitude,longitude,timestamp,speedMps";
  const rows = points.map(
    (p) => `${p.lat},${p.lon},${p.timestamp ?? 0},${p.speedMps ?? 0}`
  );
  return [header, ...rows].join("\n");
}

export async function matchTrace(csvBody, mode = "fastest;truck;traffic:disabled") {
  const params = new URLSearchParams({
    routeMatch: "1",
    mode,
    legal: "access,oneway,thrutraf,turn",
    apiKey: API_KEY,
  });

  const ctrl = new AbortController();
  const t = setTimeout(() => ctrl.abort(), 70_000); // HERE cancels around 50s

  let resp;
  try {
    resp = await fetch(`${HOST}?${params}`, {
      method: "POST",
      headers: { "Content-Type": "text/plain" },
      body: csvBody,
      signal: ctrl.signal,
    });
  } finally {
    clearTimeout(t);
  }

  if (resp.status === 403) throw new EntitlementError("Route Matching not entitled");
  if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);

  return resp.json();
}

/** Persist all four. Anything less is an assertion, not an artifact. */
export function auditArtifact(rawPoints, response) {
  const lowConf = (response.TracePoints ?? [])
    .filter((tp) => (tp.confidenceValue ?? 0) < MIN_CONFIDENCE);

  return {
    rawTrace: rawPoints,
    routeLinks: response.RouteLinks ?? [],
    mapVersion: response.MapVersion,   // cite this in any dispute
    matchedAt: Date.now(),
    warnings: response.Warnings ?? [],
    lowConfidenceCount: lowConf.length,
  };
}

# Trace as request body. GPX, NMEA, CSV, or JSON.
curl -X POST \
  --data-binary "@trip-2026-07-09.csv" \
  -H "Content-Type: text/plain" \
  "https://routematching.hereapi.com/v8/match/routelinks?\
routeMatch=1&\
mode=fastest;truck;traffic:disabled&\
legal=access,oneway,thrutraf,turn&\
apiKey=${HERE_API_KEY}"