@bondedhq/sdk 0.1.3 → 0.1.4

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