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

package/README.md

@@ -1,3 +1,81 @@
-# 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], 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 },
+    },
+    { signal: AbortSignal.timeout(35_000) },
+  );
+  console.log(solution.routes);
+} catch (err) {
+  if (!(err instanceof SolviceError)) throw err;
+  console.error(err.status, err.body?.errors);
+}
+```
+
+| 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` and, when the
+response carried one, the API's error `body`.
+
+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` and run `npm run publish:beta`.
+The explicit `--tag beta` matters: npm 11 ignores `publishConfig.tag` and would
+move `latest` to the prerelease.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+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 absent when the response carried no JSON (401, 429). */
+export declare class SolviceError extends Error {
+    readonly status: number;
+    readonly body?: ErrorBody | undefined;
+    constructor(status: number, body?: ErrorBody | undefined);
+}
+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,41 @@
+import createClient from "openapi-fetch";
+/** Any non-2xx response. `body` is absent when the response carried no JSON (401, 429). */
+export class SolviceError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(body?.message ?? `Solvice API responded ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = "SolviceError";
+    }
+}
+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);
+    }
+    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,
+    };
+}