@bondedhq/sdk 0.1.3 → 0.1.5

package/dist/gate.d.ts

@@ -0,0 +1,158 @@
+import { type GateInput, type GateLogProof, type GateRule, type PaymentAttempt, type SignedGateReceipt } from "@bondedhq/shared";
+import { type Address, type Hex } from "viem";
+import type { PaymentBreach } from "./payments.js";
+import { type BudgetRequest, type PaymentBudget } from "./budget.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" | "payment" | "budget" | "budget_close";
+    decision: "pass" | "breach" | "frozen";
+    result: "allowed" | "blocked" | "refused";
+    allowed: boolean;
+    message: string;
+    mode: "monitor" | "enforce";
+    /** Every rule broken, most serious first. */
+    rules: GateRule[];
+    /** Each rule in plain words, in the same order. */
+    reasons: {
+        rule: GateRule;
+        words: 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>;
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). The gate
+     * checks it against the general rules (the account needs invoice matching off), reserves the
+     * whole budget against the day's limit and signs a receipt whose input commits to the terms;
+     * this checks the receipt, then recomputes the input's hash and reruns its rules. Each `spend`
+     * is checked here with no network call; payments go to the gate in the background (every
+     * `flushMs`, 5 seconds by default, once `holdMs` has passed so a turned-down payment can be taken
+     * back) and on `close()`, whose receipt commits to every one. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without opening one.
+     */
+    budget(request: BudgetRequest, options?: {
+        flushMs?: number;
+        holdMs?: number;
+        onError?: (error: unknown) => void;
+    }): Promise<PaymentBudget>;
+    /** 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,416 @@
+import { budgetCloseCents, evaluateGateInput, gateInputHash, normalAccount, verifyGateReceipt, } from "@bondedhq/shared";
+import { isAddress } from "viem";
+import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, } from "./errors.js";
+import { BudgetBase } from "./budget.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,
+                ...(check.invoiceReference?.trim() ? { 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();
+    }
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). The gate
+     * checks it against the general rules (the account needs invoice matching off), reserves the
+     * whole budget against the day's limit and signs a receipt whose input commits to the terms;
+     * this checks the receipt, then recomputes the input's hash and reruns its rules. Each `spend`
+     * is checked here with no network call; payments go to the gate in the background (every
+     * `flushMs`, 5 seconds by default, once `holdMs` has passed so a turned-down payment can be taken
+     * back) and on `close()`, whose receipt commits to every one. Throws `PaymentBlockedError`
+     * (Enforce), `PaymentFrozenError` or `PaymentGateError` without opening one.
+     */
+    async budget(request, options = {}) {
+        const body = {
+            account: request.account,
+            amountUsd: request.amountUsd,
+            ...(request.maxPaymentUsd === undefined ? {} : { maxPaymentUsd: request.maxPaymentUsd }),
+            ...(request.ttlSeconds === undefined ? {} : { ttlSeconds: request.ttlSeconds }),
+            requestId: request.requestId ?? crypto.randomUUID(),
+        };
+        let answer;
+        let last;
+        for (let attempt = 0; attempt < TRIES && !answer; attempt++) {
+            try {
+                answer = await this.#request("/payments/budgets", {
+                    method: "POST",
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (error) {
+                last = error;
+                const unanswered = error instanceof PaymentGateError && (!error.status || error.status >= 500);
+                if (!unanswered)
+                    throw error;
+            }
+        }
+        if (!answer)
+            throw last;
+        const terms = await this.#verifyBudget(answer, body);
+        await this.#settle(answer);
+        return new HostedBudget(answer.id, terms, answer.mode, Date.now, this.#options.onBreach, {
+            flushMs: options.flushMs ?? 5_000,
+            holdMs: options.holdMs ?? 10_000,
+            onError: options.onError ?? (() => undefined),
+            send: (spends) => this.#request(`/payments/budgets/${encodeURIComponent(answer.id)}/spends`, {
+                method: "POST",
+                body: JSON.stringify({
+                    spends: spends.map((s) => ({
+                        id: s.id,
+                        amountMicros: s.amountMicros,
+                        reference: s.reference,
+                        at: new Date(s.atMs).toISOString(),
+                    })),
+                }),
+            }),
+            close: async () => {
+                const closed = await this.#request(`/payments/budgets/${encodeURIComponent(answer.id)}/close`, { method: "POST" });
+                await this.#verifyClose(closed, answer.id);
+                return closed;
+            },
+        });
+    }
+    /** 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"
+                : // An account with invoice matching off answers an invoice check as kind "payment".
+                    (r.kind === (asked.kind ?? "invoice") ||
+                        (r.kind === "payment" && (asked.kind ?? "invoice") === "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");
+    }
+    /** The budget answer's receipt and input check out; returns the terms it grants. */
+    async #verifyBudget(answer, asked) {
+        const wrong = (what) => new PaymentGateError(`the gate's budget can't be trusted: ${what}`, undefined, {
+            receipt: true,
+        });
+        const signed = answer.receipt;
+        if (!signed?.receipt)
+            throw wrong("it has no receipt");
+        if (this.#options.verifyReceipts !== false) {
+            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 input = answer.input;
+        if (r.kind !== "budget" ||
+            r.decisionId !== answer.id ||
+            r.decision !== answer.decision ||
+            r.result !== answer.result ||
+            answer.allowed !== (r.result === "allowed") ||
+            r.payee !== normalAccount(asked.account) ||
+            r.amountCents !== Math.round(asked.amountUsd * 100))
+            throw wrong("its receipt is for a different budget");
+        if (!input || input.kind !== "budget" || gateInputHash(input) !== r.inputHash)
+            throw wrong("its input doesn't match the receipt");
+        if (r.decision !== "frozen") {
+            const verdict = evaluateGateInput(input);
+            if (!verdict.ok || verdict.rules.join() !== r.rules.join())
+                throw wrong("its rules don't follow from its input");
+        }
+        const t = input.terms;
+        const ttlMs = (asked.ttlSeconds ?? 3600) * 1000;
+        const maxAsked = asked.maxPaymentUsd === undefined ? Infinity : Math.round(asked.maxPaymentUsd * 1e6);
+        if (t.account !== r.payee ||
+            t.budgetMicros !== r.amountCents * 10_000 ||
+            t.expiresAtMs - t.startsAtMs !== ttlMs ||
+            t.maxPaymentMicros > maxAsked)
+            throw wrong("its terms aren't the ones asked for");
+        return t;
+    }
+    /** A budget close's receipt checks out and commits to its input. */
+    async #verifyClose(answer, budgetId) {
+        if (this.#options.verifyReceipts === false)
+            return;
+        const wrong = (what) => new PaymentGateError(`the gate's budget close 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;
+        if (r.kind !== "budget_close" || r.reference !== budgetId || r.decisionId !== answer.id)
+            throw wrong("its receipt is for a different budget");
+        const input = answer.input;
+        // A close given back again has no input to check beyond its signed receipt.
+        if (!input)
+            return;
+        if (input.kind !== "budget_close" ||
+            input.budgetId !== budgetId ||
+            gateInputHash(input) !== r.inputHash)
+            throw wrong("its input doesn't match the receipt");
+        const verdict = evaluateGateInput(input);
+        if (!verdict.ok ||
+            verdict.rules.join() !== r.rules.join() ||
+            r.amountCents !== budgetCloseCents(input))
+            throw wrong("its rules or amount don't follow from its input");
+    }
+    #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);
+}
+/**
+ * A budget the hosted gate opened. Spends wait `holdMs` (so one the payee turned down can be taken
+ * back), then go to the gate every `flushMs`; `close()` sends the rest and closes it.
+ */
+class HostedBudget extends BudgetBase {
+    link;
+    #pending = [];
+    /** Spends on their way to the gate: too late to take back. */
+    #inFlight = new Set();
+    #sending;
+    #timer;
+    #closing;
+    constructor(id, terms, mode, now, onBreach, link) {
+        super(id, terms, mode, now, onBreach);
+        this.link = link;
+    }
+    /** The close decision, once closed. */
+    closeDecision;
+    recorded(spend) {
+        this.#pending.push(spend);
+        if (!this.#timer) {
+            this.#timer = setInterval(() => {
+                this.#send(false).catch(this.link.onError);
+            }, this.link.flushMs);
+            this.#timer.unref?.();
+        }
+        return Promise.resolve();
+    }
+    releasable(spend) {
+        return this.#pending.includes(spend) && !this.#inFlight.has(spend);
+    }
+    released(spend) {
+        this.#pending = this.#pending.filter((s) => s !== spend);
+    }
+    flush() {
+        return this.#send(true);
+    }
+    close() {
+        this.#closing ??= (async () => {
+            this.markClosed();
+            if (this.#timer)
+                clearInterval(this.#timer);
+            while (this.#pending.length > 0 || this.#sending)
+                await this.#send(true);
+            this.closeDecision = await this.link.close();
+        })().catch((error) => {
+            // Nothing is lost: what wasn't sent is still pending, so closing again tries again.
+            this.#closing = undefined;
+            throw error;
+        });
+        return this.#closing;
+    }
+    /** Sends what's due (everything when `all`), 500 at a time, one send at a time. */
+    async #send(all) {
+        while (this.#sending)
+            await this.#sending;
+        const cutoff = this.now() - this.link.holdMs;
+        const due = this.#pending.filter((s) => all || s.atMs <= cutoff).slice(0, 500);
+        if (due.length === 0)
+            return;
+        for (const s of due)
+            this.#inFlight.add(s);
+        this.#sending = (async () => {
+            const answer = await this.link.send(due);
+            this.#pending = this.#pending.filter((s) => !due.includes(s));
+            if (answer.frozen)
+                this.markClosed();
+        })().finally(() => {
+            for (const s of due)
+                this.#inFlight.delete(s);
+            this.#sending = undefined;
+        });
+        await this.#sending;
+        if (all && this.#pending.length > 0)
+            await this.#send(true);
+    }
+}
+function breachOf(answer) {
+    return {
+        kind: answer.kind === "bank_change"
+            ? "vendor_change"
+            : answer.kind === "refund"
+                ? "refund"
+                : answer.kind === "budget"
+                    ? "budget"
+                    : "invoice",
+        rules: answer.rules,
+        reasons: answer.reasons.map((r) => (typeof r === "string" ? r : r.words)),
+        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,12 @@
  * `@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), and `paymentGate` asks Bonded's
+ * hosted gate instead. The framework subpaths wrap a pay tool with either, `@bondedhq/sdk/openai-agents`
+ * does the same for the OpenAI Agents SDK, and `@bondedhq/sdk/x402` checks x402 payments before
+ * the client signs them.
  */
 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 +18,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, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, type GateRule, 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,12 @@
  * `@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), and `paymentGate` asks Bonded's
+ * hosted gate instead. The framework subpaths wrap a pay tool with either, `@bondedhq/sdk/openai-agents`
+ * does the same for the OpenAI Agents SDK, and `@bondedhq/sdk/x402` checks x402 payments before
+ * the client signs them.
  */
 export { BondedVault, } from "./vault.js";
 export { demoRouter, describeAction, } from "./actions.js";
@@ -12,7 +18,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, GATE_RULE_WORDS, GATE_RULES, 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