@bondedhq/sdk 0.1.2 → 0.1.4

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

package/dist/index.d.ts

@@ -5,6 +5,10 @@
  * `@bondedhq/sdk/agentkit`, `@bondedhq/sdk/solana-agent-kit`, `@bondedhq/sdk/eliza`,
  * `@bondedhq/sdk/langchain`, `@bondedhq/sdk/ai-sdk`. The episode's tools over MCP are in
  * `@bondedhq/sdk/mcp`, and the Agent URL handler in `@bondedhq/sdk/agent-url`.
+ *
+ * Off chain, `paymentGuard` and `guardPayments` check an agent's payments against the payment
+ * mandate inside your own process (no network, no receipts); the framework subpaths wrap a pay
+ * tool with it.
  */
 export { BondedVault, type ActionResult, type BondedVaultConfig, type VaultStatus, } from "./vault.js";
 export { demoRouter, describeAction, type ApproveParams, type CallParams, type SwapParams, type SwapRouter, type TransferParams, type VaultAction, type VaultCall, } from "./actions.js";
@@ -12,8 +16,11 @@ export { breachReason, type DryRunResult, type VaultBreach } from "./breaches.js
 export { guarded, GuardedVault, type GuardCheck, type GuardContext, type GuardedResult, type GuardOptions, type SentinelGuardOptions, type TokenInfo, } from "./guarded.js";
 export { checkWithSentinel, type MessageSigner, type SentinelCheckRequest, type SentinelInput, } from "./sentinel.js";
 export { buildMandate, describeMandate, type BuiltMandate, type EvmMandate, type EvmMandateParams, type EvmMandateRules, } from "./mandate.js";
-export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, type SentinelVerdict, } from "./errors.js";
+export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, type SentinelVerdict, } from "./errors.js";
 export type { BreachType } from "@bondedhq/shared";
+export { BONDED_API_URL, PaymentGate, paymentGate, type GateAnswer, type GateCheck, type GateDecision, type GatePayment, type GateReceiptProof, type GateVendorChange, type PaymentGateOptions, } from "./gate.js";
+export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, type GuardPaymentsOptions, type GuardVendorChangesOptions, type PaymentBreach, type PaymentGuardOptions, type PaymentGuardState, type PaymentMandate, type PaymentSource, type PaymentVendor, type PaymentVerdict, } from "./payments.js";
+export { describePaymentMandate, PAYMENT_RULE_WORDS, PAYMENT_RULES, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentRule, type VerifiedChange, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, type BondedVaultTool, type BondedVaultToolName, type BondedVaultToolsOptions, } from "./vault-tools.js";
 export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, type BondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, type AllowanceCheck, type AllowanceFinding, type TokenRef, installMandateModule, type InstallMandateModuleInput, type ModuleAccountType, type ModuleInstallPlan, } from "./module.js";

package/dist/index.js

@@ -5,6 +5,10 @@
  * `@bondedhq/sdk/agentkit`, `@bondedhq/sdk/solana-agent-kit`, `@bondedhq/sdk/eliza`,
  * `@bondedhq/sdk/langchain`, `@bondedhq/sdk/ai-sdk`. The episode's tools over MCP are in
  * `@bondedhq/sdk/mcp`, and the Agent URL handler in `@bondedhq/sdk/agent-url`.
+ *
+ * Off chain, `paymentGuard` and `guardPayments` check an agent's payments against the payment
+ * mandate inside your own process (no network, no receipts); the framework subpaths wrap a pay
+ * tool with it.
  */
 export { BondedVault, } from "./vault.js";
 export { demoRouter, describeAction, } from "./actions.js";
@@ -12,7 +16,10 @@ export { breachReason } from "./breaches.js";
 export { guarded, GuardedVault, } from "./guarded.js";
 export { checkWithSentinel, } from "./sentinel.js";
 export { buildMandate, describeMandate, } from "./mandate.js";
