@vouchline/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @vouchline/sdk
 
-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.
+A typed client for the Vouchline API, generated from `schema/openapi.yaml`. It has no
+runtime dependencies: it uses `fetch`, so it runs on Node 20.6+, Bun, Deno, workers and
+browsers.
+
+- `run()` and `runAndWait()` for the one-call run API
+- `streamEvents()` to follow a run live (SSE)
+- Typed errors for every error code
+- Automatic `Idempotency-Key` on POSTs, reused on retries; 429 and 5xx retried with backoff
+- Every schema type exported (`QuickRunResult`, `RunDetail`, `UsageReport`, …), plus the
+  `operations` table: each key-callable operation's method, path and scope
+
+## Install
+
+The package is not published yet. Build it from this directory:
+
+```bash
+npm install && npm run build
+```
+
+## Use
+
+```ts
+import { Vouchline } from "@vouchline/sdk";
+
+const vouchline = new Vouchline({
+  apiKey: process.env.VOUCHLINE_API_KEY,
+  baseUrl: "https://api.vouchline.example",
+});
+
+const result = await vouchline.runAndWait({
+  agent: "vendor-risk",
+  question: "Is Acme Logistics GmbH a safe supplier?",
+  inputs: { company: "Acme Logistics GmbH" },
+});
+console.info(result.summary, result.claims.length);
+```
+
+`run()` returns `{ finished: true, result }`, or `{ finished: false, pending }` when the
+run is still working after `wait` seconds (0-120). `runAndWait()` holds one request and
+then polls `GET /v1/runs/{id}/result` until the run is done or `timeoutSeconds` (default
+600) passes, then throws `TimeoutError`.
+
+### Stream a run
+
+```ts
+import { Vouchline } from "@vouchline/sdk";
+
+const vouchline = new Vouchline();
+const started = await vouchline.run({ question: "Check Acme Logistics GmbH" });
+const runId = started.finished ? started.result.id : started.pending.id;
+for await (const event of vouchline.streamEvents(runId)) {
+  if (event.event === "delta") continue;
+  console.info(event.id, event.event, event.data);
+}
+```
+
+To resume after a disconnect, pass `{ after: lastEventId }`.
+
+### Errors
+
+```ts
+import { PaymentRequiredError, PermissionDeniedError, Vouchline, RateLimitError } from "@vouchline/sdk";
+
+const vouchline = new Vouchline();
+try {
+  await vouchline.run({ question: "Check Acme" });
+} catch (error) {
+  if (error instanceof PaymentRequiredError) console.warn("Out of credits:", error.code);
+  else if (error instanceof PermissionDeniedError) console.warn("Missing scope:", error.requiredScope);
+  else if (error instanceof RateLimitError) console.warn("Retry in", error.retryAfter, "s");
+  else throw error;
+}
+```
+
+| Status | Class |
+| --- | --- |
+| 400 | `ValidationError` |
+| 401 | `AuthenticationError` |
+| 402 | `PaymentRequiredError` |
+| 403 | `PermissionDeniedError` |
+| 404 | `NotFoundError` |
+| 409 | `ConflictError` |
+| 429 | `RateLimitError` |
+| 5xx | `ServerError` |
+| no answer | `ConnectionError` |
+
+Every class extends `VouchlineError` and carries `status`, `code`, `requestId`, `field` and
+`details`, which is the full error envelope.
+
+### Anything else
+
+Each operation in the schema can be called with `request`:
+
+```ts
+import { type Batch, Vouchline } from "@vouchline/sdk";
+
+const vouchline = new Vouchline();
+const batch = await vouchline.request<Batch>("POST", "/v1/batches", {
+  body: { agent: "vendor-risk", inputs: [{ company: "Acme GmbH" }] },
+});
+console.info(batch.id);
+```
+
+`listRuns`, `getRun`, `getRunResult`, `cancelRun`, `listAgents`, `getAgent`, `startBatch` and
+`usage()` are shortcuts. `usage()` returns credits used and left this period, by source.
+
+## Develop
+
+```bash
+npm test                                   # node --test against a local mock server
+npm run typecheck
+python ../../scripts/generate_sdk_types.py  # after the schema changes
+```
+
+Billing: every call is billed to the workspace exactly like the same call from the
+dashboard.

package/dist/client.d.ts

