@belvador/api 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Belvador
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This software depends on the Sentry JavaScript SDK (https://github.com/getsentry/sentry-javascript),
+which is distributed under its own MIT License (Copyright (c) Functional Software, Inc. dba Sentry)
+in each of its npm packages. Belvador is not affiliated with or endorsed by Sentry.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @belvador/api
 
-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.
+Typed client for the [Belvador API](https://belvador.dev/docs/reference/api) (`https://api.belvador.dev`, OpenAPI 3.1).
+Every operation is called by its OpenAPI `operationId` with parameters in the API's wire names (snake_case);
+the operation table and parameter types are generated from the same registry as the OpenAPI document.
+
+```sh
+npm install @belvador/api
+```
+
+```ts
+import { BelvadorApiError, createClient } from "@belvador/api";
+
+const belvador = createClient({ token: process.env.BELVADOR_TOKEN! });
+
+const { data } = await belvador.call("issues.list", { status: "unresolved", period: "24h", limit: 20 });
+
+for await (const rows of belvador.pages("monitors.list", { limit: 100 })) console.log(rows.length);
+
+try {
+  await belvador.call(
+    "monitors.create",
+    {
+      project_id: 1,
+      slug: "nightly-backup",
+      name: "Nightly backup",
+      kind: "crontab",
+      schedule: { type: "crontab", value: "0 2 * * *" },
+      timezone: "UTC",
+      checkin_margin_min: 5,
+      max_runtime_min: 30,
+      failure_threshold: 1,
+      recovery_threshold: 1,
+      expected_environments: ["production"],
+    },
+    { idempotencyKey: crypto.randomUUID() },
+  );
+} catch (e) {
+  if (e instanceof BelvadorApiError && e.code === "API_SCOPE_INSUFFICIENT") console.log("needs", e.scope);
+}
+```
+
+- **Tokens**: a personal token (`blv_pat_`), service token (`blv_svc_`) or OAuth access token (`blv_oat_`).
+  Create one in Settings → API tokens. The client never puts the token in an error message.
+- **Errors** are RFC 9457 problem+json, surfaced as `BelvadorApiError` with a stable `code`,
+  `status`, `scope` (for `API_SCOPE_INSUFFICIENT`), `retryAfter` and `requestId`.
+- **Approvals**: sensitive operations (keys, members, tokens, alert destinations, node changes) throw
+  `APPROVAL_REQUIRED` with `e.approval` = `{ id, url, expiresAt, state }`. A person opens `url` on
+  belvador.dev and approves with their authenticator code; call again with the same `idempotencyKey`
+  (or `call("approvals.get", { approval_id })`) to read the outcome. Only https `/approve/<id>` links are kept.
+- **Retries**: reads, and writes sent with an `idempotencyKey`, are retried on 429 / 502–504 and network
+  errors (`retries`, default 2), honouring `Retry-After` up to 10 s. `NODE_OFFLINE` is not retried.
+- **Scopes**: `await belvador.scopes()` returns the token's effective scopes (the `Belvador-Scopes` header).
+- **Node data** (issues, events, spans, traces, logs) lives on your workspace's own node. With
+  `nodeReads: "edge"` the client asks `POST /v1/tickets` for a short-lived read ticket and reads
+  `edge.belvador.dev` directly, so the data never passes the API gateway; it falls back to the gateway
+  when the token may not hold a ticket.
+
+Node ≥ 20.10, Bun, Deno and modern browsers (any runtime with `fetch` and `AbortSignal.any`). MIT licensed.

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import { OPERATIONS, type OperationId, type OperationMeta, type OperationParams } from "./operations.gen.js";
+export declare const CLIENT_VERSION = "0.2.0";
+export declare const DEFAULT_BASE_URL = "https://api.belvador.dev";
+/** Personal (`blv_pat_`), service (`blv_svc_`) or OAuth access (`blv_oat_`) token. */
+export declare const TOKEN_PATTERN: RegExp;
+/** Response header naming the credential's effective scopes. */
+export declare const SCOPES_HEADER = "belvador-scopes";
+export type ClientOptions = {
+    /** `blv_pat_…`, `blv_svc_…` or an OAuth access token `blv_oat_…`. */
+    token: string;
+    /** Default `https://api.belvador.dev`. Plain http only for localhost. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Where node data (issues, events, spans, logs) is read:
+     * `gateway` (default) through api.belvador.dev; `edge` straight from edge.belvador.dev with a
+     * short-lived ticket from `POST /v1/tickets`, so the data never passes the API gateway.
+     */
+    nodeReads?: "gateway" | "edge";
+    /** Per request, default 30 000 ms. */
+    timeoutMs?: number;
+    /** Retries for reads and for writes sent with an Idempotency-Key (429, 502–504, network). Default 2. */
+    retries?: number;
+    userAgent?: string;
+};
+export type CallOptions = {
+    /** Makes a write safe to retry: the same key and body answer once (24 h). */
+    idempotencyKey?: string;
+    /** ETag from the last read, for operations that need `If-Match`. */
+    ifMatch?: string;
+    signal?: AbortSignal;
+};
+export type ApiResult<T = unknown> = {
+    status: number;
+    data: T;
+    etag: string | null;
+    requestId: string | null;
+    /** A replayed answer to the same Idempotency-Key. */
+    replayed: boolean;
+    /** Where the answer came from. */
+    via: "gateway" | "edge";
+};
+export type Page<T = unknown> = {
+    data: T[];
+    next_cursor: string | null;
+    complete: boolean;
+};
+export type PagedOperationId = {
+    [K in OperationId]: (typeof OPERATIONS)[K]["paged"] extends true ? K : never;
+}[OperationId];
+type Args<Id extends OperationId> = Record<string, never> extends OperationParams[Id] ? [params?: OperationParams[Id], opts?: CallOptions] : [params: OperationParams[Id], opts?: CallOptions];
+export interface BelvadorClient {
+    /** One API operation by its OpenAPI `operationId`, with parameters in wire names. */
+    call<Id extends OperationId>(id: Id, ...args: Args<Id>): Promise<ApiResult>;
+    /** Every page of a list operation (follows `next_cursor`, at most `maxPages`). */
+    pages<Id extends PagedOperationId>(id: Id, params?: OperationParams[Id], opts?: CallOptions & {
+        maxPages?: number;
+    }): AsyncGenerator<unknown[], void, undefined>;
+    /** The credential's effective scopes (asks the API once when nothing answered yet). */
+    scopes(): Promise<string[]>;
+}
+/** Wire parameters → path, query (GET) or JSON body; the same split the MCP tools use. */
+export declare function requestParts(meta: OperationMeta, params: Record<string, unknown>): {
+    path: string;
+    query: string;
+    body: Record<string, unknown> | undefined;
+};
+/** A client for the Belvador API (`https://api.belvador.dev`, OpenAPI 3.1). */
+export declare function createClient(options: ClientOptions): BelvadorClient;
+export {};

package/dist/client.js

@@ -0,0 +1,290 @@
+import { BelvadorApiError, errorFrom } from "./errors.js";
+import { nodeErrorWord, nodeReadRequest, nodeRefusal, nodeWindowMissing, NODE_REFUSAL_STATUS, reshapeNodeAnswer, } from "./node-wire.gen.js";
+import { OPERATIONS } from "./operations.gen.js";
+export const CLIENT_VERSION = "0.2.0";
+export const DEFAULT_BASE_URL = "https://api.belvador.dev";
+/** Personal (`blv_pat_`), service (`blv_svc_`) or OAuth access (`blv_oat_`) token. */
+export const TOKEN_PATTERN = /^blv_(pat|svc|oat)_[A-Za-z0-9_-]{20,200}$/;
+/** Response header naming the credential's effective scopes. */
+export const SCOPES_HEADER = "belvador-scopes";
+const NODE_RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
+const TICKET_MARGIN_MS = 30_000;
+const EDGE_OFF_MS = 5 * 60_000;
+const MAX_RETRY_AFTER_S = 10;
+const NO_RETRY_CODES = new Set(["NODE_OFFLINE", "PUBLIC_API_PAUSED"]);
+const isLocalHost = (u) => ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+function checkedOrigin(raw, what) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new TypeError(`${what} is not a URL`);
+    }
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocalHost(u)))
+        throw new TypeError(`${what} must use https`);
+    return u;
+}
+function timeoutSignal(ms, outer) {
+    const t = AbortSignal.timeout(ms);
+    return outer ? AbortSignal.any([t, outer]) : t;
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new BelvadorApiError("ABORTED", 0));
+    const id = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(id);
+        reject(new BelvadorApiError("ABORTED", 0));
+    }, { once: true });
+});
+const queryValue = (v) => (typeof v === "string" ? v : JSON.stringify(v));
+/** Wire parameters → path, query (GET) or JSON body; the same split the MCP tools use. */
+export function requestParts(meta, params) {
+    const names = new Set(meta.pathParams);
+    const qs = new URLSearchParams();
+    const body = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || names.has(k))
+            continue;
+        if (meta.method === "GET")
+            qs.set(k, queryValue(v));
+        else
+            body[k] = v;
+    }
+    const path = meta.path.replace(/\{([a-z_]+)\}/g, (_, name) => {
+        const v = params[name];
+        if (v === undefined || v === null || v === "")
+            throw new BelvadorApiError("INVALID_INPUT", 400, { errors: [{ pointer: `/${name}`, code: "required" }] });
+        return encodeURIComponent(String(v));
+    });
+    return { path, query: qs.toString(), body: meta.method === "GET" ? undefined : body };
+}
+class Client {
+    #token;
+    #base;
+    #fetch;
+    #nodeReads;
+    #timeoutMs;
+    #retries;
+    #userAgent;
+    #scopes = null;
+    #ticket = null;
+    #ticketInFlight = null;
+    #edgeOffUntil = 0;
+    constructor(o) {
+        if (typeof o.token !== "string" || !TOKEN_PATTERN.test(o.token))
+            throw new TypeError("token must be a Belvador token (blv_pat_, blv_svc_ or blv_oat_)");
+        this.#token = o.token;
+        this.#base = checkedOrigin(o.baseUrl ?? DEFAULT_BASE_URL, "baseUrl").origin;
+        this.#fetch = o.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#nodeReads = o.nodeReads ?? "gateway";
+        this.#timeoutMs = o.timeoutMs ?? 30_000;
+        this.#retries = Math.max(0, Math.min(5, o.retries ?? 2));
+        this.#userAgent = o.userAgent ?? `belvador-api-js/${CLIENT_VERSION}`;
+    }
+    async call(id, ...args) {
+        const meta = OPERATIONS[id];
+        if (!meta)
+            throw new BelvadorApiError("NOT_FOUND", 404, { detail: "unknown_operation" });
+        const params = (args[0] ?? {});
+        const opts = args[1] ?? {};
+        if (this.#nodeReads === "edge" && meta.node?.path.startsWith("q/") && Date.now() >= this.#edgeOffUntil) {
+            const direct = await this.#edgeRead(meta, meta.node, params, opts);
+            if (direct)
+                return direct;
+        }
+        return this.#gateway(meta, params, opts);
+    }
+    async *pages(id, params, opts = {}) {
+        let cursor = null;
+        const max = opts.maxPages ?? 100;
+        for (let i = 0; i < max; i++) {
+            const p = { ...(params ?? {}), ...(cursor ? { cursor } : {}) };
+            const r = await this.call(id, p, opts);
+            const page = r.data;
+            yield Array.isArray(page?.data) ? page.data : [];
+            cursor = page?.next_cursor ?? null;
+            if (!cursor)
+                return;
+        }
+    }
+    async scopes() {
+        if (this.#scopes)
+            return [...this.#scopes];
+        try {
+            await this.#gateway(OPERATIONS["workspace.get"], {}, {});
+        }
+        catch (e) {
+            // A refusal after authentication still names the scopes; only a bad token has none.
+            if (!this.#scopes)
+                throw e;
+        }
+        return [...(this.#scopes ?? [])];
+    }
+    #noteScopes(res) {
+        const h = res.headers.get(SCOPES_HEADER);
+        if (h !== null)
+            this.#scopes = h.split(" ").filter(Boolean);
+    }
+    async #send(url, init, retryable, signal) {
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(url, { ...init, signal: timeoutSignal(this.#timeoutMs, signal) });
+            }
+            catch {
+                if (signal?.aborted)
+                    throw new BelvadorApiError("ABORTED", 0);
+                if (retryable && attempt < this.#retries) {
+                    await sleep(250 * 2 ** attempt + Math.random() * 100, signal);
+                    continue;
+                }
+                throw new BelvadorApiError("UNAVAILABLE", 0, { detail: "network_error" });
+            }
+            if (!retryable || attempt >= this.#retries || ![429, 502, 503, 504].includes(res.status))
+                return res;
+            const err = await errorFrom(res.clone());
+            if (NO_RETRY_CODES.has(err.code))
+                return res;
+            const wait = err.retryAfter ? Math.min(err.retryAfter, MAX_RETRY_AFTER_S) * 1000 : 250 * 2 ** attempt;
+            if (err.retryAfter && err.retryAfter > MAX_RETRY_AFTER_S)
+                return res;
+            await sleep(wait + Math.random() * 100, signal);
+        }
+    }
+    async #gateway(meta, params, opts) {
+        const parts = requestParts(meta, params);
+        const headers = {
+            authorization: `Bearer ${this.#token}`,
+            accept: "application/json",
+            "user-agent": this.#userAgent,
+        };
+        if (parts.body !== undefined)
+            headers["content-type"] = "application/json";
+        if (opts.idempotencyKey)
+            headers["idempotency-key"] = opts.idempotencyKey;
+        if (opts.ifMatch)
+            headers["if-match"] = opts.ifMatch;
+        const res = await this.#send(`${this.#base}${parts.path}${parts.query ? `?${parts.query}` : ""}`, {
+            method: meta.method,
+            headers,
+            ...(parts.body !== undefined ? { body: JSON.stringify(parts.body) } : {}),
+        }, meta.method === "GET" || !!opts.idempotencyKey, opts.signal);
+        this.#noteScopes(res);
+        if (res.status === 401)
+            this.#ticket = null;
+        if (!res.ok)
+            throw await errorFrom(res);
+        const text = await res.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new BelvadorApiError("UNAVAILABLE", res.status, { detail: "invalid_json" });
+        }
+        return {
+            status: res.status,
+            data,
+            etag: res.headers.get("etag"),
+            requestId: res.headers.get("belvador-request-id"),
+            replayed: res.headers.get("idempotent-replayed") === "true",
+            via: "gateway",
+        };
+    }
+    /** A read ticket, reused until 30 s before it ends; null = read through the gateway instead. */
+    async #readTicket(fresh) {
+        if (!fresh && this.#ticket && this.#ticket.expiresAt - Date.now() > TICKET_MARGIN_MS)
+            return this.#ticket;
+        this.#ticketInFlight ??= (async () => {
+            try {
+                const r = await this.#gateway(OPERATIONS["tickets.create"], { scope: "read" }, {});
+                const t = r.data;
+                if (typeof t?.ticket !== "string" || typeof t.node_url !== "string")
+                    return null;
+                // The ticket only ever goes to https (plain http only to localhost while testing locally).
+                let node;
+                try {
+                    node = new URL(t.node_url);
+                }
+                catch {
+                    return null;
+                }
+                const localTest = isLocalHost(new URL(this.#base)) && isLocalHost(node) && node.protocol === "http:";
+                if (node.protocol !== "https:" && !localTest)
+                    return null;
+                this.#ticket = {
+                    ticket: t.ticket,
+                    nodeUrl: t.node_url.replace(/\/+$/, ""),
+                    expiresAt: Date.parse(String(t.expires_at)) || Date.now() + 60_000,
+                    scopes: Array.isArray(t.scopes) ? t.scopes.map(String) : [],
+                };
+                return this.#ticket;
+            }
+            catch (e) {
+                if (e instanceof BelvadorApiError && (e.code === "API_SCOPE_INSUFFICIENT" || e.code === "API_FORBIDDEN")) {
+                    this.#edgeOffUntil = Date.now() + EDGE_OFF_MS;
+                    return null;
+                }
+                throw e;
+            }
+            finally {
+                this.#ticketInFlight = null;
+            }
+        })();
+        return this.#ticketInFlight;
+    }
+    /** Node data straight from the edge with a read ticket; null when the gateway should answer. */
+    async #edgeRead(meta, route, params, opts) {
+        const wire = { ...meta.defaults, ...params };
+        if (nodeWindowMissing(route, wire))
+            throw new BelvadorApiError("QUERY_WINDOW_REQUIRED", NODE_REFUSAL_STATUS.QUERY_WINDOW_REQUIRED);
+        const req = nodeReadRequest(route, wire);
+        if (!req)
+            throw new BelvadorApiError("INVALID_INPUT", NODE_REFUSAL_STATUS.INVALID_INPUT);
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const t = await this.#readTicket(attempt > 0);
+            if (!t || !t.scopes.includes(meta.scope))
+                return null;
+            const res = await this.#send(`${t.nodeUrl}/${req.path}${req.query ? `?${req.query}` : ""}`, { method: "GET", headers: { authorization: `Bearer ${t.ticket}`, accept: "application/json" } }, false, // like the gateway: a node answer is final (NODE_BUSY carries its own Retry-After)
+            opts.signal).catch((e) => {
+                if (e instanceof BelvadorApiError && e.code === "ABORTED")
+                    throw e;
+                throw new BelvadorApiError("NODE_OFFLINE", NODE_REFUSAL_STATUS.NODE_OFFLINE);
+            });
+            const len = Number(res.headers.get("content-length") ?? "0");
+            if (len > NODE_RESPONSE_MAX_BYTES)
+                throw new BelvadorApiError("UNAVAILABLE", 503, { detail: "response_too_large" });
+            const text = await res.text();
+            if (text.length > NODE_RESPONSE_MAX_BYTES)
+                throw new BelvadorApiError("UNAVAILABLE", 503, { detail: "response_too_large" });
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                throw new BelvadorApiError("UNAVAILABLE", 503);
+            }
+            if (res.status === 401 && attempt === 0) {
+                this.#ticket = null;
+                continue;
+            }
+            if (res.ok)
+                return { status: 200, data: reshapeNodeAnswer(route.list, body), etag: null, requestId: null, replayed: false, via: "edge" };
+            if (res.status === 401)
+                throw new BelvadorApiError("UNAVAILABLE", 503);
+            const r = nodeRefusal(res.status, nodeErrorWord(body));
+            throw new BelvadorApiError(r.code, r.status, {
+                ...(r.detail ? { detail: r.detail } : {}),
+                ...(r.retryAfter ? { retryAfter: r.retryAfter } : {}),
+                ...(r.code === "API_SCOPE_INSUFFICIENT" ? { scope: meta.scope } : {}),
+            });
+        }
+        return null;
+    }
+}
+/** A client for the Belvador API (`https://api.belvador.dev`, OpenAPI 3.1). */
+export function createClient(options) {
+    return new Client(options);
+}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * An API refusal (RFC 9457 problem+json) or a transport failure, as a stable `code`.
+ * The token never appears in a message.
+ */
+export declare class BelvadorApiError extends Error {
+    readonly name = "BelvadorApiError";
+    /** Stable error code, e.g. `API_SCOPE_INSUFFICIENT`, `NODE_OFFLINE`, `RATE_LIMITED`. */
+    readonly code: string;
+    /** HTTP status (0 when the request never got an answer). */
+    readonly status: number;
+    readonly title: string | undefined;
+    readonly detail: string | undefined;
+    /** The scope to ask for when `code` is `API_SCOPE_INSUFFICIENT`. */
+    readonly scope: string | undefined;
+    /** Seconds to wait before trying again (429 / 503). */
+    readonly retryAfter: number | undefined;
+    readonly requestId: string | undefined;
+    /** Field errors: JSON pointers into the request with a code. */
+    readonly errors: ReadonlyArray<{
+        pointer: string;
+        code: string;
+    }> | undefined;
+    /**
+     * `APPROVAL_REQUIRED` (403): the approval a person gives on belvador.dev. Retry the same call
+     * with the same Idempotency-Key after they approved to get the stored result.
+     */
+    readonly approval: Approval | undefined;
+    constructor(code: string, status: number, extra?: {
+        title?: string;
+        detail?: string;
+        scope?: string;
+        retryAfter?: number;
+        requestId?: string;
+        errors?: ReadonlyArray<{
+            pointer: string;
+            code: string;
+        }>;
+        approval?: Approval;
+    });
+}
+export type ApprovalState = "pending" | "approved" | "executed" | "rejected" | "expired" | "failed";
+export type Approval = {
+    id: string;
+    url: string;
+    expiresAt: string;
+    state: ApprovalState;
+};
+/** Approval members of a problem body; only an https `/approve/<id>` link is accepted. */
+export declare function approvalFrom(body: Record<string, unknown>): Approval | undefined;
+/** An error answer → BelvadorApiError (problem+json fields, scope challenge, Retry-After). */
+export declare function errorFrom(res: Response): Promise<BelvadorApiError>;

