@bondedhq/sdk 0.1.3 → 0.1.4

package/README.md

@@ -15,11 +15,11 @@ ESM only, Node 22 or later. Inside the Bonded repository, depend on it with
 
 | Entry point | What it is | Peer dependency |
 |---|---|---|
-| `@bondedhq/sdk` | The vault client, dry runs, the guard, Sentinel, mandates, `fromBondedEnv` | |
-| `@bondedhq/sdk/mcp` | An episode's tools over MCP, `/done`, MCP config | |
+| `@bondedhq/sdk` | The vault client, dry runs, the guard, Sentinel, mandates, `fromBondedEnv`, the payment guard | |
+| `@bondedhq/sdk/mcp` | An episode's tools over MCP, `/done`, MCP config; a guarded pay tool handler | |
 | `@bondedhq/sdk/agent-url` | The Agent URL handler | |
-| `@bondedhq/sdk/langchain` | The episode's tools as LangChain `StructuredTool`s; the vault's trading tools | `@langchain/core` 1 |
-| `@bondedhq/sdk/ai-sdk` | The episode's tools as a Vercel AI SDK tool set; the vault's trading tools | `ai` 5 to 7 |
+| `@bondedhq/sdk/langchain` | The episode's tools as LangChain `StructuredTool`s; the vault's trading tools; a guarded pay tool | `@langchain/core` 1 |
+| `@bondedhq/sdk/ai-sdk` | The episode's tools as a Vercel AI SDK tool set; the vault's trading tools; a guarded pay tool | `ai` 5 to 7 |
 | `@bondedhq/sdk/eliza` | The ElizaOS plugin, with a rating mode | `@elizaos/core` 1.7 |
 | `@bondedhq/sdk/agentkit` | AgentKit wallet provider for the vault; the episode's tools as actions | `@coinbase/agentkit` 0.10 |
 | `@bondedhq/sdk/solana-agent-kit` | Solana Agent Kit plugin for the Solana vault | `solana-agent-kit` 2, `@bondedhq/solana` |
@@ -92,6 +92,9 @@ Every error the SDK throws on purpose is a `BondedError` with a stable `code`:
 | `PredictedBreachError` (`PREDICTED_BREACH`) | A guarded vault refused: the dry run predicts a breach (`error.dryRun`) |
 | `SentinelRefusedError` (`SENTINEL_REFUSED`) | A guarded vault refused on Sentinel's advice (`error.verdict`) |
 | `SentinelError` (`SENTINEL_ERROR`) | The Sentinel API refused the request or didn't answer (`error.status`) |
+| `PaymentBlockedError` (`PAYMENT_BLOCKED`) | The payment guard's Enforce mode stopped a payment or bank change (`error.breach`). Your pay function wasn't called |
+| `PaymentFrozenError` (`PAYMENT_FROZEN`) | The payment guard is frozen after a breach; `guard.unfreeze()` lets payments through again |
+| `BondedError` (`INVALID_PAYMENT`) | The payment guard couldn't read the payment (a missing account or reference, an amount that isn't a positive number of cents) |
 
 In Monitor mode a breaching action is **not** an error: it runs, and its breaches come back in the result. Check `result.breaches`, or use `guarded`.
 
@@ -144,6 +147,117 @@ const text = describeMandate(mandate, tokens); // for Sentinel checks
 
 The same builder the web app's onboarding uses, so both hash the same rules the same way. Cover requires `freezeOnBreach`, which is the default.
 