@@ -0,0 +1,85 @@
+import { VouchlineError } from "./errors.ts";
+import type { Agent, AgentDetail, Batch, BatchCreateRequest, PaginatedRunList, QuickRunPending, QuickRunRequest, QuickRunResult, RunDetail, UsageReport } from "./generated.ts";
+import { type RunEvent } from "./sse.ts";
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface ClientOptions {
+    /** `pl_live_…` or `pl_test_…`. Defaults to the VOUCHLINE_API_KEY environment variable. */
+    apiKey?: string;
+    /** API origin, e.g. https://api.vouchline.example. Defaults to VOUCHLINE_BASE_URL. */
+    baseUrl?: string;
+    /** Retries for 429, 5xx and network errors (POSTs reuse their Idempotency-Key). Default 2. */
+    maxRetries?: number;
+    /** Per-request timeout in milliseconds. Default 150 000 (a `wait` run holds up to 120 s). */
+    timeoutMs?: number;
+    fetch?: FetchLike;
+    /** For tests: how to wait between retries and polls. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export type Query = Record<string, string | number | boolean | undefined>;
+export interface RequestOptions {
+    query?: Query;
+    body?: unknown;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export type RunAnswer = {
+    finished: true;
+    result: QuickRunResult;
+} | {
+    finished: false;
+    pending: QuickRunPending;
+};
+export interface RunAndWaitOptions {
+    /** Give up after this many seconds overall. Default 600. */
+    timeoutSeconds?: number;
+    /** Delay between result polls once the held request ends. Default 2000 ms. */
+    pollIntervalMs?: number;
+}
+export interface RunFilters {
+    status?: string;
+    agent?: string;
+    effort?: "fast" | "standard" | "deep";
+    q?: string;
+    page_size?: number;
+    cursor?: string;
+}
+export declare class TimeoutError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+export declare class Vouchline {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options?: ClientOptions);
+    /** Any operation by method and flat path (see `operations` in generated.ts). */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** `POST /v1/run`. With `wait` (seconds, 0-120) the call holds for the result. */
+    run(params: QuickRunRequest, options?: {
+        wait?: number;
+    }): Promise<RunAnswer>;
+    /** Start a run and resolve with its result: a held request, then polling the result. */
+    runAndWait(params: QuickRunRequest, options?: RunAndWaitOptions): Promise<QuickRunResult>;
+    waitForResult(runId: string, deadline: number, pollIntervalMs?: number): Promise<QuickRunResult>;
+    getRun(runId: string): Promise<RunDetail>;
+    getRunResult(runId: string): Promise<QuickRunResult>;
+    listRuns(filters?: RunFilters): Promise<PaginatedRunList>;
+    cancelRun(runId: string): Promise<RunDetail>;
+    listAgents(): Promise<Agent[]>;
+    getAgent(slug: string): Promise<AgentDetail>;
+    startBatch(params: BatchCreateRequest): Promise<Batch>;
+    /** Credits used and left this period, by source (dashboard, api_key, mcp, schedule, batch). */
+    usage(): Promise<UsageReport>;
+    /** The run's events as they happen; resume with `after` (an event `id`). Ends on `end`. */
+    streamEvents(runId: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<RunEvent>;
+    private url;
+    private send;
+    private backoff;
+}
+export { VouchlineError };

package/dist/client.js