-export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, } from "./errors.js";
+export { BlockedByMandateError, BondedError, CallRevertedError, NotAgentError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, PredictedBreachError, SentinelError, SentinelRefusedError, VaultFrozenError, } from "./errors.js";
+export { BONDED_API_URL, PaymentGate, paymentGate, } from "./gate.js";
+export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, } from "./payments.js";
+export { describePaymentMandate, PAYMENT_RULE_WORDS, PAYMENT_RULES, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, } from "./vault-tools.js";
 export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";

package/dist/langchain.d.ts

@@ -1,7 +1,9 @@
-import { DynamicStructuredTool } from "@langchain/core/tools";
+import { DynamicStructuredTool, type StructuredToolInterface } from "@langchain/core/tools";
 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 LangChain `StructuredTool`s, for LangChain and LangGraph agents
  * (`createReactAgent`, `ToolNode`, `model.bindTools`). Each takes the tool's own JSON Schema and
@@ -36,4 +38,20 @@ export declare function bondedLangChainTools(from?: EpisodeTools | EpisodeToolsS
  * ```
  */
 export declare function bondedVaultLangChainTools(options: BondedVaultToolsOptions): DynamicStructuredTool[];
+/**
+ * Your own LangChain pay tool, with every call checked against the payment mandate first (see
+ * `PaymentGuard`). Same name, description and schema. When the guard refuses (Enforce mode
+ * blocked it, the guard is frozen, or it can't read the payment) your tool 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, guardLangChainPayTool(payInvoice, { guard })];
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`.
+ */
+export declare function guardLangChainPayTool(payTool: StructuredToolInterface, options: GuardPaymentsOptions<Record<string, unknown>>): DynamicStructuredTool;
 //# sourceMappingURL=langchain.d.ts.map

package/dist/langchain.js

@@ -1,5 +1,6 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { resolveTools, resultText } from "./mcp.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
 import { bondedVaultTools } from "./vault-tools.js";
 /**
  * The episode's tools as LangChain `StructuredTool`s, for LangChain and LangGraph agents
@@ -50,4 +51,37 @@ export function bondedVaultLangChainTools(options) {
         func: async (args) => resultText(await t.call(args ?? {})),
     }));
 }
+/**
+ * Your own LangChain pay tool, with every call checked against the payment mandate first (see
+ * `PaymentGuard`). Same name, description and schema. When the guard refuses (Enforce mode
+ * blocked it, the guard is frozen, or it can't read the payment) your tool 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, guardLangChainPayTool(payInvoice, { guard })];
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`.
+ */
+export function guardLangChainPayTool(payTool, options) {
+    const guarded = guardPayments((args, config) => payTool.invoke(args, config), options);
+    return new DynamicStructuredTool({
+        name: payTool.name,
+        description: payTool.description,
+        schema: payTool.schema,
+        func: async (args, _runManager, config) => {
+            try {
+                return await guarded(args ?? {}, config);
+            }
+            catch (error) {
+                if (isPaymentRefusal(error))
+                    return `Error: ${error.message}`;
+                throw error;
+            }
+        },
+    });
+}
 //# sourceMappingURL=langchain.js.map

package/dist/mcp.d.ts

@@ -1,7 +1,10 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { DoneRequest } from "@bondedhq/shared";
+import { type GuardPaymentsOptions } from "./payments.js";
 export { isBondedEpisode } from "./episode.js";
 export { finishEpisode } from "./done.js";
+export type { GuardPaymentsOptions } from "./payments.js";
 /**
  * Where an episode's tools are. A `BondedEpisode` (from `fromBondedEnv`, or the one an Agent URL
  * handler hands you) has these, and so does the runner protocol's `EpisodeMessage`.
@@ -128,4 +131,21 @@ export declare function mcpConfigJson(episode?: {
         mcp: string;
     };
 }, options?: McpConfigOptions): string;
+/**
+ * Your MCP server's pay tool handler, with every call checked against the payment mandate first
+ * (see `PaymentGuard`). Register the result in its place:
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoice, { guard }));
+ * ```
+ *
+ * When the guard refuses (Enforce mode blocked it, the guard is frozen, or it can't read the
+ * payment) your handler is not called and the client gets an error result (`isError: true`)
+ * naming the rules broken, so the model can react. In Monitor mode a breaking payment goes
+ * through and the guard's `onBreach` reports it. The payment is read from the tool's arguments:
+ * `{ account, amountUsd, invoiceReference }` unless you pass `toPayment`. A local check: no
+ * receipts.
+ */
+export declare function guardMcpPayHandler<I, Rest extends unknown[]>(handler: (args: I, ...rest: Rest) => CallToolResult | Promise<CallToolResult>, options: GuardPaymentsOptions<I>): (args: I, ...rest: Rest) => Promise<CallToolResult>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { BondedError } from "./errors.js";
 import { finishEpisode } from "./done.js";
 import { fromBondedEnv } from "./episode.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
 export { isBondedEpisode } from "./episode.js";
 export { finishEpisode } from "./done.js";
 /**
@@ -108,4 +109,33 @@ export function mcpConfig(episode = fromBondedEnv(), options = {}) {
 export function mcpConfigJson(episode = fromBondedEnv(), options = {}) {
     return `${JSON.stringify(mcpConfig(episode, options), null, 2)}\n`;
 }
+/**
+ * Your MCP server's pay tool handler, with every call checked against the payment mandate first
+ * (see `PaymentGuard`). Register the result in its place:
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoice, { guard }));
+ * ```
+ *
+ * When the guard refuses (Enforce mode blocked it, the guard is frozen, or it can't read the
+ * payment) your handler is not called and the client gets an error result (`isError: true`)
+ * naming the rules broken, so the model can react. In Monitor mode a breaking payment goes
+ * through and the guard's `onBreach` reports it. The payment is read from the tool's arguments:
+ * `{ account, amountUsd, invoiceReference }` unless you pass `toPayment`. A local check: no
+ * receipts.
+ */
+export function guardMcpPayHandler(handler, options) {
+    const guarded = guardPayments(handler, options);
+    return async (args, ...rest) => {
+        try {
+            return await guarded(args, ...rest);
+        }
+        catch (error) {
+            if (isPaymentRefusal(error))
+                return { content: [{ type: "text", text: error.message }], isError: true };
+            throw error;
+        }
+    };
+}
 //# sourceMappingURL=mcp.js.map

package/dist/payments.d.ts

@@ -0,0 +1,194 @@
+import { type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentLimits, type PaymentRule, type SignedGateReceipt, type VerifiedChange } from "@bondedhq/shared";
+import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError } from "./errors.js";
+/** The off-chain payment mandate an agent's payments are checked against. */
+export interface PaymentMandate extends PaymentLimits {
+    /** Monitor lets a breaking payment through and reports it; Enforce blocks it. */
+    mode: "monitor" | "enforce";
+    /** After the first breach, refuse every payment until a person unfreezes the guard. */
+    freezeOnBreach: boolean;
+}
+/** A supplier as your vendor master holds it. Its account is one the agent may pay. */
+export interface PaymentVendor {
+    id: string;
+    /** Bank account (an IBAN or account number). Compared without spaces, case-insensitively. */
+    account: string;
+    name?: string;
+}
+/** A list the guard reads on every check: fixed, or read from your own system each time. */
+export type PaymentSource<T> = readonly T[] | (() => readonly T[] | Promise<readonly T[]>);
+/** What the guard remembers between payments. Persist it to keep it across restarts. */
+export interface PaymentGuardState {
+    /** Payments made through the guard (and any made before it, if you restore them), oldest first. */
+    payments: PaidPayment[];
+    /** Frozen after a breach: every payment is refused until `unfreeze()`. */
+    frozen: boolean;
+    /**
+     * Bank changes made without a verified ticket (let through in Monitor mode). The vendor master
+     * may now show these accounts, but they never count as the vendor's: paying one is
+     * `unknown_payee`.
+     */
+    unverifiedChanges: VerifiedChange[];
+}
+/** One payment (or bank change) that broke the mandate, as the guard reports it. */
+export interface PaymentBreach {
+    kind: "invoice" | "refund" | "vendor_change";
+    /** Every rule broken, most serious first. */
+    rules: PaymentRule[];
+    /** Each rule in plain words (`PAYMENT_RULE_WORDS`), in the same order. */
+    reasons: string[];
+    /** Enforce mode stopped it: the pay function was not called. */
+    blocked: boolean;
+    account: string;
+    /** The invoice or refund reference; empty for a bank change. */
+    reference: string;
+    /** The vendor whose verified account this is (or, for a bank change, the vendor changed). */
+    vendorId: string | null;
+    amountUsd: number;
+    /** If it went out: paid to an account outside the vendor master, gone for good. */
+    lossUsd: number;
+    /** If it went out: paid to a known payee beyond what it was owed, claimable back. */
+    overpaidUsd: number;
+    /** UTC day it counts against, YYYY-MM-DD. */
+    day: string;
+    /** From the hosted gate (`PaymentGate`): the decision's id in its log. */
+    decisionId?: string;
+    /** From the hosted gate: Bonded's signed receipt for the decision. */
+    receipt?: SignedGateReceipt;
+}
+/** The rule verdict for a payment, without making it. */
+export interface PaymentVerdict {
+    /** Every rule the payment breaks, most serious first. Empty when it is allowed. */
+    rules: PaymentRule[];
+    reasons: string[];
+    amountUsd: number;
+    reference: string;
+    vendorId: string | null;
+    lossUsd: number;
+    overpaidUsd: number;
+    /** The guard is frozen: the payment would be refused whatever the rules say. */
+    frozen: boolean;
+}
+export interface PaymentGuardOptions {
+    mandate: PaymentMandate;
+    /** The vendor master: each vendor's account on file. */
+    vendors: PaymentSource<PaymentVendor>;
+    /** Invoices the business approved for payment. */
+    invoices?: PaymentSource<PayableInvoice>;
+    /** Customer refunds finance approved. */
+    refunds?: PaymentSource<PayableRefund>;
+    /**
+     * Bank changes finance verified out of band (a call to the number on file). A ticket's account
+     * is a known payee for its vendor, and the only way a vendor's account may change.
+     */
+    changes?: PaymentSource<VerifiedChange>;
+    /** State to start from, as `onStateChange` last saved it (or `state()` returned). */
+    state?: PaymentGuardState;
+    /** Called with the new state after every change, inside the guard's lock. Save it here. */
+    onStateChange?: (state: PaymentGuardState) => void | Promise<void>;
+    /**
+     * Called with every breach before the guard 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>;
+    now?: () => Date;
+}
+/**
+ * The payment mandate, checked inside your own process: the same rules (`@bondedhq/shared`'s
+ * payment mandate) the Arena rates agents against, with no network and no model. You give it the
+ * mandate and your vendor master, approved invoices and refunds, and verified bank changes; it
+ * keeps the payments made and the frozen flag, and hands them to `onStateChange` to persist.
+ *
+ * Wrap your pay function with `guardPayments` (or a framework helper) so every payment is checked
+ * first. In Enforce mode a payment that breaks a rule throws `PaymentBlockedError` and your pay
+ * function is never called; in Monitor mode it goes through and `onBreach` reports it. A frozen
+ * guard refuses everything (`PaymentFrozenError`).
+ *
+ * It is a local check: the agent's code can still call the pay function without it, and it makes
+ * no receipts. Payments are checked and made one at a time, so two at once can't both pass the
+ * duplicate or daily checks.
+ */
+export declare class PaymentGuard {
+    #private;
+    readonly mandate: Readonly<PaymentMandate>;
+    constructor(options: PaymentGuardOptions);
+    get frozen(): boolean;
+    /** A copy of what the guard remembers, to persist or inspect. */
+    state(): PaymentGuardState;
+    /** Lets payments through again after a freeze. For a person who reviewed the breach. */
+    unfreeze(): Promise<void>;
+    /** The rule verdict for a payment, without making or recording it. */
+    check(attempt: PaymentAttempt, kind?: "invoice" | "refund"): Promise<PaymentVerdict>;
+    /**
+     * Checks a payment, then calls `pay` if the mandate allows it (or Monitor mode lets it through)
+     * and records it once `pay` returns. Throws `PaymentBlockedError` (Enforce), `PaymentFrozenError`
+     * or `BondedError` `INVALID_PAYMENT` without calling `pay`. A `pay` that throws records nothing.
+     */
+    pay<R>(attempt: PaymentAttempt, pay: () => R | Promise<R>, kind?: "invoice" | "refund"): Promise<R>;
+    /**
+     * Checks a vendor bank change, then calls `update` if a verified ticket covers that vendor and
+     * account (or Monitor mode lets it through). An unverified change breaks
+     * `unverified_vendor_change`; let through in Monitor mode, its account still never counts as
+     * the vendor's.
+     */
+    changeVendorAccount<R>(request: {
+        vendorId: string;
+        account: string;
+    }, update: () => R | Promise<R>): Promise<R>;
+}
+/** A payment guard: see `PaymentGuard`. */
+export declare function paymentGuard(options: PaymentGuardOptions): PaymentGuard;
+export interface GuardPaymentsOptions<I> {
+    /**
+     * A `PaymentGuard`, or the hosted `PaymentGate`. Share one between your invoice and refund
+     * functions, so limits and freezes are shared.
+     */
+    guard: Pick<PaymentGuard, "pay">;
+    /** `invoice` (the default) pays approved invoices; `refund` pays approved customer refunds. */
+    kind?: "invoice" | "refund";
+    /**
+     * Reads the payment from your function's first argument. Default: `{ account, amountUsd,
+     * invoiceReference }` (or `reference`), the Arena's `pay_invoice` and `issue_refund` arguments.
+     */
+    toPayment?: (input: I) => PaymentAttempt;
+}
+/**
+ * Wraps your own pay function so every call is checked against the payment mandate first. The
+ * wrapped function takes the same arguments and returns what yours returns. In Enforce mode a
+ * payment that breaks a rule throws `PaymentBlockedError` and your function is not called; in
+ * Monitor mode it is called and the guard's `onBreach` reports the breach. A frozen guard throws
+ * `PaymentFrozenError`.
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const pay = guardPayments(bank.pay, { guard });
+ * await pay({ account: "DE89 3704 0044 0532 0130 00", amountUsd: 1840.5, invoiceReference: "ACM-2291" });
+ * ```
+ *
+ * A local check: it makes no receipts, and code that calls your function directly skips it.
+ */
+export declare function guardPayments<I, Rest extends unknown[], R>(pay: (input: I, ...rest: Rest) => R | Promise<R>, options: GuardPaymentsOptions<I>): (input: I, ...rest: Rest) => Promise<R>;
+export interface GuardVendorChangesOptions<I> {
+    /** A `PaymentGuard`, or the hosted `PaymentGate`. */
+    guard: Pick<PaymentGuard, "changeVendorAccount">;
+    /**
+     * Reads the change from your function's first argument. Default: `{ vendorId, account }`, and
+     * `ticket` when there is one (the hosted gate checks it).
+     */
+    toChange?: (input: I) => {
+        vendorId: string;
+        account: string;
+        ticket?: string;
+    };
+}
+/**
+ * Wraps your own "change a vendor's bank account" function: a change no verified ticket covers
+ * breaks `unverified_vendor_change`. Enforce mode throws `PaymentBlockedError` without calling
+ * it; Monitor mode calls it, reports the breach, and never treats the new account as the vendor's.
+ */
+export declare function guardVendorChanges<I, Rest extends unknown[], R>(update: (input: I, ...rest: Rest) => R | Promise<R>, options: GuardVendorChangesOptions<I>): (input: I, ...rest: Rest) => Promise<R>;
+/**
+ * The payment guard or gate refused (blocked, frozen, arguments it can't check, or the gate gave no
+ * answer to act on): no money moved.
+ */
+export declare function isPaymentRefusal(error: unknown): error is PaymentBlockedError | PaymentFrozenError | PaymentGateError | BondedError;
+//# sourceMappingURL=payments.d.ts.map