@jsm-mit/map-routes-package 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @jsm-mit/map-routes-package
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The package of map-routes: the fastest route by car through 2–5 points, with the line of each
+leg, from the `map-routes-rust` canister — an OpenStreetMap road graph of
+Nordrhein-Westfalen (© OpenStreetMap contributors, ODbL) inside an Internet Computer
+canister. The canister answers anyone (anonymous queries, no cost to the caller).
+Not published under this name yet: 0.1.0 was published as `@jsm-mit/tigi-map-package`.
+
+```ts
+import { errorKeyOf, isTimeoutError, MapRoutesActor } from "@jsm-mit/map-routes-package";
+
+const map = new MapRoutesActor();                    // mainnet, MAP_ROUTES_CANISTER_ID
+const route = await map.routeAsyncUnsafe(
+    [me, pickup, destination],                     // { lat, lng }, 2..=5 points
+    { line: true, timeoutMs: 5_000 },
+);
+// route.legs[i]: { meters, seconds, line? }       line = encoded polyline, precision 5 (as ORS)
+// route.snapMeters, route.osmDate, route.graphSha256
+```
+
+Errors: `CanisterError` with `errorKeyOf(error)` = `OutsideArea` (a point farther than
+1 km from a road of the map — e.g. outside NRW), `NoRoute`, `NotReady` (no graph yet, or
+one of an older format right after an upgrade), `InvalidData`; `Timeout`
+(`isTimeoutError`); `CriticalCanisterError` (transport). A stopped canister (an upgrade
+runs, IC0508/IC0509) is waited out within the time limit.
+
+Local replica: `new MapRoutesActor(localId, { host: "http://127.0.0.1:4943" })`.
+
+## Scripts
+
+- `npm run test-unit` — no canister.
+- `npm run test-smoke` — the canister from this tree on the LOCAL replica (deploys it,
+  uploads the newest `data/*.tmc` when the active graph differs).
+- `npm run sync-declarations` — `declarations/map-routes/` from `../map-routes-rust.did`.
+- `npm run publish-public` — human-run; see the script for its refusals.

package/declarations/map-routes/map-routes.did