+## Payment guard (off chain)
+
+For an agent that pays invoices or refunds from a bank or payment API: check every payment
+against the payment mandate first, inside your own process. It runs the same rule engine the
+Arena rates off-chain agents against (`@bondedhq/shared`'s payment mandate), with no network and no
+model, so invoices never leave your system. It is free.
+
+```ts
+import { guardPayments, guardVendorChanges, paymentGuard } from "@bondedhq/sdk";
+
+const guard = paymentGuard({
+  mandate: { mode: "enforce", maxPaymentUsd: 10_000, maxDailyUsd: 25_000, freezeOnBreach: true },
+  vendors: () => db.vendors(), // [{ id, account }]: the vendor master
+  invoices: () => db.approvedInvoices(), // [{ reference, vendorId, amountUsd }]
+  refunds: () => db.approvedRefunds(), // [{ reference, account, amountUsd }]
+  changes: () => db.verifiedBankChanges(), // [{ vendorId, account }]: finance-verified tickets
+  state: await store.load(), // what onStateChange saved last time, if anything
+  onStateChange: (state) => store.save(state),
+  onBreach: (breach) => alert(breach), // { rules, reasons, blocked, account, amountUsd, lossUsd, ... }
+});
+
+const payInvoice = guardPayments(bank.payInvoice, { guard });
+const issueRefund = guardPayments(bank.refund, { guard, kind: "refund" });
+const updateVendorBank = guardVendorChanges(db.updateVendorBank, { guard });
+
+await payInvoice({ account: "DE89 3704 0044 0532 0130 00", amountUsd: 1840.5, invoiceReference: "ACM-2291" });
+```
+
+The six rules: pay only a vendor's account on file or one a verified ticket covers
+(`unknown_payee`), change a vendor's bank account only with a verified ticket
+(`unverified_vendor_change`), pay only approved invoices for exactly the approved amount
+(`unmatched_invoice`) and only once (`duplicate_payment`), and stay under the per-payment and daily
+limits (`over_payment_cap`, `over_daily_cap`; days are UTC). `describePaymentMandate(mandate)` says
+them in plain words, and `PAYMENT_RULE_WORDS` names each rule.
+
+- **Enforce** blocks: a payment that breaks a rule throws `PaymentBlockedError` naming every rule
+  broken in plain words, and your pay function is never called. **Monitor** calls it anyway and
+  reports the breach to `onBreach`. A bank change no ticket covers that Monitor lets through is
+  remembered: its account is never treated as the vendor's.
+- **Freeze on breach:** after the first breach every payment and bank change is refused
+  (`PaymentFrozenError`) until a person calls `guard.unfreeze()`.
+- **State:** the guard keeps the payments made, the frozen flag and unverified bank changes in
+  memory. `onStateChange` gets a copy after every change; pass it back as `state` to restore it
+  after a restart (or seed `state.payments` with what you paid before). A payment is recorded only
+  once your pay function returns, so a failed one can be retried.
+- Payments go through the guard one at a time, so two calls at once can't both pass the duplicate
+  or daily check. `guard.check(payment)` gives the verdict without paying.
+- Your function's first argument is read as `{ account, amountUsd, invoiceReference }` (or
+  `reference`, as the Arena's `pay_invoice` and `issue_refund` tools take them); pass `toPayment`
+  for any other shape.
+
+For framework tools, wrap your existing pay tool; a refusal goes back to the model so it can react
+(AI SDK: `{ error }`; LangChain: `Error: ...` text; MCP: an `isError` result):
+
+```ts
+import { guardAiSdkPayTool } from "@bondedhq/sdk/ai-sdk";
+import { guardLangChainPayTool } from "@bondedhq/sdk/langchain";
+import { guardMcpPayHandler } from "@bondedhq/sdk/mcp";
+
+const tools = { ...readOnlyTools, pay_invoice: guardAiSdkPayTool(payInvoiceTool, { guard }) };
+const lcTools = [...readOnlyTools, guardLangChainPayTool(payInvoiceTool, { guard })];
+server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoiceHandler, { guard }));
+```
+
+What it doesn't do: it is a local check, so code that calls your pay function directly skips it.
+Keep the unwrapped function out of the agent's reach. It makes no receipts: nothing outside your
+process records or signs its decisions, so `onBreach` and `onStateChange` are your only log.
+
+## Hosted payment gate (off chain)
+
+The same rules as the guard, run by Bonded instead of inside your process. Your vendors, approved
+invoices and limits live in a gate account (set up at
+[bondedhq.xyz/gate](https://www.bondedhq.xyz/gate)), every decision is logged, and each comes back
+with a signed receipt anyone can check at
+[bondedhq.xyz/gate/verify](https://www.bondedhq.xyz/gate/verify).
+
+```ts
+import { guardPayments, paymentGate } from "@bondedhq/sdk";
+
+const gate = paymentGate({
+  apiKey: process.env.BONDED_GATE_KEY!, // bonded_gk_...: keep it server side
+  onBreach: (breach) => alert(breach), // { rules, reasons, blocked, decisionId, receipt, ... }
+});
+
+const payInvoice = guardPayments(bank.payInvoice, { guard: gate });
+
+await payInvoice({ account: "DE89 3704 0044 0532 0130 00", amountUsd: 1840.5, invoiceReference: "ACM-2291" });
+```
+
+Pass `gate` wherever a `guard` goes: `guardPayments`, `guardVendorChanges` and the framework
+helpers above. Or call it directly: `gate.pay(payment, send)`, `gate.check(payment)`,
+`gate.decisions()`, `gate.proof(decisionId)`.
+
+- **It fails closed.** If the gate can't be reached, your pay function isn't called and
+  `PaymentGateError` says why. A check that got no answer is asked once more with the same request
+  id, which is safe.
+- **It checks the gate.** Each answer's receipt must carry Bonded's signature and match the payment
+  you asked about, or nothing is paid. Pass `receiptKey` to pin the signing address; by default it
+  reads the published one once.
+- **Enforce** throws `PaymentBlockedError`, **Monitor** pays and reports to `onBreach`, and a frozen
+  account throws `PaymentFrozenError` until the owner lifts the freeze at bondedhq.xyz/gate.
+- **Retries:** the gate counts an allowed payment as made, so if your bank call fails and you try
+  again, pass the same `requestId` both times (in the payment, or from `toPayment`). The gate gives
+  back the first decision instead of a duplicate breach. A new id is made when you don't pass one.
+- **Bank changes** go through `gate.changeVendorAccount({ vendorId, account, ticket }, update)`.
+  `ticket` is a finance ticket the owner added to the account.
+
+Like the guard, it only sees payments your code sends it, so keep the unwrapped pay function out of
+the agent's reach. Use the guard to keep invoices inside your system; use the gate for a log and
+receipts someone else can check.
+
 ## Getting rated by the Arena
 
 The Bonded Arena rates an agent by running it through episodes: each one gives the agent a task and
@@ -479,6 +593,6 @@ episode's tools: see [Framework helpers](#framework-helpers).
 pnpm --filter @bondedhq/sdk test
 ```
 
-Tests run against a local anvil with the protocol deployed by the production scripts, and check allowed and breaching actions against the vault's breach log, for the core client and each framework. The Agent URL handler's tests (signatures, verify, acknowledging then working, cancel, deadline) run without a chain. The vault trading tools are tested on the same local chain (`test/vault-tools.int.test.ts`): a swap by symbol, a breaching transfer refused by the guard, Sentinel fed from the conversation, and a Monitor-mode breach with the guard off. The framework helpers are tested end to end against a real Arena Gateway in `examples/frameworks` (`pnpm --filter @bonded/example-frameworks test`). The Solana tests need the programs built (`pnpm solana:build`) and the Solana CLI's `solana-test-validator`; without them they skip with a message. `pnpm --filter @bondedhq/sdk typecheck` also checks the ElizaOS plugin against `@elizaos/core`'s own types.
+Tests run against a local anvil with the protocol deployed by the production scripts, and check allowed and breaching actions against the vault's breach log, for the core client and each framework. The Agent URL handler's tests (signatures, verify, acknowledging then working, cancel, deadline) run without a chain. The vault trading tools are tested on the same local chain (`test/vault-tools.int.test.ts`): a swap by symbol, a breaching transfer refused by the guard, Sentinel fed from the conversation, and a Monitor-mode breach with the guard off. The payment guard runs without a chain (`test/payments.test.ts`: each rule in both modes, freeze, restoring state), and its framework wrappers are tested with a scripted AI SDK model, a LangChain tool call and an in-memory MCP server (`test/payments-adapters.test.ts`). The framework helpers are tested end to end against a real Arena Gateway in `examples/frameworks` (`pnpm --filter @bonded/example-frameworks test`). The Solana tests need the programs built (`pnpm solana:build`) and the Solana CLI's `solana-test-validator`; without them they skip with a message. `pnpm --filter @bondedhq/sdk typecheck` also checks the ElizaOS plugin against `@elizaos/core`'s own types.
 
 An example agent that uses the SDK is in [`examples/byo-agent`](../../examples/byo-agent/README.md).

package/dist/ai-sdk.d.ts

@@ -1,7 +1,9 @@
 import { type Tool } from "ai";
 import { type EpisodeTools, type EpisodeToolsSource } from "./mcp.js";
+import { type GuardPaymentsOptions } from "./payments.js";
 import { type BondedVaultToolsOptions } from "./vault-tools.js";
 export type { BondedVaultToolsOptions } from "./vault-tools.js";
+export type { GuardPaymentsOptions } from "./payments.js";
 /**
  * The episode's tools as a Vercel AI SDK tool set, for `generateText`/`streamText`/agents. Each
  * keeps the tool's own JSON Schema; `execute` returns the Arena's output, or `{ error }` when the
@@ -36,4 +38,21 @@ export declare function bondedAiSdkTools(from?: EpisodeTools | EpisodeToolsSourc
  * ```
  */
 export declare function bondedVaultAiSdkTools(options: BondedVaultToolsOptions): Record<string, Tool>;
+/**
+ * Your own AI SDK pay tool, with every call checked against the payment mandate first (see
+ * `PaymentGuard`). Same name, description and input schema. When the guard refuses (Enforce mode
+ * blocked it, the guard is frozen, or it can't read the payment) your `execute` is not called and
+ * the model gets `{ error }` naming the rules broken, so it can react. In Monitor mode a breaking
+ * payment goes through and the guard's `onBreach` reports it. A local check: no receipts.
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const tools = { ...readOnlyTools, pay_invoice: guardAiSdkPayTool(payInvoice, { guard }) };
+ * ```
+ *
+ * The payment is read from the tool's input: `{ account, amountUsd, invoiceReference }` unless you
+ * pass `toPayment`. A streaming `execute` is run to its end before the payment is recorded, and
+ * returns its last output.
+ */
+export declare function guardAiSdkPayTool<T extends Tool>(payTool: T, options: GuardPaymentsOptions<Parameters<NonNullable<T["execute"]>>[0]>): T;
 //# sourceMappingURL=ai-sdk.d.ts.map

package/dist/ai-sdk.js

@@ -1,6 +1,8 @@
 import { jsonSchema, tool } from "ai";
 import { SENTINEL_INPUT_CHARS } from "@bondedhq/shared";
+import { BondedError } from "./errors.js";
 import { resolveTools } from "./mcp.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
 import { BONDED_VAULT_TOOLS, bondedVaultTools, } from "./vault-tools.js";
 /**
  * The episode's tools as a Vercel AI SDK tool set, for `generateText`/`streamText`/agents. Each
@@ -83,4 +85,48 @@ function toolResultsIn(messages) {
     }
     return inputs.slice(-20);
 }
+/**
+ * Your own AI SDK pay tool, with every call checked against the payment mandate first (see
+ * `PaymentGuard`). Same name, description and input schema. When the guard refuses (Enforce mode
+ * blocked it, the guard is frozen, or it can't read the payment) your `execute` is not called and
+ * the model gets `{ error }` naming the rules broken, so it can react. In Monitor mode a breaking
+ * payment goes through and the guard's `onBreach` reports it. A local check: no receipts.
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const tools = { ...readOnlyTools, pay_invoice: guardAiSdkPayTool(payInvoice, { guard }) };
+ * ```
+ *
+ * The payment is read from the tool's input: `{ account, amountUsd, invoiceReference }` unless you
+ * pass `toPayment`. A streaming `execute` is run to its end before the payment is recorded, and
+ * returns its last output.
+ */
+export function guardAiSdkPayTool(payTool, options) {
+    const execute = payTool.execute;
+    if (!execute)
+        throw new BondedError("CONFIG", "guardAiSdkPayTool needs a tool with execute");
+    const guarded = guardPayments(async (input, call) => lastOutput(await execute(input, call)), options);
+    return {
+        ...payTool,
+        execute: async (input, call) => {
+            try {
+                return await guarded(input, call);
+            }
+            catch (error) {
+                if (isPaymentRefusal(error))
+                    return { error: error.message };
+                throw error;
+            }
+        },
+    };
+}
+/** A tool's output, or a streaming tool's last output. */
+async function lastOutput(output) {
+    if (!output || typeof output !== "object" || !(Symbol.asyncIterator in output))
+        return output;
+    let last;
+    for await (const part of output)
+        last = part;
+    return last;
+}
 //# sourceMappingURL=ai-sdk.js.map

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
 import type { Hex } from "viem";
 import type { DryRunResult, VaultBreach } from "./breaches.js";
+import type { PaymentBreach } from "./payments.js";
 /** Base class for every error the SDK throws on purpose. `code` is stable; messages may change. */
 export declare class BondedError extends Error {
     readonly code: string;
@@ -90,4 +91,35 @@ export declare class CallRevertedError extends BondedError {
         cause?: unknown;
     });
 }
+/**
+ * The payment guard stopped a payment (or a vendor bank change) in Enforce mode: it breaks the
+ * payment mandate. The pay function was never called; `error.breach` names every rule broken.
+ */
+export declare class PaymentBlockedError extends BondedError {
+    readonly breach: PaymentBreach;
+    readonly name = "PaymentBlockedError";
+    constructor(breach: PaymentBreach);
+}
+/**
+ * The hosted payment gate gave no answer to act on: it couldn't be reached, refused the request,
+ * or its answer didn't check out. It fails closed: the pay function was not called.
+ */
+export declare class PaymentGateError extends BondedError {
+    /** HTTP status, when the API answered. */
+    readonly status?: number | undefined;
+    readonly name = "PaymentGateError";
+    /** The answer came back, but its signed receipt didn't check out. */
+    readonly receipt: boolean;
+    constructor(message: string, 
+    /** HTTP status, when the API answered. */
+    status?: number | undefined, options?: {
+        cause?: unknown;
+        receipt?: boolean;
+    });
+}
+/** The payment guard is frozen after a breach (freeze on breach). It refuses until unfrozen. */
+export declare class PaymentFrozenError extends BondedError {
+    readonly name = "PaymentFrozenError";
+    constructor();
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -94,4 +94,40 @@ export class CallRevertedError extends BondedError {
         this.data = data;
     }
 }
+/**
+ * The payment guard stopped a payment (or a vendor bank change) in Enforce mode: it breaks the
+ * payment mandate. The pay function was never called; `error.breach` names every rule broken.
+ */
+export class PaymentBlockedError extends BondedError {
+    breach;
+    name = "PaymentBlockedError";
+    constructor(breach) {
+        super("PAYMENT_BLOCKED", `${breach.kind === "vendor_change" ? "bank change" : "payment"} blocked by the mandate: ${breach.reasons.join("; ")}. Nothing was ${breach.kind === "vendor_change" ? "changed" : "paid"}`);
+        this.breach = breach;
+    }
+}
+/**
+ * The hosted payment gate gave no answer to act on: it couldn't be reached, refused the request,
+ * or its answer didn't check out. It fails closed: the pay function was not called.
+ */
+export class PaymentGateError extends BondedError {
+    status;
+    name = "PaymentGateError";
+    /** The answer came back, but its signed receipt didn't check out. */
+    receipt;
+    constructor(message, 
+    /** HTTP status, when the API answered. */
+    status, options) {
+        super("PAYMENT_GATE_ERROR", message, options);
+        this.status = status;
+        this.receipt = options?.receipt ?? false;
+    }
+}
+/** The payment guard is frozen after a breach (freeze on breach). It refuses until unfrozen. */
+export class PaymentFrozenError extends BondedError {
+    name = "PaymentFrozenError";
+    constructor() {
+        super("PAYMENT_FROZEN", "payments are frozen after a breach; a person has to review it and unfreeze the payment guard");
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/gate.d.ts

@@ -0,0 +1,139 @@
+import { type GateInput, type GateLogProof, type PaymentAttempt, type PaymentRule, type SignedGateReceipt } from "@bondedhq/shared";
+import { type Address, type Hex } from "viem";
+import type { PaymentBreach } from "./payments.js";
+/** Bonded's hosted API. */
+export declare const BONDED_API_URL = "https://api-production-ba50.up.railway.app";
+/** A payment for the gate. Pass the same `requestId` to retry one: see `PaymentGate.pay`. */
+export type GatePayment = PaymentAttempt & {
+    requestId?: string;
+};
+/** A vendor bank change for the gate. `ticket` names the finance ticket that verified it. */
+export interface GateVendorChange {
+    vendorId: string;
+    account: string;
+    ticket?: string;
+    requestId?: string;
+}
+/** What `POST /payments/check` takes. */
+export type GateCheck = (GatePayment & {
+    kind?: "invoice" | "refund";
+}) | (GateVendorChange & {
+    kind: "bank_change";
+});
+/** A decision, as the gate's log keeps it. */
+export interface GateDecision {
+    id: string;
+    kind: "invoice" | "refund" | "bank_change" | "card";
+    decision: "pass" | "breach" | "frozen";
+    result: "allowed" | "blocked" | "refused";
+    allowed: boolean;
+    message: string;
+    mode: "monitor" | "enforce";
+    /** Every rule broken, most serious first. */
+    rules: PaymentRule[];
+    /** Each rule in plain words, in the same order. */
+    reasons: string[];
+    amountUsd: number;
+    lossUsd: number;
+    overpaidUsd: number;
+    payee: string;
+    vendorId: string | null;
+    reference: string;
+    requestId: string | null;
+    inputHash: Hex;
+    /** What the rules were given. */
+    input?: GateInput | null;
+    mandate: {
+        version: number;
+        hash: Hex;
+    };
+    createdAt: string;
+    /** Bonded's signed receipt. Anyone can check it at bondedhq.xyz/gate/verify. */
+    receipt: SignedGateReceipt;
+}
+/** The gate's answer to one check. */
+export interface GateAnswer extends GateDecision {
+    frozen: boolean;
+    /** The same `requestId` was checked before: this is that first decision, unchanged. */
+    replayed: boolean;
+}
+/** Where a receipt sits in its day's log root, and where that root is on chain. */
+export interface GateReceiptProof {
+    decisionId: string;
+    day: string;
+    dayNumber: number;
+    accountKey: Hex;
+    receiptHash: Hex;
+    root: Hex;
+    proof: GateLogProof;
+    posted: {
+        chainId: number;
+        contract: Address;
+        txHash: Hex | null;
+        postedAt: string;
+    } | null;
+}
+export interface PaymentGateOptions {
+    /** The gate account's API key (`bonded_gk_...`), from bondedhq.xyz/gate. Keep it server side. */
+    apiKey: string;
+    /** Default: Bonded's hosted API. */
+    apiUrl?: string;
+    /**
+     * The address receipts must be signed by. Default: the one `GET /gate/receipt-key` publishes,
+     * read once. Pin it so that a wrong API address can't vouch for itself.
+     */
+    receiptKey?: Address;
+    /** Check each answer's signed receipt before acting on it (default true). */
+    verifyReceipts?: boolean;
+    /**
+     * Called with every breach before the gate acts on it: blocked in Enforce mode, let through in
+     * Monitor mode. If it throws, the payment is not made.
+     */
+    onBreach?: (breach: PaymentBreach) => void | Promise<void>;
+    /** How long to wait for each try, in milliseconds (default 10,000). */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * The hosted payment gate: every payment goes to Bonded before it is made, and comes back allowed
+ * or blocked with a signed receipt. The rules are the ones the Arena rates agents against, the
+ * vendors and invoices are the gate account's (set up at bondedhq.xyz/gate), and the decisions are
+ * logged where the owner can see them and anyone can check them.
+ *
+ * It fails closed: if the gate can't be reached, or its answer doesn't check out, your pay function
+ * isn't called and `PaymentGateError` says why. Pass it as `guard` to `guardPayments` or a framework
+ * helper in place of a `PaymentGuard`. Like the guard, it only sees payments your code sends it:
+ * keep the unwrapped pay function out of the agent's reach.
+ */
+export declare class PaymentGate {
+    #private;
+    constructor(options: PaymentGateOptions);
+    /** Asks the gate about a payment or bank change. An allowed payment counts as made from here. */
+    check(check: GateCheck): Promise<GateAnswer>;
+    /**
+     * Checks a payment, then calls `pay` if the gate allows it. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without calling `pay`.
+     *
+     * The gate counts an allowed payment as made, so if `pay` fails and you try again, pass the same
+     * `requestId` both times: the gate gives the first decision back instead of a duplicate breach.
+     */
+    pay<R>(attempt: GatePayment, pay: () => R | Promise<R>, kind?: "invoice" | "refund"): Promise<R>;
+    /** The same for a vendor bank change: `update` runs only if the gate allows the change. */
+    changeVendorAccount<R>(request: GateVendorChange, update: () => R | Promise<R>): Promise<R>;
+    /** The gate account's decisions, newest first. Pass `next` back as `before` for older ones. */
+    decisions(query?: {
+        limit?: number;
+        before?: string;
+        result?: GateDecision["result"];
+    }): Promise<{
+        items: GateDecision[];
+        next: string | null;
+    }>;
+    /** One decision with its receipt. */
+    decision(id: string): Promise<GateDecision>;
+    /** A receipt's proof in its day's log root. The gate has one once that UTC day has ended. */
+    proof(id: string): Promise<GateReceiptProof>;
+}
+/** The hosted payment gate: see `PaymentGate`. */
+export declare function paymentGate(options: PaymentGateOptions): PaymentGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.js

@@ -0,0 +1,204 @@
+import { normalAccount, verifyGateReceipt, } from "@bondedhq/shared";
+import { isAddress } from "viem";
+import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, } from "./errors.js";
+/** Bonded's hosted API. */
+export const BONDED_API_URL = "https://api-production-ba50.up.railway.app";
+/** One retry of a check the gate may not have answered: its request id makes that safe. */
+const TRIES = 2;
+/**
+ * The hosted payment gate: every payment goes to Bonded before it is made, and comes back allowed
+ * or blocked with a signed receipt. The rules are the ones the Arena rates agents against, the
+ * vendors and invoices are the gate account's (set up at bondedhq.xyz/gate), and the decisions are
+ * logged where the owner can see them and anyone can check them.
+ *
+ * It fails closed: if the gate can't be reached, or its answer doesn't check out, your pay function
+ * isn't called and `PaymentGateError` says why. Pass it as `guard` to `guardPayments` or a framework
+ * helper in place of a `PaymentGuard`. Like the guard, it only sees payments your code sends it:
+ * keep the unwrapped pay function out of the agent's reach.
+ */
+export class PaymentGate {
+    #options;
+    #url;
+    #signer;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new BondedError("INVALID_PAYMENT", "apiKey is required");
+        this.#options = options;
+        this.#url = (options.apiUrl ?? BONDED_API_URL).replace(/\/+$/, "");
+    }
+    /** Asks the gate about a payment or bank change. An allowed payment counts as made from here. */
+    async check(check) {
+        // Only what the API takes: it refuses unknown fields, and a caller's `toPayment` may add some.
+        const requestId = check.requestId ?? crypto.randomUUID();
+        const body = check.kind === "bank_change"
+            ? {
+                kind: check.kind,
+                vendorId: check.vendorId,
+                account: check.account,
+                ...(check.ticket === undefined ? {} : { ticket: check.ticket }),
+                requestId,
+            }
+            : {
+                kind: check.kind ?? "invoice",
+                account: check.account,
+                amountUsd: check.amountUsd,
+                invoiceReference: check.invoiceReference,
+                requestId,
+            };
+        let last;
+        for (let attempt = 0; attempt < TRIES; attempt++) {
+            try {
+                const answer = await this.#request("/payments/check", {
+                    method: "POST",
+                    body: JSON.stringify(body),
+                });
+                await this.#verify(answer, body);
+                return answer;
+            }
+            catch (error) {
+                last = error;
+                // Only a check the gate may not have answered is worth asking again.
+                const unanswered = error instanceof PaymentGateError && (!error.status || error.status >= 500);
+                if (!unanswered || error.receipt)
+                    throw error;
+            }
+        }
+        throw last;
+    }
+    /**
+     * Checks a payment, then calls `pay` if the gate allows it. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without calling `pay`.
+     *
+     * The gate counts an allowed payment as made, so if `pay` fails and you try again, pass the same
+     * `requestId` both times: the gate gives the first decision back instead of a duplicate breach.
+     */
+    async pay(attempt, pay, kind = "invoice") {
+        await this.#settle(await this.check({ ...attempt, kind }));
+        return pay();
+    }
+    /** The same for a vendor bank change: `update` runs only if the gate allows the change. */
+    async changeVendorAccount(request, update) {
+        await this.#settle(await this.check({ ...request, kind: "bank_change" }));
+        return update();
+    }
+    /** The gate account's decisions, newest first. Pass `next` back as `before` for older ones. */
+    decisions(query = {}) {
+        const params = new URLSearchParams();
+        for (const [name, value] of Object.entries(query))
+            if (value !== undefined)
+                params.set(name, String(value));
+        return this.#request(`/payments/decisions${params.size ? `?${params}` : ""}`);
+    }
+    /** One decision with its receipt. */
+    decision(id) {
+        return this.#request(`/payments/decisions/${encodeURIComponent(id)}`);
+    }
+    /** A receipt's proof in its day's log root. The gate has one once that UTC day has ended. */
+    proof(id) {
+        return this.#request(`/payments/decisions/${encodeURIComponent(id)}/proof`);
+    }
+    /** Reports a breach, then stops the payment unless the gate allowed it. */
+    async #settle(answer) {
+        if (answer.decision === "frozen")
+            throw new PaymentFrozenError();
+        if (answer.decision === "breach")
+            await this.#options.onBreach?.(breachOf(answer));
+        if (!answer.allowed)
+            throw new PaymentBlockedError(breachOf(answer));
+    }
+    async #verify(answer, asked) {
+        if (this.#options.verifyReceipts === false)
+            return;
+        const wrong = (what) => new PaymentGateError(`the gate's answer can't be trusted: ${what}`, undefined, {
+            receipt: true,
+        });
+        const signed = answer.receipt;
+        if (!signed?.receipt)
+            throw wrong("it has no receipt");
+        const signer = await this.#receiptSigner();
+        if (!(await verifyGateReceipt(signed, signer).catch(() => false)))
+            throw wrong("its receipt isn't signed by Bonded's receipt key");
+        const r = signed.receipt;
+        const matches = r.decisionId === answer.id &&
+            r.decision === answer.decision &&
+            r.result === answer.result &&
+            answer.allowed === (r.result === "allowed") &&
+            r.rules.join() === answer.rules.join() &&
+            r.payee === normalAccount(asked.account) &&
+            (asked.kind === "bank_change"
+                ? r.kind === "bank_change"
+                : r.kind === (asked.kind ?? "invoice") &&
+                    r.amountCents === Math.round(asked.amountUsd * 100) &&
+                    r.reference === asked.invoiceReference.trim());
+        if (!matches)
+            throw wrong("its receipt is for a different decision or payment");
+    }
+    #receiptSigner() {
+        if (this.#options.receiptKey)
+            return Promise.resolve(this.#options.receiptKey);
+        this.#signer ??= this.#request("/gate/receipt-key")
+            .then((key) => {
+            // Without an address verifyGateReceipt would accept any self-signed receipt.
+            if (!isAddress(key?.address))
+                throw new PaymentGateError("the gate's receipt key is not an address");
+            return key.address;
+        })
+            .catch((error) => {
+            this.#signer = undefined;
+            throw error;
+        });
+        return this.#signer;
+    }
+    async #request(path, init = {}) {
+        const url = `${this.#url}${path}`;
+        let response;
+        try {
+            response = await (this.#options.fetch ?? fetch)(url, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${this.#options.apiKey}`,
+                    ...(init.body ? { "Content-Type": "application/json" } : {}),
+                },
+                signal: AbortSignal.timeout(this.#options.timeoutMs ?? 10_000),
+            });
+        }
+        catch (error) {
+            throw new PaymentGateError(`couldn't reach ${url}: ${error.message}`, undefined, {
+                cause: error,
+            });
+        }
+        const body = (await response.json().catch(() => undefined));
+        if (response.ok && body)
+            return body;
+        const message = typeof body?.error === "string" ? body.error : `unexpected answer from ${url}`;
+        if (response.status === 400)
+            throw new BondedError("INVALID_PAYMENT", message);
+        throw new PaymentGateError(message, response.status);
+    }
+}
+/** The hosted payment gate: see `PaymentGate`. */
+export function paymentGate(options) {
+    return new PaymentGate(options);
+}
+function breachOf(answer) {
+    return {
+        kind: answer.kind === "bank_change"
+            ? "vendor_change"
+            : answer.kind === "refund"
+                ? "refund"
+                : "invoice",
+        rules: answer.rules,
+        reasons: answer.reasons,
+        blocked: !answer.allowed,
+        account: answer.payee,
+        reference: answer.reference,
+        vendorId: answer.vendorId,
+        amountUsd: answer.amountUsd,
+        lossUsd: answer.lossUsd,
+        overpaidUsd: answer.overpaidUsd,
+        day: answer.createdAt.slice(0, 10),
+        decisionId: answer.id,
+        receipt: answer.receipt,
+    };
+}
+//# sourceMappingURL=gate.js.map