@solvice/routing 0.17.4-beta.0 → 0.17.6-beta.0

package/README.md

@@ -71,7 +71,8 @@ try {
 | `suggest(request)` | `POST /v3/routing/suggest` |
 | `validate.solve(request)`, `validate.evaluate(request)`, `validate.suggest(request)` | the same three sent to `/v3/routing/validate/solve`, `/evaluate`, `/suggest`: checked, not run |
 | `runs.submit(request)` | `POST /v3/routing/runs`: answers at once with a `queued` run |
-| `runs.get(id)` | `GET /v3/routing/runs/{id}`: poll the run's `status` |
+| `runs.get(id)` | `GET /v3/routing/runs/{id}`: the run's `status` |
+| `runs.wait(id, { intervalMs, maxIntervalMs, signal })` | polls `get` with a growing pause until the run is final, and returns it (a `failed` or `cancelled` run is returned, not thrown) |
 | `runs.result(id)` | `GET /v3/routing/runs/{id}/result`: the plan of a `succeeded` run |
 | `runs.cancel(id)` | `POST /v3/routing/runs/{id}/cancel` |
 
@@ -85,21 +86,22 @@ import { createSolvice, type SolveRequest } from '@solvice/routing';
 const solvice = createSolvice({ apiKey: process.env.SOLVICE_API_KEY! });
 
 export async function solveInBackground(problem: SolveRequest['problem']) {
-  let run = await solvice.runs.submit({ problem, options: { time_limit_s: 600 } });
-  while (run.status === 'queued' || run.status === 'running') {
-    await new Promise((resolve) => setTimeout(resolve, 5000));
-    run = await solvice.runs.get(run.id);
-  }
+  const submitted = await solvice.runs.submit({ problem, options: { time_limit_s: 600 } });
+  const run = await solvice.runs.wait(submitted.id);
   if (run.status !== 'succeeded') {
-    throw new Error(`run ${run.id} ${run.status}: ${run.error?.message ?? 'no plan'}`);
+    throw new Error(`run ${run.id} ${run.status}: ${run.status === 'failed' ? run.error.message : 'no plan'}`);
   }
   return solvice.runs.result(run.id);
 }
 ```
 
 The run endpoints are served by the API gateway, so their `404` and `409` errors are
-not the API's error body: a `SolviceError` with no `body`, and `raw.message` starting
-with a code (`not_found`, `run_not_finished`, `no_result`).
+not the API's error body: a `SolviceError` with no `body`. Branch on `err.code`
+(`not_found`, `run_not_finished`, `no_result`), read from the start of `raw.message`;
+for the API's own errors it is the body's `code`. A run waits about 40 s in `queued`
+while its worker starts, so use runs for searches of a minute or more, and `solve`
+for shorter ones. `Run` narrows on `status`: a `succeeded` run always has
+`started_at`, `finished_at` and `expires_at`, and a `failed` run always has `error`.
 
 Any non-2xx response throws a `SolviceError` with the HTTP `status`, the
 `response`, and, when the response carried one, the API's error `body`. A `401`
@@ -136,6 +138,6 @@ Actions → Run workflow on `main`: it publishes the latest tag, or the one type
 It runs `npm run publish:beta` through npm trusted publishing; never publish
 from a branch. The explicit `--tag beta` matters: npm 11 ignores
 `publishConfig.tag` and would move `latest` to the prerelease. Until a stable version
-exists, `latest` still points at the first prerelease (npm gives a package's first
-version `latest` whatever the tag), so `npm install @solvice/routing` without
-`@beta` installs the beta too.
+exists, `latest` is not moved by a publish and has to be pointed by hand
+(`npm dist-tag add @solvice/routing@<version> latest`, run by a maintainer logged in to npm), or `npm install @solvice/routing` without `@beta` installs
+an old prerelease.

package/dist/index.d.ts

@@ -13,6 +13,10 @@ export type RunSchemas = runsComponents["schemas"];
 export type RunRequest = RunSchemas["RunRequest"];
 export type Run = RunSchemas["Run"];
 export type RunStatus = RunSchemas["RunStatus"];
+/** `Run` narrowed by `status`: `succeeded` always has `started_at`, `finished_at` and `expires_at`, `failed` always has `error`. */
+export type RunOf<S extends RunStatus> = Extract<Run, {
+    status: S;
+}>;
 /** The gateway's own error answer on `/v3/routing/runs*`: not an `ErrorBody`. */
 export type GatewayError = RunSchemas["GatewayError"];
 export interface SolviceOptions {
@@ -43,9 +47,23 @@ export declare class SolviceError extends Error {
     constructor(status: number, response: Response, body?: ErrorBody | undefined, 
     /** The parsed response body as received, whatever its shape; `undefined` when there was none. */
     raw?: unknown | undefined);
+    /**
+     * What to branch on: the `code` of the API's error body (`invalid_request`),
+     * or for a gateway error on `/v3/routing/runs*` the code its `message`
+     * starts with (`not_found`, `run_not_finished`, `no_result`). `undefined`
+     * when the response carried neither (a `401`, a `429`, a malformed run id).
+     */
+    get code(): string | undefined;
     /** Seconds to wait before retrying, from the `Retry-After` header; `undefined` without one (or with an HTTP date). */
     get retryAfterS(): number | undefined;
 }
+/** Options for `runs.wait`. `signal` aborts the wait and also bounds each poll: pass `AbortSignal.timeout(ms)` to cap the whole wait. */
+export interface WaitOptions extends RequestOptions {
+    /** First pause between polls; it grows by half each poll up to `maxIntervalMs`. Default 2,000. */
+    intervalMs?: number;
+    /** Longest pause between polls. Default 10,000. */
+    maxIntervalMs?: number;
+}
 /** The client `createSolvice` returns, for naming it in your own signatures. */
 export type Solvice = ReturnType<typeof createSolvice>;
 export declare function createSolvice({ apiKey, baseUrl, fetch }: SolviceOptions): {
@@ -61,14 +79,23 @@ export declare function createSolvice({ apiKey, baseUrl, fetch }: SolviceOptions
     /**
      * Async runs, served by the API gateway: `submit` answers at once and the
      * search runs in the background for up to `options.time_limit_s` (3,600 s).
-     * Poll `get` until `status` is `succeeded`, `failed` or `cancelled`, then
-     * read the plan with `result`. A gateway error (`404`, `409`) is a
-     * `SolviceError` with no `body`; its `raw.message` starts with a code such
-     * as `not_found`, `run_not_finished` or `no_result`.
+     * A run waits about 40 s in `queued` while its worker starts, so `wait` is
+     * for searches of a minute or more; `solve` is faster for short ones.
+     * Poll `get`, or `wait`, until `status` is `succeeded`, `failed` or
+     * `cancelled`, then read the plan with `result`. A gateway error (`404`,
+     * `409`) is a `SolviceError` with no `body`; branch on its `code`
+     * (`not_found`, `run_not_finished`, `no_result`).
      */
     runs: {
         submit: (body: RunRequest, options?: RequestOptions) => Promise<Run>;
         get: (id: string, options?: RequestOptions) => Promise<Run>;
+        /**
+         * Polls `get` until the run is `succeeded`, `failed` or `cancelled` and
+         * returns it; a `failed` or `cancelled` run is returned, not thrown. A run
+         * the gateway never sees start turns `failed` after 30 minutes, so the wait
+         * ends; use `signal` for a shorter bound.
+         */
+        wait: (id: string, { intervalMs, maxIntervalMs, ...options }?: WaitOptions) => Promise<Run>;
         /** The plan of a `succeeded` run; a run that is not finished, failed or cancelled answers `409`. */
         result: (id: string, options?: RequestOptions) => Promise<SolveResponse>;
         /** Cancels a `queued` or `running` run; a finished run comes back in its final state. */

package/dist/index.js

@@ -22,6 +22,17 @@ export class SolviceError extends Error {
         this.raw = raw;
         this.name = "SolviceError";
     }
+    /**
+     * What to branch on: the `code` of the API's error body (`invalid_request`),
+     * or for a gateway error on `/v3/routing/runs*` the code its `message`
+     * starts with (`not_found`, `run_not_finished`, `no_result`). `undefined`
+     * when the response carried neither (a `401`, a `429`, a malformed run id).
+     */
+    get code() {
+        if (this.body)
+            return this.body.code;
+        return /^([a-z][a-z_]*): /.exec(gatewayMessage(this.raw) ?? "")?.[1];
+    }
     /** Seconds to wait before retrying, from the `Retry-After` header; `undefined` without one (or with an HTTP date). */
     get retryAfterS() {
         const value = this.response.headers.get("retry-after");
@@ -51,8 +62,43 @@ function unwrap({ data, error, response }) {
     }
     return data;
 }
+const pause = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(signal.reason);
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
 export function createSolvice({ apiKey, baseUrl = "https://api.solvice.io", fetch }) {
     const client = createClient({ baseUrl, headers: { Authorization: apiKey }, fetch });
+    const runs = {
+        submit: async (body, options) => unwrap(await client.POST("/v3/routing/runs", { body, ...options })),
+        get: async (id, options) => unwrap(await client.GET("/v3/routing/runs/{id}", { params: { path: { id } }, ...options })),
+        /**
+         * Polls `get` until the run is `succeeded`, `failed` or `cancelled` and
+         * returns it; a `failed` or `cancelled` run is returned, not thrown. A run
+         * the gateway never sees start turns `failed` after 30 minutes, so the wait
+         * ends; use `signal` for a shorter bound.
+         */
+        wait: async (id, { intervalMs = 2000, maxIntervalMs = 10_000, ...options } = {}) => {
+            for (let delay = intervalMs;; delay = Math.min(delay * 1.5, maxIntervalMs)) {
+                const run = await runs.get(id, options);
+                if (run.status !== "queued" && run.status !== "running")
+                    return run;
+                await pause(delay, options.signal);
+            }
+        },
+        /** The plan of a `succeeded` run; a run that is not finished, failed or cancelled answers `409`. */
+        result: async (id, options) => unwrap(await client.GET("/v3/routing/runs/{id}/result", { params: { path: { id } }, ...options })),
+        /** Cancels a `queued` or `running` run; a finished run comes back in its final state. */
+        cancel: async (id, options) => unwrap(await client.POST("/v3/routing/runs/{id}/cancel", { params: { path: { id } }, ...options })),
+    };
     return {
         solve: async (body, options) => unwrap(await client.POST("/v3/routing/solve", { body, ...options })),
         evaluate: async (body, options) => unwrap(await client.POST("/v3/routing/evaluate", { body, ...options })),
@@ -66,19 +112,14 @@ export function createSolvice({ apiKey, baseUrl = "https://api.solvice.io", fetc
         /**
          * Async runs, served by the API gateway: `submit` answers at once and the
          * search runs in the background for up to `options.time_limit_s` (3,600 s).
-         * Poll `get` until `status` is `succeeded`, `failed` or `cancelled`, then
-         * read the plan with `result`. A gateway error (`404`, `409`) is a
-         * `SolviceError` with no `body`; its `raw.message` starts with a code such
-         * as `not_found`, `run_not_finished` or `no_result`.
+         * A run waits about 40 s in `queued` while its worker starts, so `wait` is
+         * for searches of a minute or more; `solve` is faster for short ones.
+         * Poll `get`, or `wait`, until `status` is `succeeded`, `failed` or
+         * `cancelled`, then read the plan with `result`. A gateway error (`404`,
+         * `409`) is a `SolviceError` with no `body`; branch on its `code`
+         * (`not_found`, `run_not_finished`, `no_result`).
          */
-        runs: {
-            submit: async (body, options) => unwrap(await client.POST("/v3/routing/runs", { body, ...options })),
-            get: async (id, options) => unwrap(await client.GET("/v3/routing/runs/{id}", { params: { path: { id } }, ...options })),
-            /** The plan of a `succeeded` run; a run that is not finished, failed or cancelled answers `409`. */
-            result: async (id, options) => unwrap(await client.GET("/v3/routing/runs/{id}/result", { params: { path: { id } }, ...options })),
-            /** Cancels a `queued` or `running` run; a finished run comes back in its final state. */
-            cancel: async (id, options) => unwrap(await client.POST("/v3/routing/runs/{id}/cancel", { params: { path: { id } }, ...options })),
-        },
+        runs,
         /** The underlying openapi-fetch client, for anything the methods above do not cover. */
         client,
     };

package/dist/runs.d.ts

@@ -1828,18 +1828,22 @@ export interface components {
              */
             wait_s?: number | null;
         };
-        /** @description One async run. */
-        Run: {
+        /** @description One async run. `status` selects the variant: which timestamps and `error` are present follows from it. */
+        Run: components["schemas"]["RunQueued"] | components["schemas"]["RunRunning"] | components["schemas"]["RunSucceeded"] | components["schemas"]["RunFailed"] | components["schemas"]["RunCancelled"];
+        /** @description A run cancelled before it finished. `started_at` is absent when it was cancelled while `queued`; it never returns a plan. */
+        RunCancelled: {
             /**
              * Format: uuid
              * @description The run id. Use it in the paths of the other endpoints.
              * @example d28568b1-34cc-4f89-b10b-dc24b26a8275
              */
             id: string;
-            status: components["schemas"]["RunStatus"];
+            /**
+             * @description `cancelled`. (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "cancelled";
             links: components["schemas"]["RunLinks"];
-            /** @description Present when `status` is `failed`. */
-            error?: components["schemas"]["RunError"];
             /**
              * Format: date-time
              * @description When a worker claimed the run, in UTC. Absent while the run is `queued`.
@@ -1851,13 +1855,13 @@ export interface components {
              * @description When the run reached a final state, in UTC. Absent before then.
              * @example 2026-10-15T07:41:00Z
              */
-            finished_at?: string;
+            finished_at: string;
             /**
              * Format: date-time
              * @description When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.
              * @example 2027-10-15T07:41:00Z
              */
-            expires_at?: string;
+            expires_at: string;
         };
         /** @description Why a run `failed`, in the `ErrorBody` shape. */
         RunError: {
@@ -1881,6 +1885,41 @@ export interface components {
             /** @description One entry per problem found in the request, as in `ErrorBody`. */
             errors?: components["schemas"]["RequestIssue"][];
         };
+        /** @description A run that stopped with an error. `started_at` is absent when the run never started. */
+        RunFailed: {
+            /**
+             * Format: uuid
+             * @description The run id. Use it in the paths of the other endpoints.
+             * @example d28568b1-34cc-4f89-b10b-dc24b26a8275
+             */
+            id: string;
+            /**
+             * @description `failed`. (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "failed";
+            links: components["schemas"]["RunLinks"];
+            /** @description Present when `status` is `failed`. */
+            error: components["schemas"]["RunError"];
+            /**
+             * Format: date-time
+             * @description When a worker claimed the run, in UTC. Absent while the run is `queued`.
+             * @example 2026-10-15T07:40:59Z
+             */
+            started_at?: string;
+            /**
+             * Format: date-time
+             * @description When the run reached a final state, in UTC. Absent before then.
+             * @example 2026-10-15T07:41:00Z
+             */
+            finished_at: string;
+            /**
+             * Format: date-time
+             * @description When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.
+             * @example 2027-10-15T07:41:00Z
+             */
+            expires_at: string;
+        };
         /** @description Paths of the run, relative to the API host. */
         RunLinks: {
             /**
@@ -1939,6 +1978,21 @@ export interface components {
              */
             travel_fallback?: null | components["schemas"]["TravelFallback"];
         };
+        /** @description A run no worker has claimed yet. No timestamps. */
+        RunQueued: {
+            /**
+             * Format: uuid
+             * @description The run id. Use it in the paths of the other endpoints.
+             * @example d28568b1-34cc-4f89-b10b-dc24b26a8275
+             */
+            id: string;
+            /**
+             * @description `queued`. (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "queued";
+            links: components["schemas"]["RunLinks"];
+        };
         /**
          * @description Request body for `POST /v3/routing/runs`: the `POST /v3/routing/solve` body, with a longer `options.time_limit_s`.
          * @example {
@@ -2046,11 +2100,65 @@ export interface components {
             /** @description The problem: tasks, fleet, depots, relations, objective, travel. */
             problem: components["schemas"]["Problem"];
         };
+        /** @description A run a worker has claimed. */
+        RunRunning: {
+            /**
+             * Format: uuid
+             * @description The run id. Use it in the paths of the other endpoints.
+             * @example d28568b1-34cc-4f89-b10b-dc24b26a8275
+             */
+            id: string;
+            /**
+             * @description `running`. (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "running";
+            links: components["schemas"]["RunLinks"];
+            /**
+             * Format: date-time
+             * @description When a worker claimed the run, in UTC. Absent while the run is `queued`.
+             * @example 2026-10-15T07:40:59Z
+             */
+            started_at: string;
+        };
         /**
          * @description Where a run is. `queued` until a worker claims it, then `running`. `succeeded`, `failed` and `cancelled` are final.
          * @enum {string}
          */
         RunStatus: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+        /** @description A run that finished. Read the plan with `GET /v3/routing/runs/{id}/result`. */
+        RunSucceeded: {
+            /**
+             * Format: uuid
+             * @description The run id. Use it in the paths of the other endpoints.
+             * @example d28568b1-34cc-4f89-b10b-dc24b26a8275
+             */
+            id: string;
+            /**
+             * @description `succeeded`. (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            status: "succeeded";
+            links: components["schemas"]["RunLinks"];
+            /**
+             * Format: date-time
+             * @description When a worker claimed the run, in UTC. Absent while the run is `queued`.
+             * @example 2026-10-15T07:40:59Z
+             */
+            started_at: string;
+            /**
+             * Format: date-time
+             * @description When the run reached a final state, in UTC. Absent before then.
+             * @example 2026-10-15T07:41:00Z
+             */
+            finished_at: string;
+            /**
+             * Format: date-time
+             * @description When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.
+             * @example 2027-10-15T07:41:00Z
+             */
+            expires_at: string;
+        };
         /**
          * @description How good a plan is. Plans compare in order: fewer `violation_count`
          *     first, then less `unassigned_priority`, then less `cost`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvice/routing",
-  "version": "0.17.4-beta.0",
+  "version": "0.17.6-beta.0",
   "description": "TypeScript client for the Solvice V3 routing API, generated from its OpenAPI spec.",
   "license": "Apache-2.0",
   "homepage": "https://docs.solvice.io/guides/platform/sdks/typescript",