@vestiarion/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vestiarion contributors
+
+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.

package/README.md

@@ -0,0 +1,100 @@
+# @vestiarion/sdk
+
+A typed client for the [Vestiarion](https://www.vestiarion.xyz) API and its signed webhooks:
+
+- every `/api/v1` endpoint, with its types;
+- pagination that reads every page;
+- retries that never add a record twice;
+- checks for webhook signatures and ledger entries.
+
+It has no dependencies, and runs on Node 20 or later, Deno, Bun and edge runtimes such as Cloudflare Workers.
+
+## Install
+
+```bash
+npm install https://www.vestiarion.xyz/sdk/vestiarion-sdk-0.1.0.tgz
+```
+
+pnpm, Yarn and Bun take the same URL. The package is ESM only.
+
+## Read
+
+```ts
+import { Vestiarion } from "@vestiarion/sdk";
+
+const vestiarion = new Vestiarion({ apiKey: process.env.VESTIARION_API_KEY! });
+
+const status = await vestiarion.status.get();
+const { data: held, page } = await vestiarion.invoices.list({ status: "held" });
+const verification = await vestiarion.ledger.verify();
+
+for await (const invoice of vestiarion.invoices.listAll({ direction: "payable" })) {
+  console.log(invoice.id, invoice.status, invoice.agentReasoning);
+}
+```
+
+An owner or admin creates a workspace API key on the workspace's Settings page. Keep it on a server: it reads the whole
+workspace.
+
+## Add records
+
+A key with write access ("Can also add counterparties and invoices") adds counterparties and invoices.
+- The agent decides each invoice as it decides one typed into the console, with every guardrail.
+- An address added this way waits for a person in the workspace to confirm it.
+
+```ts
+const counterparty = await vestiarion.counterparties.create(
+  { name: "Quill Studio", role: "vendor", address: "0x5b2d8c1f0e7a4936b8d1c0e2f3a4b5c6d7e8f901", paymentLimit: "500" },
+  { idempotencyKey: "crm-vendor-1042" }
+);
+const invoice = await vestiarion.invoices.create(
+  { counterpartyId: counterparty.id, amount: "420.00", dueDate: "2026-10-31", poReference: "PO-4012", goodsReceived: true },
+  { idempotencyKey: "billing-inv-2026-0042" }
+);
+```
+
+Pass your own record's id as `idempotencyKey`, so that your own retries cannot add it twice either.
+
+## Errors and retries
+
+Every failure is a `VestiarionError`. It carries:
+- `status`;
+- `code`: the API's error code, or `network_error`, `timeout` or `invalid_response`;
+- `message`;
+- `retryAfter`.
+
+A request is retried twice by default after:
+- a `429`, waiting as long as `Retry-After` says, up to 60 seconds;
+- a `500`, `502`, `503` or `504`;
+- a timeout or a network failure.
+
+A write always carries an `Idempotency-Key`, so retrying it never adds the record twice.
+
+## Webhooks
+
+```ts
+import { verifyLedgerEntry, verifyWebhook } from "@vestiarion/sdk/webhooks";
+
+export async function POST(request: Request) {
+  const event = await verifyWebhook({
+    secret: process.env.VESTIARION_WEBHOOK_SECRET!,
+    payload: await request.text(),
+    signature: request.headers.get("vestiarion-signature"),
+  });
+  if (event.entry) {
+    const check = await verifyLedgerEntry(event.entry, process.env.VESTIARION_LEDGER_PUBLIC_KEY!);
+    if (check.ok === false) return new Response(check.reason, { status: 400 });
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+`verifyWebhook` throws a `WebhookVerificationError` unless the signature matches the raw body, signed less than 5
+minutes ago. `verifyLedgerEntry` checks the entry's own Ed25519 signature and chain hash, with the public key from the
+workspace's Audit page.
+
+The full guide: https://www.vestiarion.xyz/docs/get-started/sdk
+
+## Licence
+
+MIT

package/dist/canonical-json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The ledger's canonical JSON: keys sorted at every level, `undefined` left out, nothing else changed. An entry's
+ * `bodyHash` is SHA-256 of this over `{ actor, domain, action, summary, detail }`. tests/sdk-webhooks.test.ts holds it
+ * to the server's own (src/lib/canonical-json.ts).
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/canonical-json.js

@@ -0,0 +1,16 @@
+/**
+ * The ledger's canonical JSON: keys sorted at every level, `undefined` left out, nothing else changed. An entry's
+ * `bodyHash` is SHA-256 of this over `{ actor, domain, action, summary, detail }`. tests/sdk-webhooks.test.ts holds it
+ * to the server's own (src/lib/canonical-json.ts).
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${entries.join(",")}}`;
+}

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+import { type FetchLike } from "./http.js";
+import type { Counterparty, CounterpartyDetail, CreateCounterpartyInput, CreateInvoiceInput, Insights, Invoice, LedgerEntry, LedgerVerification, ListCounterpartiesParams, ListInvoicesParams, ListLedgerEntriesParams, ListMilestonesParams, Milestone, Page, Status, Treasury } from "./types.js";
+/** Where the API is, unless `baseUrl` says otherwise. */
+export declare const DEFAULT_BASE_URL = "https://www.vestiarion.xyz";
+export interface VestiarionOptions {
+    /** A workspace API key, `vxk_<prefix>_<secret>`. Keep it on a server: it reads the whole workspace. */
+    apiKey: string;
+    /** Where the API is. Defaults to `https://www.vestiarion.xyz`. Plain `http` is refused, except to localhost. */
+    baseUrl?: string;
+    /** Defaults to the runtime's `fetch`. */
+    fetch?: FetchLike;
+    /** How many times a request is retried after a 429, a 5xx, a timeout or a network failure. Defaults to 2. */
+    maxRetries?: number;
+    /** How long one attempt may take, in milliseconds. Defaults to 30 000. */
+    timeoutMs?: number;
+}
+/** One page of a collection, as the API answers it. */
+export interface List<T> {
+    data: T[];
+    page: Page;
+}
+/** A write's options: the `Idempotency-Key` that makes retrying it safe. Best: the record's id in your own system. */
+export interface WriteOptions {
+    idempotencyKey?: string;
+}
+export interface Collection<T, P> {
+    /** One page, `{ data, page }`. Pass `page.nextCursor` back as `cursor` for the next. */
+    list(params?: P): Promise<List<T>>;
+    /** Every page in turn, from `params.cursor` on. Store each `page.nextCursor` once its page is processed, to resume from it. */
+    pages(params?: P): AsyncIterable<List<T>>;
+    /** Every item, page after page, until the collection ends. */
+    listAll(params?: P): AsyncIterable<T>;
+}
+/**
+ * A client for one workspace's `/api/v1` (docs/superpowers/specs/2026-10-03-typescript-sdk-design.md R4): one method
+ * per operation, a resource's `data` returned as it is, and a collection paged by `list`, `pages` or `listAll`.
+ */
+export declare class Vestiarion {
+    readonly status: {
+        get(): Promise<Status>;
+    };
+    readonly ledger: Collection<LedgerEntry, ListLedgerEntriesParams> & {
+        verify(): Promise<LedgerVerification>;
+    };
+    readonly invoices: Collection<Invoice, ListInvoicesParams> & {
+        create(input: CreateInvoiceInput, options?: WriteOptions): Promise<Invoice>;
+    };
+    readonly counterparties: Collection<Counterparty, ListCounterpartiesParams> & {
+        get(id: string): Promise<CounterpartyDetail>;
+        create(input: CreateCounterpartyInput, options?: WriteOptions): Promise<Counterparty>;
+    };
+    readonly milestones: Collection<Milestone, ListMilestonesParams>;
+    readonly treasury: {
+        get(): Promise<Treasury>;
+    };
+    readonly insights: {
+        get(): Promise<Insights>;
+    };
+    constructor(options: VestiarionOptions);
+}

