@solvice/routing 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @solvice/routing
 
-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.
+TypeScript client for the Solvice V3 Routing API. The request and response types
+are generated from the API's OpenAPI spec, so they match the API field for field.
+
+V3 is in beta until general availability. Until then this package is published
+under the `beta` dist-tag as `0.x` prereleases, and any release may change types.
+
+```bash
+npm install @solvice/routing@beta
+```
+
+```typescript
+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], // [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: { 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] },
+            },
+          ],
+        },
+      ],
+    },
+    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.job_id}: ${job.category}`);
+  }
+} catch (err) {
+  if (!(err instanceof SolviceError)) throw err;
+  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}`);
+  }
+}
+```
+
+| Method | Endpoint |
+| --- | --- |
+| `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` |
+
+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
+top of `options.time_limit_s`. It does not retry; pass your own `fetch` to
+`createSolvice` to add that. `client` is the underlying
+[openapi-fetch](https://openapi-ts.dev/openapi-fetch/) client.
+
+Runs on Node.js 20 or later. Keep the API key on your server.
+
+Documentation: <https://docs.solvice.io>
+
+## Development
+
+`src/v3.ts` is generated; do not edit it. After an API change:
+
+```bash
+npm run generate   # from mintlify/openapi.json
+npm test           # builds, typechecks tests/types.ts and examples/, runs the unit tests
+npm run smoke      # live calls; needs SOLVICE_API_KEY
+```
+
+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

@@ -0,0 +1,56 @@
+import type { components, paths } from "./v3.js";
+export type { components, paths };
+export type Schemas = components["schemas"];
+export type SolveRequest = Schemas["SolveRequest"];
+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 ErrorBody = Schemas["ErrorBody"];
+export interface SolviceOptions {
+    /** Sent as the `Authorization` header value, with no scheme prefix. */
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** Per-call options. The client sets no timeout: pass `AbortSignal.timeout(ms)` as `signal`. */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+/**
+ * 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;
+    /** 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. */
+    validate: {
+        solve: (body: SolveRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
+        evaluate: (body: EvaluateRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
+        suggest: (body: SuggestRequest, options?: RequestOptions) => Promise<ValidateOnlyResponse>;
+    };
+    /** 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

@@ -0,0 +1,67 @@
+import createClient from "openapi-fetch";
+/**
+ * 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;
+    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, 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. */
+        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 })),
+        },
+        /** The underlying openapi-fetch client, for anything the methods above do not cover. */
+        client,
+    };
+}