@bondedhq/sdk 0.1.3 → 0.1.4

package/dist/payments.js

@@ -0,0 +1,275 @@
+import { checkInvoicePayment, checkRefundPayment, isVerifiedChange, normalAccount, PAYMENT_RULE_WORDS, utcDay, } from "@bondedhq/shared";
+import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError, } from "./errors.js";
+const read = async (source) => typeof source === "function" ? await source() : (source ?? []);
+const copy = (state) => ({
+    payments: state.payments.map((p) => ({ ...p })),
+    frozen: state.frozen,
+    unverifiedChanges: state.unverifiedChanges.map((c) => ({ ...c })),
+});
+/**
+ * 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 class PaymentGuard {
+    mandate;
+    #options;
+    #state;
+    #queue = Promise.resolve();
+    #now;
+    constructor(options) {
+        this.mandate = Object.freeze({ ...options.mandate });
+        this.#options = options;
+        this.#state = copy(options.state ?? { payments: [], frozen: false, unverifiedChanges: [] });
+        this.#now = options.now ?? (() => new Date());
+    }
+    get frozen() {
+        return this.#state.frozen;
+    }
+    /** A copy of what the guard remembers, to persist or inspect. */
+    state() {
+        return copy(this.#state);
+    }
+    /** Lets payments through again after a freeze. For a person who reviewed the breach. */
+    unfreeze() {
+        return this.#exclusive(async () => {
+            if (!this.#state.frozen)
+                return;
+            this.#state.frozen = false;
+            await this.#save();
+        });
+    }
+    /** The rule verdict for a payment, without making or recording it. */
+    async check(attempt, kind = "invoice") {
+        const check = await this.#check(attempt, kind, utcDay(this.#now()));
+        const { rules, amountUsd, reference, vendorId, lossUsd, overpaidUsd } = check;
+        return {
+            rules,
+            reasons: words(rules),
+            amountUsd,
+            reference,
+            vendorId,
+            lossUsd,
+            overpaidUsd,
+            frozen: this.frozen,
+        };
+    }
+    /**
+     * 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(attempt, pay, kind = "invoice") {
+        return this.#exclusive(async () => {
+            if (this.#state.frozen)
+                throw new PaymentFrozenError();
+            const day = utcDay(this.#now());
+            const check = await this.#check(attempt, kind, day);
+            if (check.rules.length > 0) {
+                await this.#breach({
+                    kind,
+                    rules: check.rules,
+                    reasons: words(check.rules),
+                    blocked: this.mandate.mode === "enforce",
+                    account: attempt.account,
+                    reference: check.reference,
+                    vendorId: check.vendorId,
+                    amountUsd: check.amountUsd,
+                    lossUsd: check.lossUsd,
+                    overpaidUsd: check.overpaidUsd,
+                    day,
+                });
+            }
+            const result = await pay();
+            this.#state.payments.push({
+                account: attempt.account,
+                // A refund settles no supplier invoice, as in the Arena's ledger.
+                vendorId: kind === "refund" ? null : check.vendorId,
+                amountUsd: check.amountUsd,
+                invoiceReference: check.reference,
+                day,
+                ...(kind === "refund" ? { kind } : {}),
+            });
+            await this.#save();
+            return result;
+        });
+    }
+    /**
+     * 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(request, update) {
+        return this.#exclusive(async () => {
+            if (this.#state.frozen)
+                throw new PaymentFrozenError();
+            if (!normalAccount(request.account))
+                throw new BondedError("INVALID_PAYMENT", "account is required");
+            // Already a known payee for this vendor (its account on file, or a ticket's): no change to
+            // verify. Marking it unverified would make the vendor's own account unpayable.
+            if (!isVerifiedChange(await this.#payees(), request)) {
+                const rules = ["unverified_vendor_change"];
+                await this.#breach({
+                    kind: "vendor_change",
+                    rules,
+                    reasons: words(rules),
+                    blocked: this.mandate.mode === "enforce",
+                    account: request.account,
+                    reference: "",
+                    vendorId: request.vendorId,
+                    amountUsd: 0,
+                    lossUsd: 0,
+                    overpaidUsd: 0,
+                    day: utcDay(this.#now()),
+                });
+                this.#state.unverifiedChanges.push({
+                    vendorId: request.vendorId,
+                    account: request.account,
+                });
+                await this.#save();
+            }
+            return update();
+        });
+    }
+    /** Runs the shared rule check against the builder's data and the guard's payments. */
+    async #check(attempt, kind, day) {
+        const payees = await this.#payees();
+        const limits = this.mandate;
+        const payments = this.#state.payments;
+        const check = kind === "refund"
+            ? checkRefundPayment({ limits, payees, refunds: await read(this.#options.refunds), payments, day }, attempt)
+            : checkInvoicePayment({ limits, payees, invoices: await read(this.#options.invoices), payments, day }, attempt);
+        if (!check.ok)
+            throw new BondedError("INVALID_PAYMENT", check.error);
+        return check;
+    }
+    /**
+     * Known payees: each vendor's account on file, unless it got there through an unverified
+     * change, and every account a verified ticket covers.
+     */
+    async #payees() {
+        const unverified = this.#state.unverifiedChanges;
+        const onFile = (await read(this.#options.vendors))
+            .map((v) => ({ vendorId: v.id, account: v.account }))
+            .filter((p) => !unverified.some((u) => u.vendorId === p.vendorId && normalAccount(u.account) === normalAccount(p.account)));
+        const ticketed = (await read(this.#options.changes)).map((c) => ({
+            vendorId: c.vendorId,
+            account: c.account,
+        }));
+        return [...onFile, ...ticketed];
+    }
+    /** Reports a breach, freezes if the mandate says so, and throws when Enforce mode blocks it. */
+    async #breach(breach) {
+        if (this.mandate.freezeOnBreach) {
+            this.#state.frozen = true;
+            await this.#save();
+        }
+        await this.#options.onBreach?.({
+            ...breach,
+            rules: [...breach.rules],
+            reasons: [...breach.reasons],
+        });
+        if (breach.blocked)
+            throw new PaymentBlockedError(breach);
+    }
+    async #save() {
+        await this.#options.onStateChange?.(this.state());
+    }
+    /** One check-and-pay at a time, so the duplicate and daily checks see every payment. */
+    #exclusive(run) {
+        const next = this.#queue.then(run, run);
+        this.#queue = next.catch(() => undefined);
+        return next;
+    }
+}
+const words = (rules) => rules.map((r) => PAYMENT_RULE_WORDS[r]);
+/** A payment guard: see `PaymentGuard`. */
+export function paymentGuard(options) {
+    return new PaymentGuard(options);
+}
+/**
+ * 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 function guardPayments(pay, options) {
+    const toPayment = options.toPayment ?? defaultPayment;
+    return async (input, ...rest) => options.guard.pay(toPayment(input), () => pay(input, ...rest), options.kind ?? "invoice");
+}
+/**
+ * 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 function guardVendorChanges(update, options) {
+    const toChange = options.toChange ?? defaultChange;
+    return async (input, ...rest) => options.guard.changeVendorAccount(toChange(input), () => update(input, ...rest));
+}
+/**
+ * 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 function isPaymentRefusal(error) {
+    return (error instanceof PaymentBlockedError ||
+        error instanceof PaymentFrozenError ||
+        error instanceof PaymentGateError ||
+        (error instanceof BondedError && error.code === "INVALID_PAYMENT"));
+}
+const field = (input, name) => {
+    const value = input[name];
+    if (typeof value !== "string")
+        throw new BondedError("INVALID_PAYMENT", `${name} must be a string`);
+    return value;
+};
+const asObject = (input) => {
+    if (!input || typeof input !== "object")
+        throw new BondedError("INVALID_PAYMENT", "the payment's arguments must be an object");
+    return input;
+};
+function defaultPayment(input) {
+    const args = asObject(input);
+    const amount = args.amountUsd;
+    const amountUsd = typeof amount === "number"
+        ? amount
+        : typeof amount === "string" && /^\d+(\.\d+)?$/.test(amount.trim())
+            ? Number(amount)
+            : NaN;
+    if (Number.isNaN(amountUsd))
+        throw new BondedError("INVALID_PAYMENT", "amountUsd must be a number of US dollars");
+    return {
+        account: field(args, "account"),
+        amountUsd,
+        invoiceReference: field(args, "invoiceReference" in args ? "invoiceReference" : "reference"),
+        ...(typeof args.requestId === "string" ? { requestId: args.requestId } : {}),
+    };
+}
+function defaultChange(input) {
+    const args = asObject(input);
+    return {
+        vendorId: field(args, "vendorId"),
+        account: field(args, "account"),
+        ...(typeof args.ticket === "string" ? { ticket: args.ticket } : {}),
+    };
+}
+//# sourceMappingURL=payments.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bondedhq/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Trade through a Bonded Mandate Vault and get rated by the Bonded Arena from any TypeScript agent: a typed vault client with dry runs, Sentinel checks and a mandate builder; the Arena episode's tools for LangChain, the Vercel AI SDK, ElizaOS and Coinbase AgentKit; and an Agent URL handler.",
   "license": "MIT",
   "keywords": [
@@ -83,7 +83,7 @@
     "@modelcontextprotocol/sdk": "1.30.1",
     "viem": "^2.56.9",
     "zod": "^4.6.5",
-    "@bondedhq/shared": "^0.1.3"
+    "@bondedhq/shared": "^0.1.4"
   },
   "devDependencies": {
     "@coinbase/agentkit": "0.10.4",
@@ -93,8 +93,8 @@
     "@solana/web3.js": "^1.98.4",
     "ai": "7.0.114",
     "solana-agent-kit": "2.0.10",
-    "@bondedhq/solana": "0.1.2",
-    "@bonded/sandbox": "0.1.0"
+    "@bonded/sandbox": "0.1.0",
+    "@bondedhq/solana": "0.1.2"
   },
   "peerDependencies": {
     "@coinbase/agentkit": "^0.10.4",