package/dist/client.js

@@ -0,0 +1,91 @@
+import { VestiarionError } from "./errors.js";
+import { createTransport } from "./http.js";
+/** Where the API is, unless `baseUrl` says otherwise. */
+export const DEFAULT_BASE_URL = "https://www.vestiarion.xyz";
+const KEY_FORMAT = /^vxk_[a-z2-7]{8}_[A-Za-z0-9_-]{43}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** An https URL, or plain http to this machine for local testing: the key must never travel in the clear. */
+function isSafeBaseUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname));
+}
+function collection(transport, path) {
+    const list = (params) => transport.request({ method: "GET", path, query: params });
+    async function* pages(params) {
+        let cursor = params?.cursor;
+        for (;;) {
+            const answer = await list({ ...params, cursor });
+            yield answer;
+            const next = answer.page.nextCursor;
+            if (!answer.page.hasMore || next === null)
+                return;
+            if (next === cursor)
+                throw new VestiarionError(200, "invalid_response", "The API answered the same cursor twice.");
+            cursor = next;
+        }
+    }
+    async function* listAll(params) {
+        for await (const answer of pages(params))
+            yield* answer.data;
+    }
+    return { list, pages, listAll };
+}
+/**
+ * A client for one workspace's `/api/v1` (docs/superpowers/specs/2026-10-03-typescript-sdk-design.md R4): one method
+ * per operation, a resource's `data` returned as it is, and a collection paged by `list`, `pages` or `listAll`.
+ */
+export class Vestiarion {
+    status;
+    ledger;
+    invoices;
+    counterparties;
+    milestones;
+    treasury;
+    insights;
+    constructor(options) {
+        if (typeof options?.apiKey !== "string" || !KEY_FORMAT.test(options.apiKey)) {
+            throw new TypeError("apiKey must be a workspace API key, shaped vxk_<prefix>_<secret>.");
+        }
+        const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        if (!isSafeBaseUrl(baseUrl))
+            throw new TypeError("baseUrl must be an https URL, or http to localhost: the key must not travel in the clear.");
+        // NaN here would retry a failing request forever, or time out every attempt.
+        const maxRetries = options.maxRetries ?? 2;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0)
+            throw new TypeError("maxRetries must be a whole number, 0 or more.");
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new TypeError("timeoutMs must be a positive number of milliseconds.");
+        const fetchImpl = options.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : undefined);
+        if (!fetchImpl)
+            throw new TypeError("This runtime has no fetch: pass one as options.fetch.");
+        const transport = createTransport({ apiKey: options.apiKey, baseUrl, fetch: fetchImpl, maxRetries, timeoutMs });
+        const one = (path) => transport.request({ method: "GET", path }).then((answer) => answer.data);
+        const add = (path, body, write) => transport.request({ method: "POST", path, body, idempotencyKey: write?.idempotencyKey }).then((answer) => answer.data);
+        this.status = { get: () => one("/api/v1/status") };
+        this.ledger = {
+            ...collection(transport, "/api/v1/ledger"),
+            verify: () => one("/api/v1/ledger/verify"),
+        };
+        this.invoices = {
+            ...collection(transport, "/api/v1/invoices"),
+            create: (input, write) => add("/api/v1/invoices", input, write),
+        };
+        this.counterparties = {
+            ...collection(transport, "/api/v1/counterparties"),
+            get: (id) => one(`/api/v1/counterparties/${encodeURIComponent(id)}`),
+            create: (input, write) => add("/api/v1/counterparties", input, write),
+        };
+        this.milestones = collection(transport, "/api/v1/milestones");
+        this.treasury = { get: () => one("/api/v1/treasury") };
+        this.insights = { get: () => one("/api/v1/insights") };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import type { ApiErrorCode } from "./types.js";
+/** What went wrong: one of the API's own codes, or what happened before an answer arrived. */
+export type VestiarionErrorCode = ApiErrorCode | "network_error" | "timeout" | "invalid_response";
+/**
+ * Every failed request (TypeScript SDK design R5): the HTTP status (0 when no answer arrived), a code to branch on,
+ * the API's own message, and how long the API's `Retry-After` asked to wait, in seconds.
+ */
+export declare class VestiarionError extends Error {
+    readonly status: number;
+    readonly code: VestiarionErrorCode;
+    readonly retryAfter: number | null;
+    readonly name = "VestiarionError";
+    constructor(status: number, code: VestiarionErrorCode, message: string, retryAfter?: number | null);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Every failed request (TypeScript SDK design R5): the HTTP status (0 when no answer arrived), a code to branch on,
+ * the API's own message, and how long the API's `Retry-After` asked to wait, in seconds.
+ */
+export class VestiarionError extends Error {
+    status;
+    code;
+    retryAfter;
+    name = "VestiarionError";
+    constructor(status, code, message, retryAfter = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,42 @@
+/** The part of `fetch` the SDK uses. Pass your own to route, record or proxy its requests. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+export interface TransportOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch: FetchLike;
+    maxRetries: number;
+    timeoutMs: number;
+    /** Waits that many milliseconds. Replaced in tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** A number in [0, 1), for the backoff's jitter. Replaced in tests. */
+    random?: () => number;
+    /** A fresh Idempotency-Key. Replaced in tests. */
+    uuid?: () => string;
+}
+export interface RequestSpec {
+    method: "GET" | "POST";
+    path: string;
+    query?: object;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+export interface Transport {
+    request<T>(spec: RequestSpec): Promise<T>;
+}
+/**
+ * Sends one request to the API and reads its answer (TypeScript SDK design R4–R6): the key as a bearer token, a write's
+ * body with its `Idempotency-Key`, retries after a 429, a 5xx, a timeout or a network failure, and every failure as a
+ * `VestiarionError`.
+ */
+export declare function createTransport(options: TransportOptions): Transport;

package/dist/http.js

@@ -0,0 +1,138 @@
+import { VestiarionError } from "./errors.js";
+import { API_ERROR_CODES } from "./types.js";
+import { VERSION } from "./version.js";
+/** The longest `Retry-After` the SDK waits out; a longer one is thrown, so a call never blocks for minutes (R6). */
+const RETRY_AFTER_CAP_S = 60;
+const BACKOFF_START_MS = 500;
+const BACKOFF_CAP_MS = 8_000;
+const RETRIED_STATUSES = new Set([500, 502, 503, 504]);
+const API_CODES = new Set(API_ERROR_CODES);
+function queryString(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        params.append(name, String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : "";
+}
+function retryAfterSeconds(header) {
+    return header !== null && /^\d+$/.test(header.trim()) ? Number(header.trim()) : null;
+}
+/** The API's own `{ error: { code, message } }`, or null for any other body. */
+function apiErrorOf(text) {
+    try {
+        const error = JSON.parse(text).error;
+        if (typeof error?.code === "string" && API_CODES.has(error.code) && typeof error.message === "string") {
+            return { code: error.code, message: error.message };
+        }
+    }
+    catch {
+        // Not JSON: a proxy's page, or nothing.
+    }
+    return null;
+}
+/** What a status means when its body is not the API's own error. */
+function codeForStatus(status) {
+    const named = {
+        400: "invalid_request",
+        401: "unauthorized",
+        403: "forbidden",
+        404: "not_found",
+        409: "conflict",
+        429: "rate_limited",
+        503: "unavailable",
+    };
+    return named[status] ?? (status >= 500 ? "internal" : "invalid_response");
+}
+/**
+ * Sends one request to the API and reads its answer (TypeScript SDK design R4–R6): the key as a bearer token, a write's
+ * body with its `Idempotency-Key`, retries after a 429, a 5xx, a timeout or a network failure, and every failure as a
+ * `VestiarionError`.
+ */
+export function createTransport(options) {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const random = options.random ?? Math.random;
+    const uuid = options.uuid ?? (() => globalThis.crypto.randomUUID());
+    // Called as a plain function: a runtime's own fetch throws "Illegal invocation" when called on another object.
+    const fetchImpl = options.fetch;
+    const base = options.baseUrl.replace(/\/+$/, "");
+    function backoff(attempt) {
+        const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_START_MS * 2 ** attempt);
+        return Math.round(ceiling / 2 + (random() * ceiling) / 2);
+    }
+    function retryDelay(status, retryAfter, attempt, method) {
+        const waitable = retryAfter !== null && retryAfter <= RETRY_AFTER_CAP_S;
+        if (status === 429)
+            return retryAfter === null ? backoff(attempt) : waitable ? retryAfter * 1000 : null;
+        if (RETRIED_STATUSES.has(status))
+            return waitable ? retryAfter * 1000 : backoff(attempt);
+        // The same key and body again: a conflict now means the first attempt is still being handled (R6).
+        if (status === 409 && method === "POST" && attempt > 0)
+            return backoff(attempt);
+        return null;
+    }
+    async function attemptOnce(url, init, attempt, method) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+        try {
+            let status;
+            let headers;
+            let text;
+            try {
+                const response = await fetchImpl(url, { ...init, signal: controller.signal });
+                status = response.status;
+                headers = response.headers;
+                text = await response.text();
+            }
+            catch {
+                const error = controller.signal.aborted
+                    ? new VestiarionError(0, "timeout", `No answer within ${options.timeoutMs} ms.`)
+                    : new VestiarionError(0, "network_error", "The request did not reach the API.");
+                return { error, retryInMs: backoff(attempt) };
+            }
+            if (status >= 200 && status < 300) {
+                try {
+                    return { value: JSON.parse(text) };
+                }
+                catch {
+                    return { error: new VestiarionError(status, "invalid_response", "The API's answer was not JSON."), retryInMs: null };
+                }
+            }
+            const retryAfter = retryAfterSeconds(headers.get("retry-after"));
+            const own = apiErrorOf(text);
+            const error = new VestiarionError(status, own?.code ?? codeForStatus(status), own?.message ?? `The API answered HTTP ${status}.`, retryAfter);
+            return { error, retryInMs: retryDelay(status, retryAfter, attempt, method) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async function request(spec) {
+        const url = `${base}${spec.path}${queryString(spec.query)}`;
+        const headers = {
+            authorization: `Bearer ${options.apiKey}`,
+            accept: "application/json",
+            "user-agent": `vestiarion-sdk-js/${VERSION}`,
+        };
+        let body;
+        if (spec.method === "POST") {
+            headers["content-type"] = "application/json";
+            // Every write carries a key, so retrying it can never add the record twice (R6).
+            headers["idempotency-key"] = spec.idempotencyKey ?? uuid();
+            body = JSON.stringify(spec.body ?? {});
+        }
+        for (let attempt = 0;; attempt += 1) {
+            const outcome = await attemptOnce(url, { method: spec.method, headers, body }, attempt, spec.method);
+            if ("value" in outcome)
+                return outcome.value;
+            if (outcome.retryInMs === null || attempt >= options.maxRetries)
+                throw outcome.error;
+            await sleep(outcome.retryInMs);
+        }
+    }
+    return { request };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Vestiarion, DEFAULT_BASE_URL, type Collection, type List, type VestiarionOptions, type WriteOptions } from "./client.js";
+export { VestiarionError, type VestiarionErrorCode } from "./errors.js";
+export type { FetchLike } from "./http.js";
+export * from "./types.js";
+export { VERSION } from "./version.js";
+export { verifyLedgerEntry, verifyWebhook, WEBHOOK_TOLERANCE_SECONDS, WebhookVerificationError, type EntryCheck, type WebhookEvent, type WebhookLedgerEntry, type WebhookVerificationReason, } from "./webhooks.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Vestiarion, DEFAULT_BASE_URL } from "./client.js";
+export { VestiarionError } from "./errors.js";
+export * from "./types.js";
+export { VERSION } from "./version.js";
+export { verifyLedgerEntry, verifyWebhook, WEBHOOK_TOLERANCE_SECONDS, WebhookVerificationError, } from "./webhooks.js";

package/dist/types.d.ts

@@ -0,0 +1,383 @@
+/** One of a closed set, so a client can branch on it without parsing the message. */
+export declare const API_ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "invalid_request", "conflict", "rate_limited", "unavailable", "internal"];
+export type ApiErrorCode = (typeof API_ERROR_CODES)[number];
+/** What this workspace is, and what it can actually do. */
+export interface Status {
+    /** The workspace's name. */
+    businessName: string;
+    /** Payments and yield differ and are reported separately, as in the UI. `unavailable` means the workspace's Circle credentials are stored but could not be read: cycles refuse to pay then rather than simulate, so neither leg is live or simulated. */
+    provenance: {
+        payments: "live" | "simulate" | "unavailable";
+        yield: "live" | "simulate" | "unavailable";
+        screening: "live" | "simulate";
+    };
+    /** The workspace's clock, and when its last cycle ran. */
+    clock: {
+        mode: "real" | "simulate";
+        day: number;
+        lastCycleAt: string | null;
+    };
+    /** Running totals across the workspace. */
+    totals: {
+        decisionsLogged: number;
+        totalPaidOut: number;
+        flagged: number;
+    };
+    /** What is configured for this workspace, as flags and modes. Never carries a secret. */
+    configuration: Record<string, unknown>;
+    apiVersion: "v1";
+}
+/** One entry of the audit chain, which the API returns oldest first. */
+export interface LedgerEntry {
+    /** Monotonic within a workspace, but not gap-free; the hash chain proves continuity. */
+    seq: number;
+    id: string;
+    ts: string;
+    actor: string;
+    domain: string;
+    action: string;
+    summary: string;
+    detail: Record<string, unknown>;
+    /** Present so a consumer can verify the chain itself rather than trust us. */
+    bodyHash: string;
+    signature: string;
+    prevHash: string;
+    hash: string;
+    /** Which key signed the entry; `null` for entries written before key identity existed. A consumer verifying for itself needs this to pick the right key. */
+    signingKeyId: string | null;
+}
+/** The verdict of replaying the workspace's ledger: signatures, body hashes and hash continuity. */
+export interface LedgerVerification {
+    /** `true` verified, `false` broken, and `null` not checked, which is a third answer, not a soft failure. A workspace holding no public key has produced no evidence either way. */
+    valid: boolean | null;
+    checkedEntries: number;
+    /** The `seq` of the first entry that failed. Absent unless `valid` is `false`. */
+    brokenAt?: number;
+    /** Why the verdict is what it is, when it is not a plain `true`. */
+    reason?: string;
+    /** Configuration problems found on the way to this verdict; not about the chain. */
+    warnings?: Array<string>;
+}
+/** An invoice in the payable or receivable book, with the agent's reasoning. */
+export interface Invoice {
+    id: string;
+    direction: "payable" | "receivable";
+    status: string;
+    amount: number;
+    /** USDC or EURC: what `amount` is in, and what a payable is paid in. A EURC payable is checked against the counterparty's USDC limit at a quoted rate. */
+    currency: string;
+    memo: string | null;
+    poReference: string | null;
+    goodsReceived: boolean;
+    dueDate: string;
+    /** ISO timestamp the agent has committed to pay this on, once scheduled; else null. */
+    scheduledFor: string | null;
+    /** The early-payment discount this invoice carries, if any: the percent off and the deadline's ISO timestamp. */
+    earlyPayDiscount: {
+        percent: number;
+        deadline: string;
+    } | null;
+    decidedAt: string | null;
+    settledAt: string | null;
+    escalatedAt: string | null;
+    /** Why the agent ruled as it did, verbatim from the decision. */
+    agentReasoning: string | null;
+    /** An on-chain hash once the payment settled, else null: on Arc testnet, or for a payout from a Gateway balance the mint on the payee's chain. */
+    txHash: string | null;
+    /** What actually left once this invoice was paid; null otherwise, even while a submitted transfer already carries an amount. */
+    paidAmount: number | null;
+    counterparty: {
+        id: string;
+        name: string;
+        riskLevel: string;
+    } | null;
+    createdAt: string;
+}
+/** A vendor, client or contractor, with its risk tier and payment limits. */
+export interface Counterparty {
+    id: string;
+    name: string;
+    role: "vendor" | "client" | "contractor";
+    address: string | null;
+    chain: string | null;
+    jurisdiction: string | null;
+    riskLevel: "unscreened" | "clear" | "medium" | "high";
+    riskNotes: string | null;
+    /** The business's baseline payment limit for this counterparty. */
+    baselinePaymentLimit: number | null;
+    /** The current payment limit, derived from the risk tier. */
+    paymentLimit: number | null;
+    lastScreenedAt: string | null;
+    /** No history is different from a zero score and remains null. */
+    performanceScore: number | null;
+    performanceInputs: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** A counterparty, with its recent screening history. */
+export interface CounterpartyDetail {
+    id: string;
+    name: string;
+    role: "vendor" | "client" | "contractor";
+    address: string | null;
+    chain: string | null;
+    jurisdiction: string | null;
+    riskLevel: "unscreened" | "clear" | "medium" | "high";
+    riskNotes: string | null;
+    /** The business's baseline payment limit for this counterparty. */
+    baselinePaymentLimit: number | null;
+    /** The current payment limit, derived from the risk tier. */
+    paymentLimit: number | null;
+    lastScreenedAt: string | null;
+    /** No history is different from a zero score and remains null. */
+    performanceScore: number | null;
+    performanceInputs: Record<string, unknown> | null;
+    createdAt: string;
+    /** Up to 20 recent screenings, newest first. */
+    screeningHistory: Array<{
+        id: string;
+        riskLevel: string;
+        source: string;
+        notes: string | null;
+        rawScore: number | null;
+        matchedEntityId: string | null;
+        screeningMode: "live" | "simulate";
+        status: "complete" | "failed";
+        createdAt: string;
+    }>;
+}
+/** A contractor milestone, how it was verified, and whether it was paid. */
+export interface Milestone {
+    id: string;
+    title: string;
+    amount: number;
+    status: "pending" | "verified" | "paid" | "held" | "closed";
+    verificationSource: string | null;
+    verificationMethod: "unverified" | "github" | "manual" | "seed";
+    verificationStatus: "unverified" | "verified" | "not_merged" | "unavailable" | "failed";
+    verificationCheckedAt: string | null;
+    verifiedAt: string | null;
+    verificationDetail: Record<string, unknown>;
+    verified: boolean;
+    decidedAt: string | null;
+    settledAt: string | null;
+    /** When a person closed the milestone without paying it (status closed), else null. */
+    closedAt: string | null;
+    /** The reason the person gave for closing it without paying, else null. */
+    closeReason: string | null;
+    agentReasoning: string | null;
+    /** An on-chain hash when the payment settled on Arc, else null. */
+    txHash: string | null;
+    contractor: {
+        id: string;
+        name: string;
+        riskLevel: string;
+    } | null;
+    createdAt: string;
+}
+/** The workspace's accounts, reserve, obligations, latest forecast and recent treasury moves. */
+export interface Treasury {
+    accounts: Array<{
+        id: string;
+        name: string;
+        kind: "operating" | "reserve" | "chain";
+        chain: string;
+        token: string;
+        address: string | null;
+        balance: number;
+        apy: number;
+    }>;
+    /** The sum of the reserve accounts' balances. */
+    reservePosition: number;
+    /** From the latest cycle snapshot; null before any snapshot exists, never an invented zero. */
+    obligations: {
+        asOf: string | null;
+        dueWithin7Days: number | null;
+        dueWithin14Days: number | null;
+    };
+    latestForecast: {
+        id: string;
+        asOf: string;
+        horizonDays: number;
+        projectedInflow: number;
+        projectedOutflow: number;
+        liquidBalance: number;
+        recommendation: string | null;
+    } | null;
+    /** Up to 20 treasury moves, newest first. */
+    recentActions: Array<{
+        id: string;
+        action: "sweep_to_usyc" | "redeem_from_usyc" | "rebalance";
+        amount: number;
+        fromAccountId: string | null;
+        toAccountId: string | null;
+        reasoning: string | null;
+        createdAt: string;
+    }>;
+}
+/** The telemetry behind the Insights charts: the most recent transfers, cycle runs, snapshots, treasury moves and screenings, each oldest first. */
+export interface Insights {
+    transfers: Array<{
+        id: string;
+        targetType: "invoice" | "milestone";
+        targetId: string;
+        txRef: string;
+        feeUsd: number;
+        feeSource: "chain_reported" | "provider_estimate" | "simulated_profile";
+        settledInMs: number | null;
+        chain: string;
+        providerMode: "live" | "simulate";
+        executedAt: string;
+        status: string;
+    }>;
+    runs: Array<{
+        id: string;
+        startedAt: string;
+        finishedAt: string;
+        durationMs: number;
+        decisionCount: number;
+        paidCount: number;
+        heldCount: number;
+        flaggedCount: number;
+        awaitingInfoCount: number;
+        releasedCount: number;
+        modelDecisionCount: number;
+        heuristicDecisionCount: number;
+        guardrailOverrideCount: number;
+        /** Model verdicts that chose a different action from the rule-based policy. Null for cycles run before the comparison existed, never zero, which would claim perfect agreement over decisions never compared. */
+        referenceDisagreementCount: number | null;
+        /** A cycle that failed partway is not a quiet cycle, and must not read as one. Its counts are real but partial: they cover the stages that ran before it stopped, and nothing after. */
+        status: "running" | "completed" | "partial" | "failed";
+        failedStage: string | null;
+        errorMessage: string | null;
+        chainMode: "live" | "simulate";
+        screeningMode: "live" | "simulate";
+    }>;
+    snapshots: Array<{
+        id: string;
+        cycleRunId: string;
+        capturedAt: string;
+        totalLiquid: number;
+        openPayables: number;
+        openReceivables: number;
+        obligationsDue7d: number;
+        obligationsDue14d: number;
+        reservePosition: number;
+        chainMode: "live" | "simulate";
+    }>;
+    treasuryMoves: Array<{
+        id: string;
+        action: "sweep_to_usyc" | "redeem_from_usyc" | "rebalance";
+        amount: number;
+        createdAt: string;
+    }>;
+    screenings: Array<{
+        id: string;
+        counterpartyId: string;
+        counterpartyName: string;
+        riskLevel: string;
+        previousRiskLevel: string | null;
+        tierChanged: boolean;
+        mode: "live" | "simulate";
+        source: string;
+        status: "complete" | "failed";
+        createdAt: string;
+    }>;
+}
+/** Where this page sits in the collection. */
+export interface Page {
+    /** Pass back as `?cursor=` to continue. Null when the end is reached. */
+    nextCursor: string | null;
+    /** Whether another page follows this one. */
+    hasMore: boolean;
+    /** How many items this response carries. */
+    count: number;
+}
+/** An invoice to add. The agent decides a payable as one typed in, with every guardrail, usually within a minute. */
+export interface CreateInvoiceInput {
+    /** `payable`, a bill the business pays, which is the default, or `receivable`, one it is owed. */
+    direction?: "payable" | "receivable";
+    /** The counterparty's `id`, from `GET /api/v1/counterparties` or from the answer that added it. */
+    counterpartyId: string;
+    /** What it bills, in `currency`, with at most 6 decimal places. A decimal string such as `"1250.50"` keeps it exact; a number is read the same way. */
+    amount: string | number;
+    /** `USDC`, the default, or `EURC`. */
+    currency?: "USDC" | "EURC";
+    /** The day it is due, as `YYYY-MM-DD`. */
+    dueDate: string;
+    /** What it is for, up to 280 characters. */
+    memo?: string;
+    /** The purchase order it bills against, up to 100 characters. */
+    poReference?: string;
+    /** Whether what it bills for has arrived. Defaults to `false`. Without it, or without `poReference`, the agent asks for the missing detail instead of paying. */
+    goodsReceived?: boolean;
+    /** A discount for paying by `deadline`. The agent weighs it against what the cash would earn in the reserve until `dueDate`. */
+    earlyPayDiscount?: {
+        /** The percent off, greater than 0 and less than 100, with at most 2 decimal places. */
+        percent: string | number;
+        /** The last day it applies, as `YYYY-MM-DD`, on or before `dueDate`. */
+        deadline: string;
+    };
+}
+/** A counterparty to add. It is screened as one added in the console. */
+export interface CreateCounterpartyInput {
+    /** 2 to 160 characters. */
+    name: string;
+    /** `vendor` or `contractor`, whom the business pays, or `client`, who pays the business. */
+    role: "vendor" | "client" | "contractor";
+    /** Where the agent pays it. An address added through the API waits for a person in the workspace to confirm it on Counterparties; until then the agent pays nothing to it. */
+    address?: string;
+    /** The chain the address receives on. Defaults to `ARC-TESTNET`; only a vendor can be paid on another chain. */
+    chain?: "ARC-TESTNET" | "BASE-SEPOLIA" | "ARB-SEPOLIA" | "ETH-SEPOLIA";
+    /** Where it is based, up to 80 characters; screening uses it. */
+    jurisdiction?: string;
+    /** The most the agent pays it in one payment, in USDC, with up to 6 decimal places. Required for a vendor or a contractor. */
+    paymentLimit?: string | number;
+    /** Where it is emailed once a payment to it is confirmed. */
+    noticeEmail?: string;
+}
+/** The query parameters of `list-ledger-entries`. */
+export interface ListLedgerEntriesParams {
+    /** How many items to return. Defaults to 50; a larger value is capped at 200. */
+    limit?: number;
+    /** The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. */
+    cursor?: string;
+    /** Only entries in this domain. */
+    domain?: string;
+    /** Only entries written by this actor. */
+    actor?: string;
+}
+/** The query parameters of `list-invoices`. */
+export interface ListInvoicesParams {
+    /** How many items to return. Defaults to 50; a larger value is capped at 200. */
+    limit?: number;
+    /** The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. */
+    cursor?: string;
+    /** Only payables, or only receivables. */
+    direction?: "payable" | "receivable";
+    /** Only invoices in this status. */
+    status?: "pending" | "matched" | "scheduled" | "paid" | "held" | "flagged" | "awaiting_info" | "received" | "rejected";
+    /** Only invoices from or to this counterparty. */
+    counterpartyId?: string;
+}
+/** The query parameters of `list-counterparties`. */
+export interface ListCounterpartiesParams {
+    /** How many items to return. Defaults to 50; a larger value is capped at 200. */
+    limit?: number;
+    /** The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. */
+    cursor?: string;
+    /** Only counterparties with this role. */
+    role?: "vendor" | "client" | "contractor";
+    /** Only counterparties at this risk tier. */
+    riskLevel?: "unscreened" | "clear" | "medium" | "high";
+}
+/** The query parameters of `list-milestones`. */
+export interface ListMilestonesParams {
+    /** How many items to return. Defaults to 50; a larger value is capped at 200. */
+    limit?: number;
+    /** The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. */
+    cursor?: string;
+    /** Only milestones in this status. */
+    status?: "pending" | "verified" | "paid" | "held" | "closed";
+    /** Only milestones for this contractor. */
+    contractorId?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+// Generated from the API's OpenAPI document (/api/v1/openapi.json) by `npm run sdk:types`, with
+// scripts/lib/sdk-types.ts. Do not edit it by hand: tests/sdk-types.test.ts fails when it differs from what the
+// generator renders now.
+/** One of a closed set, so a client can branch on it without parsing the message. */
+export const API_ERROR_CODES = ["unauthorized", "forbidden", "not_found", "invalid_request", "conflict", "rate_limited", "unavailable", "internal"];

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version, sent in every request's `User-Agent`. tests/sdk-package.test.ts holds it to package.json. */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** This package's version, sent in every request's `User-Agent`. tests/sdk-package.test.ts holds it to package.json. */
+export const VERSION = "0.1.0";

package/dist/webhooks.d.ts

@@ -0,0 +1,61 @@
+import type { LedgerEntry } from "./types.js";
+/**
+ * Checking what Vestiarion sends (docs/superpowers/specs/2026-10-03-typescript-sdk-design.md R7), with Web Crypto
+ * alone:
+ * - a webhook delivery's `Vestiarion-Signature`, as src/lib/webhooks/sign.ts signs it;
+ * - a ledger entry's own Ed25519 signature and chain hash, as the receipt page checks them
+ *   (src/lib/receipts/verify.ts).
+ */
+/** How far a delivery's timestamp may be from now, in seconds, as the server's own check allows. */
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+/** A ledger entry as a delivery carries it: `GET /api/v1/ledger`'s fields, without the row `id`. */
+export type WebhookLedgerEntry = Omit<LedgerEntry, "id">;
+export interface WebhookEvent {
+    /** The delivery's id, the same on every retry of it: de-duplicate on it. */
+    id: string;
+    type: "ledger.appended" | "webhook.test";
+    createdAt: string;
+    workspace: {
+        slug: string;
+    };
+    /** The entry appended. `ledger.appended` only. */
+    entry?: WebhookLedgerEntry;
+}
+export type WebhookVerificationReason = "missing" | "malformed" | "expired" | "mismatch";
+export declare class WebhookVerificationError extends Error {
+    readonly reason: WebhookVerificationReason;
+    readonly name = "WebhookVerificationError";
+    constructor(reason: WebhookVerificationReason, message: string);
+}
+/** `ok: null` is not a failure: no key known here could check the entry. */
+export type EntryCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+} | {
+    ok: null;
+    reason: string;
+};
+/**
+ * The event a delivery carries, once its `Vestiarion-Signature` proves Vestiarion sent this exact body, within
+ * `toleranceSeconds` of `now`. Pass the raw request body as it arrived: a re-serialized copy differs byte for byte.
+ * Throws a `WebhookVerificationError` otherwise; nothing is parsed before the signature checks out.
+ */
+export declare function verifyWebhook(input: {
+    secret: string;
+    payload: string;
+    signature: string | null | undefined;
+    toleranceSeconds?: number;
+    now?: Date;
+}): Promise<WebhookEvent>;
+/**
+ * Whether a ledger entry is authentic, as the receipt page checks one:
+ * - its content matches `bodyHash`, SHA-256 of the canonical JSON of `{ actor, domain, action, summary, detail }`;
+ * - `signature` is the workspace key's Ed25519 signature over the 32 bytes of `bodyHash`;
+ * - `hash` is SHA-256 of `prevHash + bodyHash + signature`.
+ *
+ * `keys` is the PEM from the workspace's Audit page, or a map of key id to PEM. A key counts only under its true id, the
+ * first 16 hex characters of SHA-256 of its SPKI encoding.
+ */
+export declare function verifyLedgerEntry(entry: WebhookLedgerEntry, keys: string | Record<string, string>): Promise<EntryCheck>;

package/dist/webhooks.js

@@ -0,0 +1,154 @@
+import { canonicalJson } from "./canonical-json.js";
+/**
+ * Checking what Vestiarion sends (docs/superpowers/specs/2026-10-03-typescript-sdk-design.md R7), with Web Crypto
+ * alone:
+ * - a webhook delivery's `Vestiarion-Signature`, as src/lib/webhooks/sign.ts signs it;
+ * - a ledger entry's own Ed25519 signature and chain hash, as the receipt page checks them
+ *   (src/lib/receipts/verify.ts).
+ */
+/** How far a delivery's timestamp may be from now, in seconds, as the server's own check allows. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+export class WebhookVerificationError extends Error {
+    reason;
+    name = "WebhookVerificationError";
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const TIMESTAMP = /^\d{1,15}$/;
+const HEX_SHA256 = /^[0-9a-f]{64}$/;
+function subtle() {
+    return globalThis.crypto.subtle;
+}
+function utf8(text) {
+    return new TextEncoder().encode(text);
+}
+function hexToBytes(hex) {
+    const clean = hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(hex) ? hex : "";
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i += 1)
+        bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+async function sha256Hex(data) {
+    return Array.from(new Uint8Array(await subtle().digest("SHA-256", data)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function pemToDer(pem) {
+    const binary = atob(pem.replace(/-----(BEGIN|END) PUBLIC KEY-----/g, "").replace(/\s+/g, ""));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * The event a delivery carries, once its `Vestiarion-Signature` proves Vestiarion sent this exact body, within
+ * `toleranceSeconds` of `now`. Pass the raw request body as it arrived: a re-serialized copy differs byte for byte.
+ * Throws a `WebhookVerificationError` otherwise; nothing is parsed before the signature checks out.
+ */
+export async function verifyWebhook(input) {
+    const tolerance = input.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    // NaN in either would make every timestamp "within" the window, and turn replay protection off.
+    if (!Number.isFinite(tolerance) || tolerance < 0)
+        throw new TypeError("toleranceSeconds must be a number of seconds, 0 or more.");
+    const nowMs = (input.now ?? new Date()).getTime();
+    if (!Number.isFinite(nowMs))
+        throw new TypeError("now must be a valid Date.");
+    if (typeof input.payload !== "string") {
+        throw new WebhookVerificationError("malformed", "payload must be the raw request body as a string, not a parsed object.");
+    }
+    if (!input.signature)
+        throw new WebhookVerificationError("missing", "The delivery has no Vestiarion-Signature header.");
+    let t = null;
+    const candidates = [];
+    for (const part of input.signature.split(",")) {
+        const eq = part.indexOf("=");
+        if (eq <= 0)
+            throw new WebhookVerificationError("malformed", "Vestiarion-Signature is not t=<seconds>,v1=<hex>.");
+        const name = part.slice(0, eq);
+        const value = part.slice(eq + 1);
+        if (name === "t") {
+            if (t !== null || !TIMESTAMP.test(value))
+                throw new WebhookVerificationError("malformed", "Vestiarion-Signature's timestamp is not valid.");
+            t = Number(value);
+        }
+        else if (name === "v1") {
+            if (!HEX_SHA256.test(value))
+                throw new WebhookVerificationError("malformed", "Vestiarion-Signature's v1 is not a hex HMAC-SHA256.");
+            candidates.push(value);
+        }
+    }
+    if (t === null || candidates.length === 0)
+        throw new WebhookVerificationError("malformed", "Vestiarion-Signature needs a t and a v1.");
+    const nowSeconds = Math.floor(nowMs / 1000);
+    if (Math.abs(nowSeconds - t) > tolerance)
+        throw new WebhookVerificationError("expired", `The delivery was signed more than ${tolerance} s from now.`);
+    const key = await subtle().importKey("raw", utf8(input.secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const signed = utf8(`${t}.${input.payload}`);
+    let match = false;
+    for (const candidate of candidates) {
+        // Every candidate is checked, so the time taken does not tell which one matched.
+        if (await subtle().verify("HMAC", key, hexToBytes(candidate), signed))
+            match = true;
+    }
+    if (!match)
+        throw new WebhookVerificationError("mismatch", "The signature does not match this body and secret.");
+    let event;
+    try {
+        event = JSON.parse(input.payload);
+    }
+    catch {
+        throw new WebhookVerificationError("malformed", "The delivery's body is not JSON.");
+    }
+    if (typeof event !== "object" || event === null || typeof event.type !== "string") {
+        throw new WebhookVerificationError("malformed", "The delivery's body is not a Vestiarion event.");
+    }
+    return event;
+}
+/** The keys an entry may be checked against: each filed under its true id, and only the one the entry names, if it names one. */
+async function candidateKeys(entry, keys) {
+    const pems = typeof keys === "string" ? [[null, keys]] : Object.entries(keys);
+    const filed = await Promise.all(pems.map(async ([id, pem]) => {
+        const der = pemToDer(pem);
+        const trueId = (await sha256Hex(der)).slice(0, 16);
+        return { der, trueId, genuine: id === null || id === trueId };
+    }));
+    const genuine = filed.filter((key) => key.genuine);
+    return (entry.signingKeyId ? genuine.filter((key) => key.trueId === entry.signingKeyId) : genuine).map((key) => key.der);
+}
+/**
+ * Whether a ledger entry is authentic, as the receipt page checks one:
+ * - its content matches `bodyHash`, SHA-256 of the canonical JSON of `{ actor, domain, action, summary, detail }`;
+ * - `signature` is the workspace key's Ed25519 signature over the 32 bytes of `bodyHash`;
+ * - `hash` is SHA-256 of `prevHash + bodyHash + signature`.
+ *
+ * `keys` is the PEM from the workspace's Audit page, or a map of key id to PEM. A key counts only under its true id, the
+ * first 16 hex characters of SHA-256 of its SPKI encoding.
+ */
+export async function verifyLedgerEntry(entry, keys) {
+    const body = canonicalJson({ actor: entry.actor, domain: entry.domain, action: entry.action, summary: entry.summary, detail: entry.detail });
+    if ((await sha256Hex(utf8(body))) !== entry.bodyHash)
+        return { ok: false, reason: "The entry's content does not match its body hash." };
+    const candidates = await candidateKeys(entry, keys);
+    if (candidates.length === 0)
+        return { ok: null, reason: "The key that signed this entry is not known here." };
+    let signed = false;
+    try {
+        for (const der of candidates) {
+            const key = await subtle().importKey("spki", der, { name: "Ed25519" }, false, ["verify"]);
+            if (await subtle().verify({ name: "Ed25519" }, key, hexToBytes(entry.signature), hexToBytes(entry.bodyHash))) {
+                signed = true;
+                break;
+            }
+        }
+    }
+    catch {
+        return { ok: null, reason: "The Ed25519 signature could not be checked here." };
+    }
+    if (!signed)
+        return { ok: false, reason: "The signature does not verify with the workspace's key." };
+    if ((await sha256Hex(utf8(entry.prevHash + entry.bodyHash + entry.signature))) !== entry.hash) {
+        return { ok: false, reason: "The entry's chain hash does not match." };
+    }
+    return { ok: true };
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vestiarion/sdk",
+  "version": "0.1.0",
+  "description": "A typed client for the Vestiarion API and its signed webhooks.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": { "node": ">=20" },
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./webhooks": { "types": "./dist/webhooks.d.ts", "import": "./dist/webhooks.js" }
+  },
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "homepage": "https://www.vestiarion.xyz/docs/get-started/sdk",
+  "repository": { "type": "git", "url": "git+https://github.com/duongnq2798/vestiarion.git", "directory": "sdk" },
+  "keywords": ["vestiarion", "stablecoin", "treasury", "arc", "usdc", "webhooks"]
+}