@solvice/routing 0.17.2-beta.0 → 0.17.3-beta.0

package/README.md

@@ -70,6 +70,36 @@ try {
 | `evaluate(request)` | `POST /v3/routing/evaluate` |
 | `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.result(id)` | `GET /v3/routing/runs/{id}/result`: the plan of a `succeeded` run |
+| `runs.cancel(id)` | `POST /v3/routing/runs/{id}/cancel` |
+
+An async run takes the `solve` body and may search for up to 3,600 s
+(`options.time_limit_s`). Submit it, poll until `status` is `succeeded`, `failed` or
+`cancelled`, then read the plan:
+
+```typescript
+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);
+  }
+  if (run.status !== 'succeeded') {
+    throw new Error(`run ${run.id} ${run.status}: ${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`).
 
 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`
@@ -90,10 +120,10 @@ Documentation: <https://docs.solvice.io>
 
 ## Development
 
-`src/v3.ts` is generated; do not edit it. After an API change:
+`src/v3.ts` and `src/runs.ts` are generated; do not edit them. After an API change:
 
 ```bash
-npm run generate   # from mintlify/openapi.json
+npm run generate   # v3.ts from mintlify/openapi.json, runs.ts from mintlify/openapi-runs.json
 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
 ```

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import type { components as runsComponents, paths as runsPaths } from "./runs.js";
 import type { components, paths } from "./v3.js";
-export type { components, paths };
+export type { components, paths, runsComponents, runsPaths };
 export type Schemas = components["schemas"];
 export type SolveRequest = Schemas["SolveRequest"];
 export type EvaluateRequest = Schemas["EvaluateRequest"];
@@ -8,6 +9,12 @@ export type SolveResponse = Schemas["SolveResponse"];
 export type SuggestResponse = Schemas["SuggestResponse"];
 export type ValidateResponse = Schemas["ValidateResponse"];
 export type ErrorBody = Schemas["ErrorBody"];
+export type RunSchemas = runsComponents["schemas"];
+export type RunRequest = RunSchemas["RunRequest"];
+export type Run = RunSchemas["Run"];
+export type RunStatus = RunSchemas["RunStatus"];
+/** The gateway's own error answer on `/v3/routing/runs*`: not an `ErrorBody`. */
+export type GatewayError = RunSchemas["GatewayError"];
 export interface SolviceOptions {
     /** Sent as the `Authorization` header value, with no scheme prefix. */
     apiKey: string;
@@ -51,6 +58,22 @@ export declare function createSolvice({ apiKey, baseUrl, fetch }: SolviceOptions
         evaluate: (body: EvaluateRequest, options?: RequestOptions) => Promise<ValidateResponse>;
         suggest: (body: SuggestRequest, options?: RequestOptions) => Promise<ValidateResponse>;
     };
+    /**
+     * 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`.
+     */
+    runs: {
+        submit: (body: RunRequest, options?: RequestOptions) => Promise<Run>;
+        get: (id: string, options?: RequestOptions) => 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. */
+        cancel: (id: string, options?: RequestOptions) => Promise<Run>;
+    };
     /** The underlying openapi-fetch client, for anything the methods above do not cover. */
-    client: import("openapi-fetch").Client<paths, `${string}/${string}`>;
+    client: import("openapi-fetch").Client<paths & runsPaths, `${string}/${string}`>;
 };

package/dist/index.js

@@ -34,7 +34,15 @@ export class SolviceError extends Error {
 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;
+const gatewayMessage = (raw) => {
+    if (!isRecord(raw))
+        return undefined;
+    if (typeof raw.message === "string")
+        return raw.message;
+    // A malformed run id answers `{ error: "Invalid UUID string: ..." }` with no `message`;
+    // the bare `GATEWAY_ERROR` constant says less than the status line does.
+    return typeof raw.error === "string" && raw.error !== "GATEWAY_ERROR" ? raw.error : 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.
@@ -55,6 +63,22 @@ export function createSolvice({ apiKey, baseUrl = "https://api.solvice.io", fetc
             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 })),
         },
+        /**
+         * 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`.
+         */
+        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 })),
+        },
         /** The underlying openapi-fetch client, for anything the methods above do not cover. */
         client,
     };