@@ -0,0 +1,93 @@
+type BeginUploadArgs = record {
+  // sha256 (hex) of the graph file.
+  sha256 : text;
+  // Bytes of the graph file (`map-routes-build build` output, format TMC3).
+  size : nat64;
+  osmDate : text;
+};
+type BufferInfo = record {
+  sha256 : text;
+  size : nat64;
+  startedAtNs : nat64;
+  state : BufferState;
+  buffer : nat8;
+  osmDate : text;
+};
+type BufferState = variant { Uploading; Active; Ready };
+// The fastest route by car between two points.
+type Distance = record {
+  meters : nat64;
+  snapToMeters : nat32;
+  seconds : nat64;
+  // Instructions this query took (measurement of the PoC).
+  instructions : nat64;
+  // sha256 (hex) of the graph, as printed by `map-routes-build build`.
+  graphSha256 : text;
+  // Date of the OpenStreetMap extract the graph was built from.
+  osmDate : text;
+  // How far each point lies from the junction the route starts or ends at.
+  snapFromMeters : nat32;
+};
+type DistanceArgs = record { to : Point; from : Point };
+type Error = variant {
+  // No road within `MAX_SNAP_M` of the point named ("from" / "to" / "points[i]").
+  OutsideArea : text;
+  // No graph is active yet, or the active one is of an older format.
+  NotReady;
+  NotFound;
+  NotAuthorized : text;
+  NoRoute;
+  InvalidData : text;
+};
+// The fastest route from one point of a `route` query to the next.
+type Leg = record {
+  meters : nat64;
+  // Encoded polyline of precision 5 (as ORS sends it), from the junction the leg starts
+  // at to the one it ends at; "" when the line was not asked for.
+  line : text;
+  seconds : nat64;
+};
+type Point = record { lat : float64; lon : float64 };
+type Result = variant { Ok : BufferInfo; Err : Error };
+type Result_1 = variant { Ok : Distance; Err : Error };
+type Result_2 = variant { Ok : Status; Err : Error };
+type Result_3 = variant { Ok : RouteAnswer; Err : Error };
+type Result_4 = variant { Ok; Err : Error };
+type RouteAnswer = record {
+  // How far each point lies from the junction its legs start or end at.
+  snapMeters : vec nat32;
+  // One leg for each pair of consecutive points.
+  legs : vec Leg;
+  instructions : nat64;
+  graphSha256 : text;
+  osmDate : text;
+};
+type RouteArgs = record {
+  // Whether each leg carries its line.
+  line : bool;
+  // 2..=`MAX_ROUTE_POINTS` points, driven in this order.
+  points : vec Point;
+};
+type Status = record {
+  stableBytes : nat64;
+  heapBytes : nat64;
+  // Nodes of the graph that answers `distance`; 0 when none is active.
+  nodes : nat64;
+  buffers : vec BufferInfo;
+};
+type UploadChunkArgs = record { offset : nat64; bytes : blob };
+service : () -> {
+  // Switches `distance` to the inactive buffer — a new graph, or back to the previous one.
+  activate : () -> (Result);
+  // Starts an upload into the inactive buffer; whatever was there is dropped.
+  beginUpload : (BeginUploadArgs) -> (Result);
+  // Checks the hash and the header of the uploaded graph; the buffer becomes Ready.
+  commitUpload : () -> (Result);
+  // The fastest route by car from one point to another. Public.
+  distance : (DistanceArgs) -> (Result_1) query;
+  getStatus : () -> (Result_2) query;
+  // The fastest route by car through 2..=5 points, leg by leg, with each leg's line when
+  // asked. Public.
+  route : (RouteArgs) -> (Result_3) query;
+  uploadChunk : (UploadChunkArgs) -> (Result_4);
+}

package/declarations/map-routes/map-routes.did.d.ts

