import os
import time
import requests

HOST = "https://router.hereapi.com/v8/routes"
API_KEY = os.environ["HERE_API_KEY"]


class EntitlementError(Exception):
    """403 — valid key, missing entitlement. Never retry."""


class NoRouteError(Exception):
    """HTTP 200, empty routes. A legitimate outcome."""


def car_route(
    origin: str,          # "lat,lng"
    destination: str,     # "lat,lng"
    departure_time: str | None = None,  # ISO 8601, or None for now
    retries: int = 3,
) -> dict:
    """
    Calculate a passenger-car route.

    `return` is set explicitly. Requesting `polyline,actions,instructions`
    when you consume only a duration inflates the payload by orders of magnitude.
    """
    params = {
        "transportMode": "car",
        "origin": origin,               # lat,lng — NOT lng,lat
        "destination": destination,
        "return": "summary,polyline",   # Explicit. Always.
        "apiKey": API_KEY,
    }
    if departure_time:
        # Traffic is evaluated at this time, not at request time.
        # A route computed at 2pm for a 6pm departure inherits 2pm traffic
        # unless you say otherwise.
        params["departureTime"] = departure_time

    backoff = 1.0
    for _ in range(retries):
        resp = requests.get(HOST, params=params, timeout=15)

        if resp.status_code == 403:
            raise EntitlementError("Routing not entitled for this key")
        if resp.status_code in (429,) or resp.status_code >= 500:
            time.sleep(backoff)
            backoff *= 2
            continue

        resp.raise_for_status()
        break
    else:
        raise RuntimeError("Routing failed after retries")

    body = resp.json()

    # CRITICAL: HTTP 200 does not mean a route was found.
    routes = body.get("routes", [])
    if not routes:
        notices = body.get("notice", [])
        raise NoRouteError(f"No route: {notices}")

    section = routes[0]["sections"][0]
    return {
        "duration_s": section["summary"]["duration"],
        "length_m": section["summary"]["length"],
        "polyline": section.get("polyline"),
    }


if __name__ == "__main__":
    try:
        r = car_route("41.8845,-87.6386", "41.9028,-87.6317")
        print(f"{r['duration_s']}s over {r['length_m']}m")
    except NoRouteError as e:
        print(f"Unroutable: {e}")   # Do NOT retry
    except EntitlementError as e:
        print(f"Licensing: {e}")    # Do NOT retry

const HOST = "https://router.hereapi.com/v8/routes";
const API_KEY = process.env.HERE_API_KEY;

class EntitlementError extends Error {}
class NoRouteError extends Error {}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function carRoute(origin, destination, { departureTime, retries = 3 } = {}) {
  const params = new URLSearchParams({
    transportMode: "car",
    origin,                        // "lat,lng"
    destination,
    return: "summary,polyline",    // Explicit
    apiKey: API_KEY,
  });
  if (departureTime) params.set("departureTime", departureTime);

  let backoff = 1000;
  let resp;

  for (let i = 0; i < retries; i++) {
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), 15_000);
    try {
      resp = await fetch(`${HOST}?${params}`, { signal: ctrl.signal });
    } finally {
      clearTimeout(timer);
    }

    if (resp.status === 403) throw new EntitlementError("Routing not entitled");
    if (resp.status === 429 || resp.status >= 500) {
      await sleep(backoff + Math.random() * 250);
      backoff *= 2;
      continue;
    }
    if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);
    break;
  }

  const body = await resp.json();

  // HTTP 200 with an empty routes array is a valid response.
  if (!body.routes?.length) {
    throw new NoRouteError(JSON.stringify(body.notice ?? []));
  }

  const { summary, polyline } = body.routes[0].sections[0];
  return { durationS: summary.duration, lengthM: summary.length, polyline };
}

curl -gX GET 'https://router.hereapi.com/v8/routes' \
  --data-urlencode 'transportMode=car' \
  --data-urlencode 'origin=41.8845,-87.6386' \
  --data-urlencode 'destination=41.9028,-87.6317' \
  --data-urlencode 'return=summary,polyline' \
  --data-urlencode "apiKey=${HERE_API_KEY}" \
  -G