@unmap/routing 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # @unmap/routing
 
 Typed client for the [unmap](https://unmap.dev) routing API: point-to-point routes and
-travel-time isochrones over the Canadian road graph, for driving, cycling, and walking. No map
+travel-time isochrones over the Canadian road graph, for driving, trucking, cycling, and walking. No map
 dependency; works in Node and the browser.
 
 ```bash
@@ -22,7 +22,7 @@ const bands = await router.isochrone([-114.07, 51.05], { minutes: [10, 20], mode
 bands.features         // one GeoJSON polygon per minute value
 ```
 
-Coordinates are always `[lng, lat]`. `mode` is `'auto' | 'bicycle' | 'pedestrian'` and defaults
+Coordinates are always `[lng, lat]`. `mode` is `'auto' | 'car' | 'bicycle' | 'pedestrian' | 'truck'` and defaults
 to `'auto'`; `minutes` is required and takes up to four values of at most 120 minutes. Both methods accept an
 `AbortSignal` as `signal`. A non-2xx response throws a `RouterError` carrying the HTTP `status`.
 

package/dist/index.d.ts

@@ -3,9 +3,39 @@ interface RouterOptions {
     gateway?: string;
     fetch?: typeof fetch;
 }
-type TravelMode = "auto" | "bicycle" | "pedestrian";
+/** `car` is the same costing as `auto`, spelled for people who do not think in Valhalla terms. */
+type TravelMode = "auto" | "car" | "bicycle" | "pedestrian" | "truck";
 /** [longitude, latitude]. */
 type LngLat = [number, number];
+/**
+ * Vehicle profile for `mode: "truck"`. Metric throughout: metres and tonnes. Every field is
+ * optional; the gateway falls back to Valhalla's defaults (4.11 m high, 2.6 m wide, 21.64 m
+ * long, 21.77 t, 9.07 t axle load, 5 axles, no hazmat) for anything omitted.
+ */
+interface TruckProfile {
+    /** Vehicle height in metres. */
+    height?: number;
+    /** Vehicle width in metres. */
+    width?: number;
+    /** Vehicle length in metres. */
+    length?: number;
+    /** Gross vehicle weight in tonnes. */
+    weight?: number;
+    /** Load per axle in tonnes (0–40). */
+    axleLoad?: number;
+    /** Number of axles (2–20). */
+    axleCount?: number;
+    /** Carrying hazardous materials: avoids roads tagged `hazmat=no`. */
+    hazmat?: boolean;
+    /** Preference for designated truck routes, 0 (none) to 1 (strong). */
+    useTruckRoute?: number;
+}
+interface RouteOptions {
+    mode?: TravelMode;
+    /** Only meaningful with `mode: "truck"`; the gateway rejects it on any other mode. */
+    truck?: TruckProfile;
+    signal?: AbortSignal;
+}
 interface RouteResult {
     distanceMeters: number;
     durationSeconds: number;
@@ -19,14 +49,16 @@ interface FeatureCollection {
     type: "FeatureCollection";
     features: unknown[];
 }
-interface IsochroneOptions {
+interface IsochroneOptions extends RouteOptions {
     minutes: number[];
-    mode?: TravelMode;
-    signal?: AbortSignal;
 }
 declare class RouterError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    /** The gateway's machine-readable `code`, when the response carried one (e.g. `unauthorized`). */
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, 
+    /** The gateway's machine-readable `code`, when the response carried one (e.g. `unauthorized`). */
+    code?: string | undefined);
 }
 /** Typed client for the unmap routing API (gateway `/route`, `/isochrone`). */
 declare class Router {
@@ -34,12 +66,9 @@ declare class Router {
     private readonly base;
     private readonly fetchImpl;
     constructor(opts: RouterOptions);
-    route(from: LngLat, to: LngLat, opts?: {
-        mode?: TravelMode;
-        signal?: AbortSignal;
-    }): Promise<RouteResult>;
+    route(from: LngLat, to: LngLat, opts?: RouteOptions): Promise<RouteResult>;
     isochrone(center: LngLat, opts: IsochroneOptions): Promise<FeatureCollection>;
     private get;
 }
 
-export { type FeatureCollection, type IsochroneOptions, type LngLat, type RouteResult, Router, RouterError, type RouterOptions, type TravelMode };
+export { type FeatureCollection, type IsochroneOptions, type LngLat, type RouteOptions, type RouteResult, Router, RouterError, type RouterOptions, type TravelMode, type TruckProfile };

package/dist/index.js

@@ -1,13 +1,46 @@
 // src/index.ts
 import { DEFAULT_GATEWAY } from "@unmap/core";
+var TRUCK_PARAMS = {
+  height: "height",
+  width: "width",
+  length: "length",
+  weight: "weight",
+  axleLoad: "axle_load",
+  axleCount: "axle_count",
+  hazmat: "hazmat",
+  useTruckRoute: "use_truck_route"
+};
+function truckParams(truck) {
+  const out = {};
+  if (!truck) return out;
+  for (const [field, param] of Object.entries(TRUCK_PARAMS)) {
+    const v = truck[field];
+    if (v != null) out[param] = String(v);
+  }
+  return out;
+}
 var RouterError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "RouterError";
   }
   status;
+  code;
 };
