@solvice/routing 0.1.0-beta.0 → 0.16.1-beta.0

package/README.md

@@ -16,33 +16,51 @@ import { createSolvice, SolviceError } from '@solvice/routing';
 const solvice = createSolvice({ apiKey: process.env.SOLVICE_API_KEY! });
 
 try {
-  const solution = await solvice.solve(
-    {
-      problem: {
-        jobs: [{ id: 'delivery-1', location: [4.7005, 50.8798], service_duration_s: 300 }],
-        vehicles: [
-          {
-            id: 'truck-1',
-            shifts: [
-              {
-                id: 'mon',
-                from: '2026-04-01T08:00:00+02:00',
-                to: '2026-04-01T17:00:00+02:00',
-                start: { location: [4.3517, 50.8503] },
-                end: { location: [4.3517, 50.8503] },
-              },
-            ],
-          },
-        ],
-      },
-      options: { time_limit_s: 5 },
+  const solution = await solvice.solve({
+    problem: {
+      jobs: [
+        {
+          id: 'delivery-1',
+          location: [4.7005, 50.8798], // [longitude, latitude]
+          service_duration_s: 300,
+          time_windows: [{ from: '2026-04-01T09:00:00+02:00', to: '2026-04-01T12:00:00+02:00' }],
+          delivery_load: { weight: 10 },
+        },
+      ],
+      vehicles: [
+        {
+          id: 'truck-1',
+          capacity: { weight: 100 },
+          shifts: [
+            {
+              id: 'mon',
+              from: '2026-04-01T08:00:00+02:00',
+              to: '2026-04-01T17:00:00+02:00',
+              start: { location: [4.3517, 50.8503] },
+              end: { location: [4.3517, 50.8503] },
+            },
+          ],
+        },
+      ],
     },
-    { signal: AbortSignal.timeout(35_000) },
-  );
-  console.log(solution.routes);
+    options: { time_limit_s: 5 },
+  });
+
+  for (const route of solution.routes) {
+    console.log(`${route.vehicle} / ${route.shift}: ${route.distance_m} m`);
+    for (const stop of route.stops) {
+      console.log(`  ${stop.type} ${stop.id ?? ''} arrives ${stop.arrival}`);
+    }
+  }
+  for (const job of solution.unassigned) {
+    console.log(`unassigned ${job.task}: ${job.category}`);
+  }
 } catch (err) {
   if (!(err instanceof SolviceError)) throw err;
-  console.error(err.status, err.body?.errors);
+  console.error(err.status, err.body?.code, err.message);
+  for (const item of err.body?.errors ?? []) {
+    console.error(`  ${item.code} at ${item.pointer}: ${item.message}`);
+  }
 }
 ```
 
@@ -51,10 +69,14 @@ try {
 | `solve(request)` | `POST /v3/routing/solve` |
 | `evaluate(request)` | `POST /v3/routing/evaluate` |
 | `suggest(request)` | `POST /v3/routing/suggest` |
-| `validate.solve(request)`, `validate.evaluate(request)`, `validate.suggest(request)` | the same three with `?validate_only=true` |
+| `validate.solve(request)`, `validate.evaluate(request)`, `validate.suggest(request)` | the same three sent to `/v3/routing/validate/solve`, `/evaluate`, `/suggest`: checked, not run |
 
-Any non-2xx response throws a `SolviceError` with the HTTP `status` and, when the
-response carried one, the API's error `body`.
+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`
+or a `429` comes from the API gateway and does not use that body (see
+[Errors](https://docs.solvice.io/guides/vrp/errors)): branch on `status`, and read
+`raw` for whatever JSON came back. Every `503` carries `Retry-After`; wait
+`err.retryAfterS` seconds before retrying.
 
 Every method takes a second argument, `{ signal, headers }`. The client sets no
 timeout of its own: pass `AbortSignal.timeout(ms)` as `signal`, with a margin on
@@ -72,10 +94,15 @@ Documentation: <https://docs.solvice.io>
 
 ```bash
 npm run generate   # from mintlify/openapi.json
-npm test           # builds, typechecks tests/types.ts and examples/, runs the unit tests
+npm test           # builds, typechecks tests/types.ts and examples/, runs the unit tests and the solve-response fixture check
 npm run smoke      # live calls; needs SOLVICE_API_KEY
 ```
 
-To release, bump `version` to the next `0.x.y-beta.n` and run `npm run publish:beta`.
-The explicit `--tag beta` matters: npm 11 ignores `publishConfig.tag` and would
-move `latest` to the prerelease.
+To release, bump `version` to the next `0.x.y-beta.n`, merge it to `main`, then run
+the "Publish TypeScript SDK" workflow on `main` (Actions → Run workflow). 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.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type EvaluateRequest = Schemas["EvaluateRequest"];
 export type SuggestRequest = Schemas["SuggestRequest"];
 export type SolveResponse = Schemas["SolveResponse"];
 export type SuggestResponse = Schemas["SuggestResponse"];
-export type ValidateOnlyResponse = Schemas["ValidateOnlyResponse"];
+export type ValidateResponse = Schemas["ValidateResponse"];
 export type ErrorBody = Schemas["ErrorBody"];
 export interface SolviceOptions {
     /** Sent as the `Authorization` header value, with no scheme prefix. */
@@ -19,21 +19,37 @@ export interface RequestOptions {
     signal?: AbortSignal;
     headers?: Record<string, string>;
 }
-/** Any non-2xx response. `body` is absent when the response carried no JSON (401, 429). */
+/**
+ * Any non-2xx response. `body` is the API's error body when the response
+ * carried one. A `401` or a `429` comes from the API gateway and does not use
+ * that body (a JSON `{ message, error }` or nothing): branch on `status`, and
+ * read `raw` for whatever came back. `response` is the `Response` itself, for
+ * its headers: every `503` carries `Retry-After` (`retryAfterS`), and
+ * `X-Request-Id` survives a bodiless error.
+ */
 export declare class SolviceError extends Error {
     readonly status: number;
+    readonly response: Response;
     readonly body?: ErrorBody | undefined;
-    constructor(status: number, body?: ErrorBody | undefined);
+    /** The parsed response body as received, whatever its shape; `undefined` when there was none. */
+    readonly raw?: unknown | undefined;
+    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);
+    /** Seconds to wait before retrying, from the `Retry-After` header; `undefined` without one (or with an HTTP date). */
+    get retryAfterS(): number | undefined;
 }
+/** 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): {
     solve: (body: SolveRequest, options?: RequestOptions) => Promise<SolveResponse>;
     evaluate: (body: EvaluateRequest, options?: RequestOptions) => Promise<SolveResponse>;
     suggest: (body: SuggestRequest, options?: RequestOptions) => Promise<SuggestResponse>;
-    /** The same requests with `?validate_only=true`: no matrix fetch, no search. */
+    /** The same requests sent to `/v3/routing/validate/*`: no matrix fetch, no search, not billed. */
     validate: {
-        solve: (body: SolveRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
-        evaluate: (body: EvaluateRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
-        suggest: (body: SuggestRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
+        solve: (body: SolveRequest, options?: RequestOptions) => Promise<ValidateResponse>;
+        evaluate: (body: EvaluateRequest, options?: RequestOptions) => Promise<ValidateResponse>;
+        suggest: (body: SuggestRequest, options?: RequestOptions) => Promise<ValidateResponse>;
     };
     /** The underlying openapi-fetch client, for anything the methods above do not cover. */
     client: import("openapi-fetch").Client<paths, `${string}/${string}`>;

package/dist/index.js

@@ -1,39 +1,59 @@
 import createClient from "openapi-fetch";
-/** Any non-2xx response. `body` is absent when the response carried no JSON (401, 429). */
+/**
+ * Any non-2xx response. `body` is the API's error body when the response
+ * carried one. A `401` or a `429` comes from the API gateway and does not use
+ * that body (a JSON `{ message, error }` or nothing): branch on `status`, and
+ * read `raw` for whatever came back. `response` is the `Response` itself, for
+ * its headers: every `503` carries `Retry-After` (`retryAfterS`), and
+ * `X-Request-Id` survives a bodiless error.
+ */
 export class SolviceError extends Error {
     status;
+    response;
     body;
-    constructor(status, body) {
-        super(body?.message ?? `Solvice API responded ${status}`);
+    raw;
+    constructor(status, response, body, 
+    /** The parsed response body as received, whatever its shape; `undefined` when there was none. */
+    raw) {
+        super(body?.message ?? gatewayMessage(raw) ?? `Solvice API responded ${status}`);
         this.status = status;
+        this.response = response;
         this.body = body;
+        this.raw = raw;
         this.name = "SolviceError";
     }
+    /** 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");
+        if (value === null)
+            return undefined;
+        const seconds = Number(value);
+        return Number.isFinite(seconds) ? seconds : undefined;
+    }
 }
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** The API's error body has `status`, `code` and `message`; the gateway's `401` has `message` and `error`. */
+const isErrorBody = (value) => isRecord(value) && "status" in value && "code" in value && "message" in value;
+const gatewayMessage = (raw) => isRecord(raw) && typeof raw.message === "string" ? raw.message : undefined;
 function unwrap({ data, error, response }) {
     if (!response.ok) {
-        // openapi-fetch hands back the raw text when the error is not JSON.
-        throw new SolviceError(response.status, typeof error === "object" && error !== null ? error : undefined);
+        // openapi-fetch hands back the raw text when the error is not JSON, and "" for no body.
+        const raw = error === "" || error == null ? undefined : error;
+        throw new SolviceError(response.status, response, isErrorBody(raw) ? raw : undefined, raw);
     }
     return data;
 }
-// The spec types every 200 as `Response | ValidateOnlyResponse` (#1626 H).
-// Which one comes back is decided by `validate_only`, which each method below
-// fixes, so these two pick the matching side of the union.
-const result = (r) => unwrap(r);
-const validation = (r) => unwrap(r);
-const VALIDATE_ONLY = { query: { validate_only: true } };
 export function createSolvice({ apiKey, baseUrl = "https://api.solvice.io", fetch }) {
     const client = createClient({ baseUrl, headers: { Authorization: apiKey }, fetch });
     return {
-        solve: async (body, options) => result(await client.POST("/v3/routing/solve", { body, ...options })),
-        evaluate: async (body, options) => result(await client.POST("/v3/routing/evaluate", { body, ...options })),
-        suggest: async (body, options) => result(await client.POST("/v3/routing/suggest", { body, ...options })),
-        /** The same requests with `?validate_only=true`: no matrix fetch, no search. */
+        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 })),
+        suggest: async (body, options) => unwrap(await client.POST("/v3/routing/suggest", { body, ...options })),
+        /** The same requests sent to `/v3/routing/validate/*`: no matrix fetch, no search, not billed. */
         validate: {
-            solve: async (body, options) => validation(await client.POST("/v3/routing/solve", { body, params: VALIDATE_ONLY, ...options })),
-            evaluate: async (body, options) => validation(await client.POST("/v3/routing/evaluate", { body, params: VALIDATE_ONLY, ...options })),
-            suggest: async (body, options) => validation(await client.POST("/v3/routing/suggest", { body, params: VALIDATE_ONLY, ...options })),
+            solve: async (body, options) => unwrap(await client.POST("/v3/routing/validate/solve", { body, ...options })),
+            evaluate: async (body, options) => unwrap(await client.POST("/v3/routing/validate/evaluate", { body, ...options })),
+            suggest: async (body, options) => unwrap(await client.POST("/v3/routing/validate/suggest", { body, ...options })),
         },
         /** The underlying openapi-fetch client, for anything the methods above do not cover. */
         client,