@bondedhq/sdk 0.1.3 → 0.1.5

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,201 @@ 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.
+
+Payments with no invoices: set `invoiceMatching: false` on the mandate, and optionally
+`maxPaymentsPerHour`. A payment then needs a listed vendor and to stay within the limits, and
+`invoiceReference` is optional. `GATE_RULE_WORDS` adds the hourly rule's words. The hosted gate
+reads the same setting from your account, so your code doesn't change.
+
+- **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 }));
+```
+
+The OpenAI Agents SDK works the same way, and the model gets `Error: ...` text back:
+
+```ts
+import { Agent } from "@openai/agents";
+import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+
+const agent = new Agent({
+  name: "AP clerk",
+  tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoiceTool, { guard })],
+});
+```
+
+If the tool needs a person's approval (`needsApproval`), the run stops for that first. The guard
+still checks the payment once it is approved.
+
+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.
+
+### Budgets
+
+For many small payments to one payee, such as an API that charges $0.001 a call, ask for a budget
+and check each payment against it. The budget is checked once against the rules; each payment is
+checked against the budget with no rule check and no network call, in exact micro-dollars
+(millionths of a dollar), so $0.001 counts as $0.001. Budgets need `invoiceMatching: false`.
+
+```ts
+const budget = await guard.budget({ account: "0x1111111111111111111111111111111111111111", amountUsd: 1 });
+
+await budget.spend(1_000); // $0.001: throws PaymentBlockedError in Enforce mode if it doesn't fit
+await budget.close(); // the unspent part stops counting toward the day
+```
+
+- **The check:** the payee must be a vendor's account (`unknown_payee`), the whole budget must fit
+  in what's left of the day (`over_daily_cap`), and with `maxPaymentsPerHour` there must be room
+  for a payment (`over_hourly_limit`). Enforce throws `PaymentBlockedError`; Monitor opens it and
+  reports the breach.
+- **The terms** (`budget.terms`): the payee, the budget, the most one payment may be
+  (`maxPaymentUsd`, default the mandate's per-payment limit), how many payments it covers (what's
+  left of the hour, with an hourly limit) and its end (`ttlSeconds`, an hour at most).
+- **Each payment:** `spend(amountMicros)` checks it against the terms. One that doesn't fit breaks
+  `over_budget`: Enforce throws and doesn't count it; Monitor counts it and reports it. Spend
+  before you pay. `release(id)` takes back one the payee turned down.
+- **The day:** the whole budget counts toward the daily limit until `close()`; then what was spent,
+  rounded up to the cent. A budget past its end is closed the next time one is opened.
+- **The hosted gate:** `gate.budget(...)` is the same, with a signed receipt whose input commits to
+  the terms; the SDK checks the receipt, recomputes the input's hash and reruns its rules. Payments
+  go to the gate in the background and on `close()`, whose receipt commits to every one. Unclosed
+  budgets close themselves soon after they end.
+
+### x402
+
+For an agent that pays for APIs with [x402](https://x402.org): check each payment before the x402
+client signs it. Turn invoice matching off, and put each service's `payTo` address on the vendor
+list, so the agent pays only services you chose:
+
+```ts
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { x402Guard } from "@bondedhq/sdk/x402";
+
+const guard = paymentGate({ apiKey: process.env.BONDED_GATE_KEY! }); // or a local paymentGuard
+const x402 = x402Guard({ guard, budget: { amountUsd: 1 } });
+const client = x402.register(new x402Client().register("eip155:*", new ExactEvmScheme(signer)));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+
+// ...and when the agent stops:
+await x402.close();
+```
+
+- The first payment to a service opens a budget for it (`budget.amountUsd`, default $1, raised to
+  fit a bigger price). Each payment then checks against that budget, exact to the micro-dollar.
+  When it's used up or ends, the next payment closes it and opens another.
+- A refused payment is never signed: the request fails with the reason. Monitor mode signs it and
+  reports the breach.
+- A payment the server turns down (it answers 402 again, or settlement fails) is taken back. One
+  that settles is reported with its transaction hash.
+- Prices count only in USDC on the networks x402 lists it for (Base, Ethereum, Arbitrum, Polygon,
+  Avalanche and Solana, plus Base Sepolia and Solana devnet). A price in any other token is
+  refused; add your own dollar stablecoins with `assets`.
+- `guardX402Client(client, { guard })` registers a guard and returns the client, if you never close
+  budgets yourself. `x402Price(requirements)` gives the payee and exact price it reads.
+
+## 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 +677,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/budget.d.ts

@@ -0,0 +1,97 @@
+import { type BudgetTerms } from "@bondedhq/shared";
+import type { PaymentBreach } from "./payments.js";
+/**
+ * A budget: one check for many small payments to one payee (an x402 API, say). Ask for one with
+ * `guard.budget(...)` on the local `PaymentGuard` or the hosted `PaymentGate`; then check each
+ * payment with `spend` before making it. `spend` needs no network: it checks the payment against
+ * the budget's terms (the payee, the per-payment limit, how many payments it covers, its end, and
+ * what's left) in exact micro-dollars, so a $0.001 call counts as $0.001.
+ *
+ * In Enforce mode a payment that breaks the terms throws `PaymentBlockedError` and isn't counted;
+ * in Monitor mode it is counted and reported to `onBreach`. A hosted budget sends its payments to
+ * the gate in the background and on `close()`; closing it gets a receipt that commits to every one.
+ */
+export interface PaymentBudget {
+    /** The budget's id: the hosted gate's decision id, or a local one. */
+    readonly id: string;
+    /** What it allows: payee, budget, per-payment limit, payment count and end. */
+    readonly terms: Readonly<BudgetTerms>;
+    readonly mode: "monitor" | "enforce";
+    /** Micro-dollars counted so far, released payments left out. */
+    readonly spentMicros: number;
+    /** Payments counted so far. */
+    readonly payments: number;
+    /** Closed, or past its end. */
+    readonly closed: boolean;
+    /** What a payment of this size would break, in plain words; undefined when it fits. */
+    problem(amountMicros: number): string | undefined;
+    /** Check a payment against the terms and count it. See the interface's description. */
+    spend(amountMicros: number, options?: {
+        id?: string;
+        reference?: string;
+    }): Promise<BudgetSpend>;
+    /**
+     * Take back a payment that never went out (the payee turned it down). Only before it was sent to
+     * the gate; returns whether it was taken back.
+     */
+    release(spendId: string): boolean;
+    /** Attach what the payment settled as (an x402 transaction hash) before it is sent. */
+    settle(spendId: string, reference: string): void;
+    /** Send payments to the gate now (hosted budgets; nothing to do locally). */
+    flush(): Promise<void>;
+    /** Send what's left and close: the unspent part stops counting toward the day's limit. */
+    close(): Promise<void>;
+}
+/** A payment counted against a budget. */
+export interface BudgetSpend {
+    id: string;
+    amountMicros: number;
+    reference: string;
+    /** Unix milliseconds. */
+    atMs: number;
+}
+/** What `guard.budget(...)` takes. */
+export interface BudgetRequest {
+    /** The one account it pays: an x402 service's `payTo` address, say. */
+    account: string;
+    /** The budget, in US dollars with at most two decimals. */
+    amountUsd: number;
+    /** The most one payment may be, up to six decimals. Default: the mandate's per-payment limit. */
+    maxPaymentUsd?: number;
+    /** How long it lasts, 60 to 3,600 seconds (the default). */
+    ttlSeconds?: number;
+    /** Hosted gate: the same id again gives back the first budget instead of a second one. */
+    requestId?: string;
+}
+/** The bookkeeping both kinds of budget share: the terms check and the running totals. */
+export declare abstract class BudgetBase implements PaymentBudget {
+    #private;
+    readonly id: string;
+    readonly terms: Readonly<BudgetTerms>;
+    readonly mode: "monitor" | "enforce";
+    protected readonly now: () => number;
+    protected readonly onBreach?: ((breach: PaymentBreach) => void | Promise<void>) | undefined;
+    protected readonly counted: Map<string, BudgetSpend>;
+    constructor(id: string, terms: Readonly<BudgetTerms>, mode: "monitor" | "enforce", now: () => number, onBreach?: ((breach: PaymentBreach) => void | Promise<void>) | undefined);
+    get spentMicros(): number;
+    get payments(): number;
+    get closed(): boolean;
+    protected markClosed(): void;
+    problem(amountMicros: number): string | undefined;
+    spend(amountMicros: number, options?: {
+        id?: string;
+        reference?: string;
+    }): Promise<BudgetSpend>;
+    release(spendId: string): boolean;
+    settle(spendId: string, reference: string): void;
+    /** The spend was counted. */
+    protected abstract recorded(spend: BudgetSpend): Promise<void>;
+    /** Whether a counted spend can still be taken back. */
+    protected abstract releasable(spend: BudgetSpend): boolean;
+    /** The spend was taken back. */
+    protected abstract released(spend: BudgetSpend): void;
+    abstract flush(): Promise<void>;
+    abstract close(): Promise<void>;
+    private breachOf;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.js

@@ -0,0 +1,98 @@
+import { budgetSpendProblem, GATE_RULE_WORDS, MICROS_PER_USD, utcDay, } from "@bondedhq/shared";
+import { BondedError, PaymentBlockedError } from "./errors.js";
+/** Spends are refused this long before the budget's end, so they reach the gate inside it. */
+const END_MARGIN_MS = 5_000;
+/** The bookkeeping both kinds of budget share: the terms check and the running totals. */
+export class BudgetBase {
+    id;
+    terms;
+    mode;
+    now;
+    onBreach;
+    #spentMicros = 0;
+    #payments = 0;
+    #closed = false;
+    counted = new Map();
+    constructor(id, terms, mode, now, onBreach) {
+        this.id = id;
+        this.terms = terms;
+        this.mode = mode;
+        this.now = now;
+        this.onBreach = onBreach;
+    }
+    get spentMicros() {
+        return this.#spentMicros;
+    }
+    get payments() {
+        return this.#payments;
+    }
+    get closed() {
+        return this.#closed || this.now() >= this.terms.expiresAtMs - END_MARGIN_MS;
+    }
+    markClosed() {
+        this.#closed = true;
+    }
+    problem(amountMicros) {
+        if (this.#closed)
+            return "the budget is closed";
+        const atMs = this.now();
+        if (atMs >= this.terms.expiresAtMs - END_MARGIN_MS)
+            return "it was paid after the budget expired";
+        return budgetSpendProblem(this.terms, { spentMicros: this.#spentMicros, payments: this.#payments }, { amountMicros, atMs });
+    }
+    async spend(amountMicros, options = {}) {
+        if (!Number.isSafeInteger(amountMicros) || amountMicros <= 0)
+            throw new BondedError("INVALID_PAYMENT", "amountMicros must be a positive whole number");
+        const problem = this.problem(amountMicros);
+        const spend = {
+            id: options.id ?? crypto.randomUUID(),
+            amountMicros,
+            reference: options.reference ?? "",
+            atMs: this.now(),
+        };
+        if (problem) {
+            const breach = this.breachOf(spend, problem);
+            await this.onBreach?.(breach);
+            if (breach.blocked)
+                throw new PaymentBlockedError(breach);
+        }
+        this.#spentMicros += amountMicros;
+        this.#payments += 1;
+        this.counted.set(spend.id, spend);
+        await this.recorded(spend);
+        return spend;
+    }
+    release(spendId) {
+        const spend = this.counted.get(spendId);
+        if (!spend || !this.releasable(spend))
+            return false;
+        this.counted.delete(spendId);
+        this.#spentMicros -= spend.amountMicros;
+        this.#payments -= 1;
+        this.released(spend);
+        return true;
+    }
+    settle(spendId, reference) {
+        const spend = this.counted.get(spendId);
+        if (spend)
+            spend.reference = reference.slice(0, 200);
+    }
+    breachOf(spend, problem) {
+        const rules = ["over_budget"];
+        return {
+            kind: "budget",
+            rules,
+            reasons: [`${GATE_RULE_WORDS.over_budget}: ${problem}`],
+            blocked: this.mode === "enforce",
+            account: this.terms.account,
+            reference: spend.reference,
+            vendorId: null,
+            amountUsd: spend.amountMicros / MICROS_PER_USD,
+            lossUsd: 0,
+            overpaidUsd: 0,
+            day: utcDay(new Date(spend.atMs)),
+            decisionId: this.id,
+        };
+    }
+}
+//# sourceMappingURL=budget.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