+async function errorFrom(res, path) {
+  const fallback = `route ${res.status} on ${path}`;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = void 0;
+  }
+  const reason = typeof body?.error === "string" ? body.error : void 0;
+  const code = typeof body?.code === "string" ? body.code : void 0;
+  return new RouterError(res.status, reason ? `${reason} (${fallback})` : fallback, code);
+}
 var Router = class {
   key;
   base;
@@ -20,14 +53,20 @@ var Router = class {
   route(from, to, opts = {}) {
     return this.get(
       "/route",
-      { from: from.join(","), to: to.join(","), mode: opts.mode },
+      { from: from.join(","), to: to.join(","), mode: opts.mode, ...truckParams(opts.truck) },
       opts.signal
     );
   }
   isochrone(center, opts) {
     return this.get(
       "/isochrone",
-      { lon: String(center[0]), lat: String(center[1]), minutes: opts.minutes.join(","), mode: opts.mode },
+      {
+        lon: String(center[0]),
+        lat: String(center[1]),
+        minutes: opts.minutes.join(","),
+        mode: opts.mode,
+        ...truckParams(opts.truck)
+      },
       opts.signal
     );
   }
@@ -38,7 +77,7 @@ var Router = class {
       signal,
       headers: { accept: "application/json" }
     });
-    if (!res.ok) throw new RouterError(res.status, `route ${res.status} on ${path}`);
+    if (!res.ok) throw await errorFrom(res, path);
     return res.json();
   }
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DEFAULT_GATEWAY } from \"@unmap/core\";\n\nexport interface RouterOptions {\n  key: string;\n  gateway?: string;\n  fetch?: typeof fetch;\n}\n\nexport type TravelMode = \"auto\" | \"bicycle\" | \"pedestrian\";\n/** [longitude, latitude]. */\nexport type LngLat = [number, number];\n\nexport interface RouteResult {\n  distanceMeters: number;\n  durationSeconds: number;\n  geometry: { type: \"LineString\"; coordinates: LngLat[] };\n}\n\n/** Minimal GeoJSON FeatureCollection (isochrone bands). */\nexport interface FeatureCollection {\n  type: \"FeatureCollection\";\n  features: unknown[];\n}\n\nexport interface IsochroneOptions {\n  minutes: number[];\n  mode?: TravelMode;\n  signal?: AbortSignal;\n}\n\nexport class RouterError extends Error {\n  constructor(\n    public readonly status: number,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"RouterError\";\n  }\n}\n\n/** Typed client for the unmap routing API (gateway `/route`, `/isochrone`). */\nexport class Router {\n  private readonly key: string;\n  private readonly base: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(opts: RouterOptions) {\n    this.key = opts.key;\n    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\\/+$/, \"\");\n    // Bound to globalThis: stored on an instance and called as `this.fetchImpl(...)`, a bare\n    // `fetch` reference is invoked with the Router as its receiver, and browsers reject that\n    // with \"Illegal invocation\". Node is lenient, so this only ever surfaces in the browser.\n    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  route(\n    from: LngLat,\n    to: LngLat,\n    opts: { mode?: TravelMode; signal?: AbortSignal } = {},\n  ): Promise<RouteResult> {\n    return this.get<RouteResult>(\n      \"/route\",\n      { from: from.join(\",\"), to: to.join(\",\"), mode: opts.mode },\n      opts.signal,\n    );\n  }\n\n  isochrone(center: LngLat, opts: IsochroneOptions): Promise<FeatureCollection> {\n    return this.get<FeatureCollection>(\n      \"/isochrone\",\n      { lon: String(center[0]), lat: String(center[1]), minutes: opts.minutes.join(\",\"), mode: opts.mode },\n      opts.signal,\n    );\n  }\n\n  private async get<T>(\n    path: string,\n    params: Record<string, string | undefined>,\n    signal?: AbortSignal,\n  ): Promise<T> {\n    const q = new URLSearchParams({ key: this.key });\n    for (const [k, v] of Object.entries(params)) if (v != null && v !== \"\") q.set(k, v);\n    const res = await this.fetchImpl(`${this.base}${path}?${q}`, {\n      signal,\n      headers: { accept: \"application/json\" },\n    });\n    if (!res.ok) throw new RouterError(res.status, `route ${res.status} on ${path}`);\n    return res.json() as Promise<T>;\n  }\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AA8BzB,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YACkB,QAChB,SACA;AACA,UAAM,OAAO;AAHG;AAIhB,SAAK,OAAO;AAAA,EACd;AAAA,EALkB;AAMpB;AAGO,IAAM,SAAN,MAAa;AAAA,EACD;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAqB;AAC/B,SAAK,MAAM,KAAK;AAChB,SAAK,QAAQ,KAAK,WAAW,iBAAiB,QAAQ,QAAQ,EAAE;AAIhE,SAAK,YAAY,KAAK,SAAS,WAAW,MAAM,KAAK,UAAU;AAAA,EACjE;AAAA,EAEA,MACE,MACA,IACA,OAAoD,CAAC,GAC/B;AACtB,WAAO,KAAK;AAAA,MACV;AAAA,MACA,EAAE,MAAM,KAAK,KAAK,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,MAAM,KAAK,KAAK;AAAA,MAC1D,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,UAAU,QAAgB,MAAoD;AAC5E,WAAO,KAAK;AAAA,MACV;AAAA,MACA,EAAE,KAAK,OAAO,OAAO,CAAC,CAAC,GAAG,KAAK,OAAO,OAAO,CAAC,CAAC,GAAG,SAAS,KAAK,QAAQ,KAAK,GAAG,GAAG,MAAM,KAAK,KAAK;AAAA,MACnG,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,MAAc,IACZ,MACA,QACA,QACY;AACZ,UAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAK,IAAI,CAAC;AAC/C,eAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,MAAM,EAAG,KAAI,KAAK,QAAQ,MAAM,GAAI,GAAE,IAAI,GAAG,CAAC;AAClF,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI;AAAA,MAC3D;AAAA,MACA,SAAS,EAAE,QAAQ,mBAAmB;AAAA,IACxC,CAAC;AACD,QAAI,CAAC,IAAI,GAAI,OAAM,IAAI,YAAY,IAAI,QAAQ,SAAS,IAAI,MAAM,OAAO,IAAI,EAAE;AAC/E,WAAO,IAAI,KAAK;AAAA,EAClB;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DEFAULT_GATEWAY } from \"@unmap/core\";\n\nexport interface RouterOptions {\n  key: string;\n  gateway?: string;\n  fetch?: typeof fetch;\n}\n\n/** `car` is the same costing as `auto`, spelled for people who do not think in Valhalla terms. */\nexport type TravelMode = \"auto\" | \"car\" | \"bicycle\" | \"pedestrian\" | \"truck\";\n/** [longitude, latitude]. */\nexport type LngLat = [number, number];\n\n/**\n * Vehicle profile for `mode: \"truck\"`. Metric throughout: metres and tonnes. Every field is\n * optional; the gateway falls back to Valhalla's defaults (4.11 m high, 2.6 m wide, 21.64 m\n * long, 21.77 t, 9.07 t axle load, 5 axles, no hazmat) for anything omitted.\n */\nexport interface TruckProfile {\n  /** Vehicle height in metres. */\n  height?: number;\n  /** Vehicle width in metres. */\n  width?: number;\n  /** Vehicle length in metres. */\n  length?: number;\n  /** Gross vehicle weight in tonnes. */\n  weight?: number;\n  /** Load per axle in tonnes (0–40). */\n  axleLoad?: number;\n  /** Number of axles (2–20). */\n  axleCount?: number;\n  /** Carrying hazardous materials: avoids roads tagged `hazmat=no`. */\n  hazmat?: boolean;\n  /** Preference for designated truck routes, 0 (none) to 1 (strong). */\n  useTruckRoute?: number;\n}\n\nexport interface RouteOptions {\n  mode?: TravelMode;\n  /** Only meaningful with `mode: \"truck\"`; the gateway rejects it on any other mode. */\n  truck?: TruckProfile;\n  signal?: AbortSignal;\n}\n\n/** `TruckProfile` field → the gateway's snake_case query parameter. */\nconst TRUCK_PARAMS: Record<keyof TruckProfile, string> = {\n  height: \"height\",\n  width: \"width\",\n  length: \"length\",\n  weight: \"weight\",\n  axleLoad: \"axle_load\",\n  axleCount: \"axle_count\",\n  hazmat: \"hazmat\",\n  useTruckRoute: \"use_truck_route\",\n};\n\nfunction truckParams(truck?: TruckProfile): Record<string, string | undefined> {\n  const out: Record<string, string | undefined> = {};\n  if (!truck) return out;\n  for (const [field, param] of Object.entries(TRUCK_PARAMS) as [keyof TruckProfile, string][]) {\n    const v = truck[field];\n    if (v != null) out[param] = String(v);\n  }\n  return out;\n}\n\nexport interface RouteResult {\n  distanceMeters: number;\n  durationSeconds: number;\n  geometry: { type: \"LineString\"; coordinates: LngLat[] };\n}\n\n/** Minimal GeoJSON FeatureCollection (isochrone bands). */\nexport interface FeatureCollection {\n  type: \"FeatureCollection\";\n  features: unknown[];\n}\n\nexport interface IsochroneOptions extends RouteOptions {\n  minutes: number[];\n}\n\nexport class RouterError extends Error {\n  constructor(\n    public readonly status: number,\n    message: string,\n    /** The gateway's machine-readable `code`, when the response carried one (e.g. `unauthorized`). */\n    public readonly code?: string,\n  ) {\n    super(message);\n    this.name = \"RouterError\";\n  }\n}\n\n/**\n * The gateway answers every error with a JSON body whose `error` says what went wrong\n * (\"mode must be one of auto, car, bicycle, pedestrian, truck\", \"q required\"). Put that in the\n * message so a caller who logs the thrown error reads the reason, not just the status.\n */\nasync function errorFrom(res: { status: number; json(): Promise<unknown> }, path: string): Promise<RouterError> {\n  const fallback = `route ${res.status} on ${path}`;\n  let body: { error?: unknown; code?: unknown } | undefined;\n  try {\n    body = (await res.json()) as { error?: unknown; code?: unknown };\n  } catch {\n    body = undefined;\n  }\n  const reason = typeof body?.error === \"string\" ? body.error : undefined;\n  const code = typeof body?.code === \"string\" ? body.code : undefined;\n  return new RouterError(res.status, reason ? `${reason} (${fallback})` : fallback, code);\n}\n\n/** Typed client for the unmap routing API (gateway `/route`, `/isochrone`). */\nexport class Router {\n  private readonly key: string;\n  private readonly base: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(opts: RouterOptions) {\n    this.key = opts.key;\n    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\\/+$/, \"\");\n    // Bound to globalThis: stored on an instance and called as `this.fetchImpl(...)`, a bare\n    // `fetch` reference is invoked with the Router as its receiver, and browsers reject that\n    // with \"Illegal invocation\". Node is lenient, so this only ever surfaces in the browser.\n    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  route(from: LngLat, to: LngLat, opts: RouteOptions = {}): Promise<RouteResult> {\n    return this.get<RouteResult>(\n      \"/route\",\n      { from: from.join(\",\"), to: to.join(\",\"), mode: opts.mode, ...truckParams(opts.truck) },\n      opts.signal,\n    );\n  }\n\n  isochrone(center: LngLat, opts: IsochroneOptions): Promise<FeatureCollection> {\n    return this.get<FeatureCollection>(\n      \"/isochrone\",\n      {\n        lon: String(center[0]),\n        lat: String(center[1]),\n        minutes: opts.minutes.join(\",\"),\n        mode: opts.mode,\n        ...truckParams(opts.truck),\n      },\n      opts.signal,\n    );\n  }\n\n  private async get<T>(\n    path: string,\n    params: Record<string, string | undefined>,\n    signal?: AbortSignal,\n  ): Promise<T> {\n    const q = new URLSearchParams({ key: this.key });\n    for (const [k, v] of Object.entries(params)) if (v != null && v !== \"\") q.set(k, v);\n    const res = await this.fetchImpl(`${this.base}${path}?${q}`, {\n      signal,\n      headers: { accept: \"application/json\" },\n    });\n    if (!res.ok) throw await errorFrom(res, path);\n    return res.json() as Promise<T>;\n  }\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AA6ChC,IAAM,eAAmD;AAAA,EACvD,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,eAAe;AACjB;AAEA,SAAS,YAAY,OAA0D;AAC7E,QAAM,MAA0C,CAAC;AACjD,MAAI,CAAC,MAAO,QAAO;AACnB,aAAW,CAAC,OAAO,KAAK,KAAK,OAAO,QAAQ,YAAY,GAAqC;AAC3F,UAAM,IAAI,MAAM,KAAK;AACrB,QAAI,KAAK,KAAM,KAAI,KAAK,IAAI,OAAO,CAAC;AAAA,EACtC;AACA,SAAO;AACT;AAkBO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YACkB,QAChB,SAEgB,MAChB;AACA,UAAM,OAAO;AALG;AAGA;AAGhB,SAAK,OAAO;AAAA,EACd;AAAA,EAPkB;AAAA,EAGA;AAKpB;AAOA,eAAe,UAAU,KAAmD,MAAoC;AAC9G,QAAM,WAAW,SAAS,IAAI,MAAM,OAAO,IAAI;AAC/C,MAAI;AACJ,MAAI;AACF,WAAQ,MAAM,IAAI,KAAK;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,SAAS,OAAO,MAAM,UAAU,WAAW,KAAK,QAAQ;AAC9D,QAAM,OAAO,OAAO,MAAM,SAAS,WAAW,KAAK,OAAO;AAC1D,SAAO,IAAI,YAAY,IAAI,QAAQ,SAAS,GAAG,MAAM,KAAK,QAAQ,MAAM,UAAU,IAAI;AACxF;AAGO,IAAM,SAAN,MAAa;AAAA,EACD;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAqB;AAC/B,SAAK,MAAM,KAAK;AAChB,SAAK,QAAQ,KAAK,WAAW,iBAAiB,QAAQ,QAAQ,EAAE;AAIhE,SAAK,YAAY,KAAK,SAAS,WAAW,MAAM,KAAK,UAAU;AAAA,EACjE;AAAA,EAEA,MAAM,MAAc,IAAY,OAAqB,CAAC,GAAyB;AAC7E,WAAO,KAAK;AAAA,MACV;AAAA,MACA,EAAE,MAAM,KAAK,KAAK,GAAG,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,MAAM,KAAK,MAAM,GAAG,YAAY,KAAK,KAAK,EAAE;AAAA,MACtF,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,UAAU,QAAgB,MAAoD;AAC5E,WAAO,KAAK;AAAA,MACV;AAAA,MACA;AAAA,QACE,KAAK,OAAO,OAAO,CAAC,CAAC;AAAA,QACrB,KAAK,OAAO,OAAO,CAAC,CAAC;AAAA,QACrB,SAAS,KAAK,QAAQ,KAAK,GAAG;AAAA,QAC9B,MAAM,KAAK;AAAA,QACX,GAAG,YAAY,KAAK,KAAK;AAAA,MAC3B;AAAA,MACA,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,MAAc,IACZ,MACA,QACA,QACY;AACZ,UAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAK,IAAI,CAAC;AAC/C,eAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,MAAM,EAAG,KAAI,KAAK,QAAQ,MAAM,GAAI,GAAE,IAAI,GAAG,CAAC;AAClF,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI;AAAA,MAC3D;AAAA,MACA,SAAS,EAAE,QAAQ,mBAAmB;AAAA,IACxC,CAAC;AACD,QAAI,CAAC,IAAI,GAAI,OAAM,MAAM,UAAU,KAAK,IAAI;AAC5C,WAAO,IAAI,KAAK;AAAA,EAClB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unmap/routing",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Typed client for the unmap routing API (route + isochrone)",
   "license": "MIT",
   "keywords": [
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@unmap/core": "0.3.0"
+    "@unmap/core": "0.5.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",