@@ -0,0 +1,174 @@
+import { ConflictError, ConnectionError, VouchlineError, errorFor } from "./errors.js";
+import { readEvents } from "./sse.js";
+const MAX_WAIT_SECONDS = 120;
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+function env(name) {
+    // Node, Bun and Deno expose process.env; browsers don't.
+    const proc = Reflect.get(globalThis, "process");
+    const vars = typeof proc === "object" && proc !== null ? Reflect.get(proc, "env") : undefined;
+    const value = typeof vars === "object" && vars !== null ? Reflect.get(vars, name) : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+function newKey() {
+    return globalThis.crypto.randomUUID();
+}
+export class TimeoutError extends Error {
+    runId;
+    constructor(runId) {
+        super(`Run ${runId} did not finish in time.`);
+        this.name = "TimeoutError";
+        this.runId = runId;
+    }
+}
+export class Vouchline {
+    baseUrl;
+    apiKey;
+    maxRetries;
+    timeoutMs;
+    fetchImpl;
+    sleep;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? env("VOUCHLINE_API_KEY");
+        const baseUrl = options.baseUrl ?? env("VOUCHLINE_BASE_URL");
+        if (!apiKey)
+            throw new Error("Pass apiKey or set VOUCHLINE_API_KEY.");
+        if (!baseUrl)
+            throw new Error("Pass baseUrl or set VOUCHLINE_BASE_URL.");
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.maxRetries = options.maxRetries ?? 2;
+        this.timeoutMs = options.timeoutMs ?? 150_000;
+        this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /** Any operation by method and flat path (see `operations` in generated.ts). */
+    async request(method, path, options = {}) {
+        const response = await this.send(method, path, options);
+        const text = await response.text();
+        // The schema is the contract: bodies are typed by the generated types, not re-validated.
+        const data = text ? JSON.parse(text) : null;
+        return data;
+    }
+    /** `POST /v1/run`. With `wait` (seconds, 0-120) the call holds for the result. */
+    async run(params, options = {}) {
+        const wait = Math.max(0, Math.min(options.wait ?? 0, MAX_WAIT_SECONDS));
+        const response = await this.send("POST", "/v1/run", { body: params, query: { wait } });
+        if (response.status === 202) {
+            const pending = await response.json();
+            return { finished: false, pending };
+        }
+        const result = await response.json();
+        return { finished: true, result };
+    }
+    /** Start a run and resolve with its result: a held request, then polling the result. */
+    async runAndWait(params, options = {}) {
+        const timeout = options.timeoutSeconds ?? 600;
+        const deadline = Date.now() + timeout * 1000;
+        const answer = await this.run(params, { wait: Math.min(timeout, MAX_WAIT_SECONDS) });
+        if (answer.finished)
+            return answer.result;
+        return this.waitForResult(answer.pending.id, deadline, options.pollIntervalMs ?? 2000);
+    }
+    async waitForResult(runId, deadline, pollIntervalMs = 2000) {
+        for (;;) {
+            try {
+                return await this.getRunResult(runId);
+            }
+            catch (error) {
+                if (!(error instanceof ConflictError) || error.code !== "run_not_finished")
+                    throw error;
+            }
+            if (Date.now() + pollIntervalMs > deadline)
+                throw new TimeoutError(runId);
+            await this.sleep(pollIntervalMs);
+        }
+    }
+    getRun(runId) {
+        return this.request("GET", `/v1/runs/${encodeURIComponent(runId)}`);
+    }
+    getRunResult(runId) {
+        return this.request("GET", `/v1/runs/${encodeURIComponent(runId)}/result`);
+    }
+    listRuns(filters = {}) {
+        return this.request("GET", "/v1/runs", { query: { ...filters } });
+    }
+    cancelRun(runId) {
+        return this.request("POST", `/v1/runs/${encodeURIComponent(runId)}/cancel`, { body: {} });
+    }
+    listAgents() {
+        return this.request("GET", "/v1/agents");
+    }
+    getAgent(slug) {
+        return this.request("GET", `/v1/agents/${encodeURIComponent(slug)}`);
+    }
+    startBatch(params) {
+        return this.request("POST", "/v1/batches", { body: params });
+    }
+    /** Credits used and left this period, by source (dashboard, api_key, mcp, schedule, batch). */
+    usage() {
+        return this.request("GET", "/v1/usage");
+    }
+    /** The run's events as they happen; resume with `after` (an event `id`). Ends on `end`. */
+    async *streamEvents(runId, options = {}) {
+        const path = `/v1/runs/${encodeURIComponent(runId)}/stream`;
+        const response = await this.send("GET", path, {
+            query: { after_seq: options.after },
+            signal: options.signal,
+        }, "text/event-stream", false);
+        if (!response.body)
+            return;
+        for await (const event of readEvents(response.body)) {
+            yield event;
+            if (event.event === "end")
+                return;
+        }
+    }
+    url(path, query) {
+        const params = new URLSearchParams();
+        for (const [name, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                params.set(name, String(value));
+        }
+        const search = params.toString();
+        return `${this.baseUrl}${path}${search ? `?${search}` : ""}`;
+    }
+    async send(method, path, options, accept = "application/json", timed = true) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: accept,
+            "User-Agent": "vouchline-typescript/0.1.0",
+        };
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (method === "POST")
+            headers["Idempotency-Key"] = options.idempotencyKey ?? newKey();
+        const body = options.body === undefined ? undefined : JSON.stringify(options.body);
+        for (let attempt = 0;; attempt += 1) {
+            const signal = timed ? AbortSignal.any([AbortSignal.timeout(this.timeoutMs), ...(options.signal ? [options.signal] : [])]) : options.signal;
+            let response;
+            try {
+                response = await this.fetchImpl(this.url(path, options.query), { method, headers, body, signal });
+            }
+            catch (cause) {
+                if (attempt >= this.maxRetries || options.signal?.aborted) {
+                    throw new ConnectionError(`${method} ${path} failed: ${String(cause)}`, { cause });
+                }
+                await this.sleep(this.backoff(attempt, undefined));
+                continue;
+            }
+            if (response.ok)
+                return response;
+            const retryAfter = Number(response.headers.get("Retry-After") ?? "") || undefined;
+            if (RETRYABLE.has(response.status) && attempt < this.maxRetries) {
+                await response.body?.cancel();
+                await this.sleep(this.backoff(attempt, retryAfter));
+                continue;
+            }
+            throw errorFor(response.status, await response.json().catch(() => null), retryAfter);
+        }
+    }
+    backoff(attempt, retryAfter) {
+        return retryAfter !== undefined ? retryAfter * 1000 : 500 * 2 ** attempt;
+    }
+}
+export { VouchlineError };

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/** Typed errors for every non-2xx answer, read from the API's one error envelope. */
+export interface ErrorDetails {
+    type?: string;
+    code: string;
+    message: string;
+    field?: string | null;
+    request_id?: string;
+    required_scope?: string;
+    [extra: string]: unknown;
+}
+export declare class VouchlineError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly field: string | null | undefined;
+    readonly details: ErrorDetails;
+    constructor(status: number, details: ErrorDetails);
+}
+/** 400: a field or the body is invalid (`field`, `details.errors`). */
+export declare class ValidationError extends VouchlineError {
+}
+/** 401: missing, invalid, revoked or expired API key. */
+export declare class AuthenticationError extends VouchlineError {
+}
+/** 402: plan limit, credit exhausted (`details.buy_credit`) or budget reached. */
+export declare class PaymentRequiredError extends VouchlineError {
+}
+/** 403: the key lacks a scope (`requiredScope`), is test-mode, or the plan blocks the API. */
+export declare class PermissionDeniedError extends VouchlineError {
+    get requiredScope(): string | undefined;
+}
+export declare class NotFoundError extends VouchlineError {
+}
+/** 409: conflict, e.g. `run_not_finished`, `idempotency_in_progress`, `already_tracked`. */
+export declare class ConflictError extends VouchlineError {
+}
+/** 429: per-key rate limit; `retryAfter` is in seconds. */
+export declare class RateLimitError extends VouchlineError {
+    readonly retryAfter: number | undefined;
+    constructor(status: number, details: ErrorDetails, retryAfter: number | undefined);
+}
+export declare class ServerError extends VouchlineError {
+}
+/** The request never got an HTTP answer (DNS, TLS, reset, timeout). */
+export declare class ConnectionError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function parseErrorBody(status: number, body: unknown): ErrorDetails;
+export declare function errorFor(status: number, body: unknown, retryAfter?: number): VouchlineError;