package/dist/errors.js

@@ -0,0 +1,108 @@
+/**
+ * An API refusal (RFC 9457 problem+json) or a transport failure, as a stable `code`.
+ * The token never appears in a message.
+ */
+export class BelvadorApiError extends Error {
+    name = "BelvadorApiError";
+    /** Stable error code, e.g. `API_SCOPE_INSUFFICIENT`, `NODE_OFFLINE`, `RATE_LIMITED`. */
+    code;
+    /** HTTP status (0 when the request never got an answer). */
+    status;
+    title;
+    detail;
+    /** The scope to ask for when `code` is `API_SCOPE_INSUFFICIENT`. */
+    scope;
+    /** Seconds to wait before trying again (429 / 503). */
+    retryAfter;
+    requestId;
+    /** Field errors: JSON pointers into the request with a code. */
+    errors;
+    /**
+     * `APPROVAL_REQUIRED` (403): the approval a person gives on belvador.dev. Retry the same call
+     * with the same Idempotency-Key after they approved to get the stored result.
+     */
+    approval;
+    constructor(code, status, extra = {}) {
+        super(extra.title ? `${code}: ${extra.title}` : extra.detail ? `${code}: ${extra.detail}` : code);
+        this.code = code;
+        this.status = status;
+        this.title = extra.title;
+        this.detail = extra.detail;
+        this.scope = extra.scope;
+        this.retryAfter = extra.retryAfter;
+        this.requestId = extra.requestId;
+        this.errors = extra.errors;
+        this.approval = extra.approval;
+    }
+}
+const APPROVAL_STATES = ["pending", "approved", "executed", "rejected", "expired", "failed"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Approval members of a problem body; only an https `/approve/<id>` link is accepted. */
+export function approvalFrom(body) {
+    const id = body["approval_id"];
+    const url = body["approval_url"];
+    const exp = body["expires_at"];
+    const state = body["state"];
+    if (typeof id !== "string" || !UUID.test(id) || typeof url !== "string" || url.length > 300)
+        return undefined;
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const local = u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+    if ((u.protocol !== "https:" && !local) || !u.pathname.endsWith(`/approve/${id}`))
+        return undefined;
+    if (typeof exp !== "string" || Number.isNaN(Date.parse(exp)))
+        return undefined;
+    if (typeof state !== "string" || !APPROVAL_STATES.includes(state))
+        return undefined;
+    return { id, url: u.toString(), expiresAt: exp, state: state };
+}
+const str = (v, max = 500) => typeof v === "string" && v ? v.slice(0, max) : undefined;
+/** An error answer → BelvadorApiError (problem+json fields, scope challenge, Retry-After). */
+export async function errorFrom(res) {
+    let body = {};
+    try {
+        const parsed = await res.json();
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            body = parsed;
+    }
+    catch {
+        body = {};
+    }
+    const scope = /scope="([^"]+)"/.exec(res.headers.get("www-authenticate") ?? "")?.[1];
+    const retry = Number(res.headers.get("retry-after"));
+    const errors = Array.isArray(body["errors"])
+        ? body["errors"]
+            .filter((e) => {
+            const o = e;
+            return !!e && typeof o.pointer === "string" && typeof o.code === "string";
+        })
+            .slice(0, 50)
+            .map((e) => ({ pointer: e.pointer, code: e.code }))
+        : undefined;
+    const code = str(body["code"], 64) ?? (res.status === 401 ? "API_CREDENTIAL_INVALID" : res.status === 429 ? "RATE_LIMITED" : "UNAVAILABLE");
+    const extra = {};
+    const title = str(body["title"]);
+    const detail = str(body["detail"]);
+    const requestId = str(body["request_id"], 64) ?? str(res.headers.get("belvador-request-id"), 64);
+    if (title)
+        extra.title = title;
+    if (detail)
+        extra.detail = detail;
+    if (scope)
+        extra.scope = scope;
+    if (Number.isFinite(retry) && retry > 0)
+        extra.retryAfter = retry;
+    if (requestId)
+        extra.requestId = requestId;
+    if (errors?.length)
+        extra.errors = errors;
+    const approval = approvalFrom(body);
+    if (approval)
+        extra.approval = approval;
+    return new BelvadorApiError(code, res.status, extra);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CLIENT_VERSION, createClient, DEFAULT_BASE_URL, requestParts, SCOPES_HEADER, TOKEN_PATTERN, type ApiResult, type BelvadorClient, type CallOptions, type ClientOptions, type Page, type PagedOperationId, } from "./client.js";
+export { BelvadorApiError, type Approval, type ApprovalState } from "./errors.js";
+export { API_VERSION, OPERATIONS, type HttpMethod, type OperationId, type OperationMeta, type OperationParams, } from "./operations.gen.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CLIENT_VERSION, createClient, DEFAULT_BASE_URL, requestParts, SCOPES_HEADER, TOKEN_PATTERN, } from "./client.js";
+export { BelvadorApiError } from "./errors.js";
+export { API_VERSION, OPERATIONS, } from "./operations.gen.js";