@@ -0,0 +1,153 @@
+import type { Principal } from '@icp-sdk/core/principal';
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+
+export interface BeginUploadArgs {
+  /**
+   * sha256 (hex) of the graph file.
+   */
+  'sha256' : string,
+  /**
+   * Bytes of the graph file (`map-routes-build build` output, format TMC3).
+   */
+  'size' : bigint,
+  'osmDate' : string,
+}
+export interface BufferInfo {
+  'sha256' : string,
+  'size' : bigint,
+  'startedAtNs' : bigint,
+  'state' : BufferState,
+  'buffer' : number,
+  'osmDate' : string,
+}
+export type BufferState = { 'Uploading' : null } |
+  { 'Active' : null } |
+  { 'Ready' : null };
+/**
+ * The fastest route by car between two points.
+ */
+export interface Distance {
+  'meters' : bigint,
+  'snapToMeters' : number,
+  'seconds' : bigint,
+  /**
+   * Instructions this query took (measurement of the PoC).
+   */
+  'instructions' : bigint,
+  /**
+   * sha256 (hex) of the graph, as printed by `map-routes-build build`.
+   */
+  'graphSha256' : string,
+  /**
+   * Date of the OpenStreetMap extract the graph was built from.
+   */
+  'osmDate' : string,
+  /**
+   * How far each point lies from the junction the route starts or ends at.
+   */
+  'snapFromMeters' : number,
+}
+export interface DistanceArgs { 'to' : Point, 'from' : Point }
+export type Error = {
+    /**
+     * No road within `MAX_SNAP_M` of the point named ("from" / "to" / "points[i]").
+     */
+    'OutsideArea' : string
+  } |
+  {
+    /**
+     * No graph is active yet, or the active one is of an older format.
+     */
+    'NotReady' : null
+  } |
+  { 'NotFound' : null } |
+  { 'NotAuthorized' : string } |
+  { 'NoRoute' : null } |
+  { 'InvalidData' : string };
+/**
+ * The fastest route from one point of a `route` query to the next.
+ */
+export interface Leg {
+  'meters' : bigint,
+  /**
+   * Encoded polyline of precision 5 (as ORS sends it), from the junction the leg starts
+   * at to the one it ends at; "" when the line was not asked for.
+   */
+  'line' : string,
+  'seconds' : bigint,
+}
+export interface Point { 'lat' : number, 'lon' : number }
+export type Result = { 'Ok' : BufferInfo } |
+  { 'Err' : Error };
+export type Result_1 = { 'Ok' : Distance } |
+  { 'Err' : Error };
+export type Result_2 = { 'Ok' : Status } |
+  { 'Err' : Error };
+export type Result_3 = { 'Ok' : RouteAnswer } |
+  { 'Err' : Error };
+export type Result_4 = { 'Ok' : null } |
+  { 'Err' : Error };
+export interface RouteAnswer {
+  /**
+   * How far each point lies from the junction its legs start or end at.
+   */
+  'snapMeters' : Uint32Array | number[],
+  /**
+   * One leg for each pair of consecutive points.
+   */
+  'legs' : Array<Leg>,
+  'instructions' : bigint,
+  'graphSha256' : string,
+  'osmDate' : string,
+}
+export interface RouteArgs {
+  /**
+   * Whether each leg carries its line.
+   */
+  'line' : boolean,
+  /**
+   * 2..=`MAX_ROUTE_POINTS` points, driven in this order.
+   */
+  'points' : Array<Point>,
+}
+export interface Status {
+  'stableBytes' : bigint,
+  'heapBytes' : bigint,
+  /**
+   * Nodes of the graph that answers `distance`; 0 when none is active.
+   */
+  'nodes' : bigint,
+  'buffers' : Array<BufferInfo>,
+}
+export interface UploadChunkArgs {
+  'offset' : bigint,
+  'bytes' : Uint8Array | number[],
+}
+export interface _SERVICE {
+  /**
+   * Switches `distance` to the inactive buffer — a new graph, or back to the previous one.
+   */
+  'activate' : ActorMethod<[], Result>,
+  /**
+   * Starts an upload into the inactive buffer; whatever was there is dropped.
+   */
+  'beginUpload' : ActorMethod<[BeginUploadArgs], Result>,
+  /**
+   * Checks the hash and the header of the uploaded graph; the buffer becomes Ready.
+   */
+  'commitUpload' : ActorMethod<[], Result>,
+  /**
+   * The fastest route by car from one point to another. Public.
+   */
+  'distance' : ActorMethod<[DistanceArgs], Result_1>,
+  'getStatus' : ActorMethod<[], Result_2>,
+  /**
+   * The fastest route by car through 2..=5 points, leg by leg, with each leg's line when
+   * asked. Public.
+   */
+  'route' : ActorMethod<[RouteArgs], Result_3>,
+  'uploadChunk' : ActorMethod<[UploadChunkArgs], Result_4>,
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

package/declarations/map-routes/map-routes.did.js

@@ -0,0 +1,80 @@
+export const idlFactory = ({ IDL }) => {
+  const BufferState = IDL.Variant({
+    'Uploading' : IDL.Null,
+    'Active' : IDL.Null,
+    'Ready' : IDL.Null,
+  });
+  const BufferInfo = IDL.Record({
+    'sha256' : IDL.Text,
+    'size' : IDL.Nat64,
+    'startedAtNs' : IDL.Nat64,
+    'state' : BufferState,
+    'buffer' : IDL.Nat8,
+    'osmDate' : IDL.Text,
+  });
+  const Error = IDL.Variant({
+    'OutsideArea' : IDL.Text,
+    'NotReady' : IDL.Null,
+    'NotFound' : IDL.Null,
+    'NotAuthorized' : IDL.Text,
+    'NoRoute' : IDL.Null,
+    'InvalidData' : IDL.Text,
+  });
+  const Result = IDL.Variant({ 'Ok' : BufferInfo, 'Err' : Error });
+  const BeginUploadArgs = IDL.Record({
+    'sha256' : IDL.Text,
+    'size' : IDL.Nat64,
+    'osmDate' : IDL.Text,
+  });
+  const Point = IDL.Record({ 'lat' : IDL.Float64, 'lon' : IDL.Float64 });
+  const DistanceArgs = IDL.Record({ 'to' : Point, 'from' : Point });
+  const Distance = IDL.Record({
+    'meters' : IDL.Nat64,
+    'snapToMeters' : IDL.Nat32,
+    'seconds' : IDL.Nat64,
+    'instructions' : IDL.Nat64,
+    'graphSha256' : IDL.Text,
+    'osmDate' : IDL.Text,
+    'snapFromMeters' : IDL.Nat32,
+  });
+  const Result_1 = IDL.Variant({ 'Ok' : Distance, 'Err' : Error });
+  const Status = IDL.Record({
+    'stableBytes' : IDL.Nat64,
+    'heapBytes' : IDL.Nat64,
+    'nodes' : IDL.Nat64,
+    'buffers' : IDL.Vec(BufferInfo),
+  });
+  const Result_2 = IDL.Variant({ 'Ok' : Status, 'Err' : Error });
+  const RouteArgs = IDL.Record({
+    'line' : IDL.Bool,
+    'points' : IDL.Vec(Point),
+  });
+  const Leg = IDL.Record({
+    'meters' : IDL.Nat64,
+    'line' : IDL.Text,
+    'seconds' : IDL.Nat64,
+  });
+  const RouteAnswer = IDL.Record({
+    'snapMeters' : IDL.Vec(IDL.Nat32),
+    'legs' : IDL.Vec(Leg),
+    'instructions' : IDL.Nat64,
+    'graphSha256' : IDL.Text,
+    'osmDate' : IDL.Text,
+  });
+  const Result_3 = IDL.Variant({ 'Ok' : RouteAnswer, 'Err' : Error });
+  const UploadChunkArgs = IDL.Record({
+    'offset' : IDL.Nat64,
+    'bytes' : IDL.Vec(IDL.Nat8),
+  });
+  const Result_4 = IDL.Variant({ 'Ok' : IDL.Null, 'Err' : Error });
+  return IDL.Service({
+    'activate' : IDL.Func([], [Result], []),
+    'beginUpload' : IDL.Func([BeginUploadArgs], [Result], []),
+    'commitUpload' : IDL.Func([], [Result], []),
+    'distance' : IDL.Func([DistanceArgs], [Result_1], ['query']),
+    'getStatus' : IDL.Func([], [Result_2], ['query']),
+    'route' : IDL.Func([RouteArgs], [Result_3], ['query']),
+    'uploadChunk' : IDL.Func([UploadChunkArgs], [Result_4], []),
+  });
+};
+export const init = ({ IDL }) => { return []; };

package/dist/canister-actor.d.ts

@@ -0,0 +1,58 @@
+import { type ActorSubclass } from "@icp-sdk/core/agent";
+import type { IDL } from "@icp-sdk/core/candid";
+export interface MapRoutesOptions {
+    /**
+     * The gateway or replica to talk to. Default: mainnet (`https://icp0.io`). Pass a local
+     * replica (`http://127.0.0.1:4943`) for runs that must not touch mainnet. For a local
+     * host — and only then — the agent fetches the replica's root key.
+     */
+    host?: string;
+}
+export declare const MAINNET_HOST = "https://icp0.io";
+/** True for a replica on this machine: localhost, *.localhost, 127.0.0.1 or [::1]. */
+export declare function isLocalHost(host: string): boolean;
+export declare function rawActorAsync<S>(idlFactory: IDL.InterfaceFactory, canisterId: string, options: MapRoutesOptions): Promise<ActorSubclass<S>>;
+/**
+ * A canister that is stopped or stopping — an upgrade of it runs — refuses every call with
+ * IC0508 / IC0509. The call did NOT run, so it is tried again: doubling pauses from
+ * `STOPPED_RETRY_FIRST_DELAY_MS`, at most `STOPPED_RETRY_MAX_FACTOR` times it, each 0.5–1.5
+ * of its length at random, `STOPPED_RETRY_ATTEMPTS` tries in all: about a minute — unless
+ * the time limit of the call ends first.
+ */
+export declare const STOPPED_RETRY_FIRST_DELAY_MS = 1000;
+export declare const STOPPED_RETRY_MAX_FACTOR = 8;
+export declare const STOPPED_RETRY_ATTEMPTS = 10;
+/** True for the refusal of a stopped or stopping canister. */
+export declare function isCanisterStoppedError(error: unknown): boolean;
+/** The wait before try `attempt + 1`: doubling, capped, 0.5–1.5 of it at random. */
+export declare function stoppedRetryDelayMs(attempt: number, firstDelayMs?: number): number;
+/** Tests shorten the waits. */
+export declare const retrySettings: {
+    stoppedFirstDelayMs: number;
+    stoppedAttempts: number;
+};
+export declare function waitOutStoppedAsync<T>(fnAsync: () => Promise<T>): Promise<T>;
+/** The error of a call that did not answer within its time limit. */
+export declare function timeoutError(timeoutMs: number): Error;
+export declare function isTimeoutError(error: unknown): boolean;
+/**
+ * The call, or `Timeout` after `timeoutMs` (none when undefined). The call itself goes on
+ * (a query cannot be called back); its late answer is dropped.
+ */
+export declare function withTimeoutAsync<T>(fnAsync: () => Promise<T>, timeoutMs: number | undefined): Promise<T>;
+export type RustResult<T> = {
+    Ok: T;
+} | {
+    Err: Record<string, unknown>;
+};
+/**
+ * `{ Ok: T }` resolves with `T`; `{ Err }` is thrown as `Error("CanisterError", { cause:
+ * { errorKey, errorMessage } })` with the variant's name as the errorKey (`OutsideArea`,
+ * `NoRoute`, `NotReady`, `InvalidData`); any transport failure as
+ * `Error("CriticalCanisterError", { cause: { rawError } })`. A stopped canister is waited
+ * out first.
+ */
+export declare function executeRustAsyncUnsafe<T>(fnAsync: () => Promise<RustResult<T>>): Promise<T>;
+/** The errorKey of a `CanisterError`, or undefined for any other error. */
+export declare function errorKeyOf(error: unknown): string | undefined;
+//# sourceMappingURL=canister-actor.d.ts.map

package/dist/canister-actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canister-actor.d.ts","sourceRoot":"","sources":["../src/canister-actor.ts"],"names":[],"mappings":"AAIA,OAAO,EAAS,KAAK,aAAa,EAAa,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUjD;AAiBD,wBAAsB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,gBAAgB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAKjJ;AAID;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAKzC,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9D;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAAqC,GAAG,MAAM,CAGhH;AAED,+BAA+B;AAC/B,eAAO,MAAM,aAAa;;;CAGzB,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUlF;AAID,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAErD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAa9G;AAID,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYjG;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG7D"}

package/dist/canister-actor.js

@@ -0,0 +1,133 @@
+// The agent and the error handling of the package: one HttpAgent per host, a stopped canister
+// waited out, `{ Ok } | { Err }` turned into a value or a thrown `CanisterError`, a time
+// limit. (The retry and the error shapes are a copy of @jsm-mit/tigi-sharded-package's.)
+import { Actor, HttpAgent } from "@icp-sdk/core/agent";
+export const MAINNET_HOST = "https://icp0.io";
+/** True for a replica on this machine: localhost, *.localhost, 127.0.0.1 or [::1]. */
+export function isLocalHost(host) {
+    let hostname;
+    try {
+        hostname = new URL(host).hostname;
+    }
+    catch {
+        return false;
+    }
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** One anonymous HttpAgent per host: the canister answers anyone. */
+const agents = new Map();
+function agentOf(host) {
+    let entry = agents.get(host);
+    if (!entry) {
+        const agent = HttpAgent.createSync({ host });
+        const ready = isLocalHost(host) ? agent.fetchRootKey().then(() => undefined) : Promise.resolve();
+        entry = { agent, ready };
+        agents.set(host, entry);
+    }
+    return entry;
+}
+export async function rawActorAsync(idlFactory, canisterId, options) {
+    const { agent, ready } = agentOf(options.host ?? MAINNET_HOST);
+    await ready;
+    return Actor.createActor(idlFactory, { agent, canisterId });
+}
+// ----- a stopped canister (an upgrade runs) -----
+/**
+ * A canister that is stopped or stopping — an upgrade of it runs — refuses every call with
+ * IC0508 / IC0509. The call did NOT run, so it is tried again: doubling pauses from
+ * `STOPPED_RETRY_FIRST_DELAY_MS`, at most `STOPPED_RETRY_MAX_FACTOR` times it, each 0.5–1.5
+ * of its length at random, `STOPPED_RETRY_ATTEMPTS` tries in all: about a minute — unless
+ * the time limit of the call ends first.
+ */
+export const STOPPED_RETRY_FIRST_DELAY_MS = 1000;
+export const STOPPED_RETRY_MAX_FACTOR = 8;
+export const STOPPED_RETRY_ATTEMPTS = 10;
+const STOPPED_ERROR_CODES = ["IC0508", "IC0509"];
+const STOPPED_REJECTS = [/ is stopped\b/, / is stopping\b/];
+/** True for the refusal of a stopped or stopping canister. */
+export function isCanisterStoppedError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const raw = error.message === "CriticalCanisterError" ? error.cause?.rawError : error;
+    if (!(raw instanceof Error) && (typeof raw !== "object" || raw === null))
+        return false;
+    const code = raw.cause?.code;
+    if (typeof code?.rejectErrorCode === "string" && STOPPED_ERROR_CODES.includes(code.rejectErrorCode))
+        return true;
+    const text = typeof code?.rejectMessage === "string" ? code.rejectMessage : raw instanceof Error ? raw.message : "";
+    return STOPPED_REJECTS.some((pattern) => pattern.test(text));
+}
+/** The wait before try `attempt + 1`: doubling, capped, 0.5–1.5 of it at random. */
+export function stoppedRetryDelayMs(attempt, firstDelayMs = STOPPED_RETRY_FIRST_DELAY_MS) {
+    const base = firstDelayMs * Math.min(2 ** (attempt - 1), STOPPED_RETRY_MAX_FACTOR);
+    return base * (0.5 + Math.random());
+}
+/** Tests shorten the waits. */
+export const retrySettings = {
+    stoppedFirstDelayMs: STOPPED_RETRY_FIRST_DELAY_MS,
+    stoppedAttempts: STOPPED_RETRY_ATTEMPTS,
+};
+export async function waitOutStoppedAsync(fnAsync) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fnAsync();
+        }
+        catch (err) {
+            if (!isCanisterStoppedError(err) || attempt >= retrySettings.stoppedAttempts)
+                throw err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, stoppedRetryDelayMs(attempt, retrySettings.stoppedFirstDelayMs)));
+    }
+}
+// ----- the time limit -----
+/** The error of a call that did not answer within its time limit. */
+export function timeoutError(timeoutMs) {
+    return new Error("Timeout", { cause: { timeoutMs } });
+}
+export function isTimeoutError(error) {
+    return error instanceof Error && error.message === "Timeout";
+}
+/**
+ * The call, or `Timeout` after `timeoutMs` (none when undefined). The call itself goes on
+ * (a query cannot be called back); its late answer is dropped.
+ */
+export async function withTimeoutAsync(fnAsync, timeoutMs) {
+    if (timeoutMs === undefined)
+        return fnAsync();
+    let timer;
+    const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timeoutError(timeoutMs)), timeoutMs);
+    });
+    try {
+        return await Promise.race([fnAsync(), limit]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `{ Ok: T }` resolves with `T`; `{ Err }` is thrown as `Error("CanisterError", { cause:
+ * { errorKey, errorMessage } })` with the variant's name as the errorKey (`OutsideArea`,
+ * `NoRoute`, `NotReady`, `InvalidData`); any transport failure as
+ * `Error("CriticalCanisterError", { cause: { rawError } })`. A stopped canister is waited
+ * out first.
+ */
+export async function executeRustAsyncUnsafe(fnAsync) {
+    let result;
+    try {
+        result = await waitOutStoppedAsync(fnAsync);
+    }
+    catch (err) {
+        throw new Error("CriticalCanisterError", { cause: { rawError: err } });
+    }
+    if ("Ok" in result)
+        return result.Ok;
+    const errorKey = Object.keys(result.Err)[0] ?? "Unknown";
+    throw new Error("CanisterError", { cause: { errorKey, errorMessage: result.Err[errorKey] } });
+}
+/** The errorKey of a `CanisterError`, or undefined for any other error. */
+export function errorKeyOf(error) {
+    if (!(error instanceof Error) || error.message !== "CanisterError")
+        return undefined;
+    return error.cause?.errorKey;
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import type { Point, RouteAnswer } from "../declarations/map-routes/map-routes.did.js";
+import { type MapRoutesOptions } from "./canister-actor.js";
+export { errorKeyOf, isCanisterStoppedError, isLocalHost, isTimeoutError, MAINNET_HOST, retrySettings, type MapRoutesOptions } from "./canister-actor.js";
+/** The canister on mainnet (crafting-table slot backend7). */
+export declare const MAP_ROUTES_CANISTER_ID = "6aigz-vyaaa-aaaag-ayjqa-cai";
+/** Points of one route: a start, up to three stops, an end. */
+export declare const MAX_ROUTE_POINTS = 5;
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+export type RouteLeg = {
+    meters: number;
+    seconds: number;
+    /** Encoded polyline of precision 5, junction to junction; absent when not asked for. */
+    line?: string;
+};
+export type Route = {
+    /** One leg for each pair of consecutive points. */
+    legs: RouteLeg[];
+    /** How far each point lies from the junction its legs start or end at. */
+    snapMeters: number[];
+    /** Date of the OpenStreetMap extract of the graph. */
+    osmDate: string;
+    graphSha256: string;
+};
+export type RouteOptions = {
+    /** Each leg carries its line. Default: false. */
+    line?: boolean;
+    /** `Timeout` after this many milliseconds. Default: none. */
+    timeoutMs?: number;
+};
+export declare function toPoint(point: LatLng): Point;
+export declare function fromAnswer(answer: RouteAnswer): Route;
+export declare class MapRoutesActor {
+    private readonly canisterId;
+    private readonly options;
+    constructor(canisterId?: string, options?: MapRoutesOptions);
+    /**
+     * The fastest route through `points` (2..=MAX_ROUTE_POINTS), leg by leg. Throws
+     * `CanisterError` (errorKey `OutsideArea` — a point farther than 1 km from a road of
+     * the map, `NoRoute`, `NotReady` — no graph yet, `InvalidData`), `Timeout`, or
+     * `CriticalCanisterError`.
+     */
+    routeAsyncUnsafe(points: LatLng[], options?: RouteOptions): Promise<Route>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAEjG,OAAO,EAAyC,KAAK,gBAAgB,EAAoB,MAAM,qBAAqB,CAAC;AAErH,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE1J,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,MAAM,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAChB,mDAAmD;IACnD,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAWrD;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAE/B,UAAU,GAAE,MAA+B,EAAE,OAAO,GAAE,gBAAqB;IAKvF;;;;;OAKG;IACU,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;CAS9F"}

package/dist/index.js

@@ -0,0 +1,44 @@
+// @jsm-mit/map-routes-package: the fastest route by car through 2–5 points from the map-routes
+// canister (an OpenStreetMap road graph of Nordrhein-Westfalen), with the line of each leg
+// as an encoded polyline of precision 5 — the format ORS sends.
+import { idlFactory } from "../declarations/map-routes/map-routes.did.js";
+import { executeRustAsyncUnsafe, rawActorAsync, withTimeoutAsync } from "./canister-actor.js";
+export { errorKeyOf, isCanisterStoppedError, isLocalHost, isTimeoutError, MAINNET_HOST, retrySettings } from "./canister-actor.js";
+/** The canister on mainnet (crafting-table slot backend7). */
+export const MAP_ROUTES_CANISTER_ID = "6aigz-vyaaa-aaaag-ayjqa-cai";
+/** Points of one route: a start, up to three stops, an end. */
+export const MAX_ROUTE_POINTS = 5;
+export function toPoint(point) {
+    return { lat: point.lat, lon: point.lng };
+}
+export function fromAnswer(answer) {
+    return {
+        legs: answer.legs.map((leg) => ({
+            meters: Number(leg.meters),
+            seconds: Number(leg.seconds),
+            ...(leg.line ? { line: leg.line } : {}),
+        })),
+        snapMeters: Array.from(answer.snapMeters),
+        osmDate: answer.osmDate,
+        graphSha256: answer.graphSha256,
+    };
+}
+export class MapRoutesActor {
+    canisterId;
+    options;
+    constructor(canisterId = MAP_ROUTES_CANISTER_ID, options = {}) {
+        this.canisterId = canisterId;
+        this.options = options;
+    }
+    /**
+     * The fastest route through `points` (2..=MAX_ROUTE_POINTS), leg by leg. Throws
+     * `CanisterError` (errorKey `OutsideArea` — a point farther than 1 km from a road of
+     * the map, `NoRoute`, `NotReady` — no graph yet, `InvalidData`), `Timeout`, or
+     * `CriticalCanisterError`.
+     */
+    async routeAsyncUnsafe(points, options = {}) {
+        const actor = await rawActorAsync(idlFactory, this.canisterId, this.options);
+        const answer = await withTimeoutAsync(() => executeRustAsyncUnsafe(() => actor.route({ points: points.map(toPoint), line: options.line ?? false })), options.timeoutMs);
+        return fromAnswer(answer);
+    }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
-  "name": "@jsm-mit/map-routes-package",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@jsm-mit/map-routes-package",
+    "version": "0.1.0",
+    "description": "The package of map-routes: the fastest route by car through 2–5 points, with the line of each leg, from an IC canister that holds an OpenStreetMap road graph.",
+    "homepage": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes/tree/master/package#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/JSM-Internet-Computer-Map-Service/map-routes.git",
+        "directory": "package"
+    },
+    "license": "ISC",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./declarations/*": "./declarations/*"
+    },
+    "files": [
+        "dist/",
+        "declarations/"
+    ],
+    "scripts": {
+        "build": "tsc && tsc -p tsconfig.tests.json",
+        "clean": "rm -rf dist",
+        "sync-declarations": "bash scripts/sync-declarations.sh",
+        "prepare": "npm run build",
+        "publish-public": "bash scripts/publish-public.sh",
+        "test-unit": "npx tsx tests/test-unit.ts",
+        "test-smoke": "bash scripts/run-tests-local.sh tests/test-smoke.ts"
+    },
+    "dependencies": {
+        "@icp-sdk/core": "^6.1.0"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.2",
+        "tsx": "^4.18.0",
+        "typescript": "^5.9.3"
+    },
+    "bugs": {
+        "url": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes/issues"
+    },
+    "mapRoutes": {
+        "repo": "map-routes",
+        "repoUrl": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes",
+        "commit": "21a20fa3d79c1703edf29352d616e81d84428610"
+    }
+}