package/dist/errors.js

@@ -0,0 +1,84 @@
+/** Typed errors for every non-2xx answer, read from the API's one error envelope. */
+export class VouchlineError extends Error {
+    status;
+    code;
+    requestId;
+    field;
+    details;
+    constructor(status, details) {
+        super(details.message);
+        this.name = new.target.name;
+        this.status = status;
+        this.code = details.code;
+        this.requestId = details.request_id;
+        this.field = details.field;
+        this.details = details;
+    }
+}
+/** 400: a field or the body is invalid (`field`, `details.errors`). */
+export class ValidationError extends VouchlineError {
+}
+/** 401: missing, invalid, revoked or expired API key. */
+export class AuthenticationError extends VouchlineError {
+}
+/** 402: plan limit, credit exhausted (`details.buy_credit`) or budget reached. */
+export class PaymentRequiredError extends VouchlineError {
+}
+/** 403: the key lacks a scope (`requiredScope`), is test-mode, or the plan blocks the API. */
+export class PermissionDeniedError extends VouchlineError {
+    get requiredScope() {
+        return typeof this.details.required_scope === "string" ? this.details.required_scope : undefined;
+    }
+}
+export class NotFoundError extends VouchlineError {
+}
+/** 409: conflict, e.g. `run_not_finished`, `idempotency_in_progress`, `already_tracked`. */
+export class ConflictError extends VouchlineError {
+}
+/** 429: per-key rate limit; `retryAfter` is in seconds. */
+export class RateLimitError extends VouchlineError {
+    retryAfter;
+    constructor(status, details, retryAfter) {
+        super(status, details);
+        this.retryAfter = retryAfter;
+    }
+}
+export class ServerError extends VouchlineError {
+}
+/** The request never got an HTTP answer (DNS, TLS, reset, timeout). */
+export class ConnectionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ConnectionError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseErrorBody(status, body) {
+    const inner = isRecord(body) && isRecord(body.error) ? body.error : undefined;
+    if (inner && typeof inner.code === "string" && typeof inner.message === "string") {
+        return { ...inner, code: inner.code, message: inner.message };
+    }
+    return { code: `http_${status}`, message: `HTTP ${status}` };
+}
+export function errorFor(status, body, retryAfter) {
+    const details = parseErrorBody(status, body);
+    if (status === 400)
+        return new ValidationError(status, details);
+    if (status === 401)
+        return new AuthenticationError(status, details);
+    if (status === 402)
+        return new PaymentRequiredError(status, details);
+    if (status === 403)
+        return new PermissionDeniedError(status, details);
+    if (status === 404)
+        return new NotFoundError(status, details);
+    if (status === 409)
+        return new ConflictError(status, details);
+    if (status === 429)
+        return new RateLimitError(status, details, retryAfter);
+    if (status >= 500)
+        return new ServerError(status, details);
+    return new VouchlineError(status, details);
+}