package/dist/node-wire.gen.d.ts

@@ -0,0 +1,41 @@
+export type NodeReadRoute = {
+    /** `q/...` with `{snake}` placeholders. */
+    path: string;
+    /** List answers: the node field holding the rows, answered as `data`. */
+    list?: string;
+    /** `start`/`end` required. */
+    window?: boolean;
+};
+/** Wire arguments → the node path (placeholders filled) and query string; null when a path value is missing. */
+export declare function nodeReadRequest(route: NodeReadRoute, wire: Record<string, unknown>): {
+    path: string;
+    query: string;
+} | null;
+/** Window routes need both ends; the node and the gateway judge the size against the plan. */
+export declare function nodeWindowMissing(route: NodeReadRoute, wire: Record<string, unknown>): boolean;
+/** A node list answer as the API's page: `{data, next_cursor, complete, ...rest}`. */
+export declare function reshapeNodeAnswer(list: string | undefined, body: unknown): unknown;
+/** HTTP status of the codes a node read can end in (equal to `apiHttpStatus`; a test holds them equal). */
+export declare const NODE_REFUSAL_STATUS: {
+    readonly NOT_FOUND: 404;
+    readonly API_SCOPE_INSUFFICIENT: 403;
+    readonly API_FORBIDDEN: 403;
+    readonly NODE_BUSY: 429;
+    readonly QUERY_TIMEOUT: 422;
+    readonly NODE_OFFLINE: 503;
+    readonly QUERY_WINDOW_REQUIRED: 400;
+    readonly QUERY_WINDOW_TOO_LARGE: 400;
+    readonly INVALID_INPUT: 400;
+    readonly UNAVAILABLE: 503;
+};
+export type NodeRefusalCode = keyof typeof NODE_REFUSAL_STATUS;
+export type NodeRefusal = {
+    code: NodeRefusalCode;
+    status: number;
+    detail?: string;
+    retryAfter?: number;
+};
+/** A node error (status + its fixed `error` word) → the API error code; nothing else from the payload. */
+export declare function nodeRefusal(status: number, error: string): NodeRefusal;
+/** The node's `error` word from a parsed body ("" when absent). */
+export declare function nodeErrorWord(body: unknown): string;