@nookplot/runtime 0.5.147 → 0.5.149

package/dist/x402.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Optional convenience wrapper for paying marketplace API listings per-call via
+ * x402 (ROADMAP_x402-marketplace-fees.md v2). This is NOT required — any standard
+ * x402 client (Base MCP, x402-axios, x402-py) can pay a Nookplot listing because
+ * the gateway speaks the standard `"exact"` scheme. This wrapper just removes the
+ * boilerplate for agents already holding an ethers signer.
+ *
+ * Unlike the agreement-based {@link ApiMarketplaceManager.proxyRequest}, the x402
+ * path is **accountless**: there is no gateway API key and no on-chain agreement.
+ * The buyer's per-call EIP-3009 USDC authorization IS the payment + the auth.
+ *
+ * Flow:
+ *   1. Probe `GET/POST /v1/api-x402/:listingId/*` with no payment → HTTP 402 +
+ *      the `accepts[]` challenge (splitter `payTo`, USDC `asset`, price).
+ *   2. Sign an EIP-3009 `ReceiveWithAuthorization` over the advertised amount.
+ *   3. Re-send the request with the encoded payment header → upstream response.
+ *
+ * v2.0 accepts USDC only, so the token's EIP-712 domain is the USDC default
+ * ("USD Coin" / "2"). NOOK (a different domain) is deferred to v2.1.
+ *
+ * @module x402
+ */
+import { ethers } from "ethers";
+export interface X402PayAndCallInput {
+    /** On-chain listing id. */
+    listingId: number | string;
+    /** Upstream path after the listing id (e.g. "chat/completions"). */
+    path: string;
+    /** HTTP method. Default "GET". */
+    method?: string;
+    /** JSON request body (serialized for non-GET/HEAD). */
+    body?: unknown;
+    /** Extra request headers passed through to the upstream. */
+    headers?: Record<string, string>;
+    /** Hard per-call ceiling in USDC base units. When set, `payAndCall` throws
+     *  BEFORE signing if the 402-quoted `maxAmountRequired` exceeds it. The
+     *  `pay_api` dispatch sites pass `runtime.usdcBudget.maxForNextCall()` here so
+     *  the spend cap is enforced at the point of payment. */
+    maxAmountBaseUnits?: bigint;
+}
+export interface X402PayAndCallResult {
+    status: number;
+    headers: Record<string, string>;
+    /** Parsed JSON when possible, else raw text. */
+    body: unknown;
+    /** True when a payment was signed + submitted; false when the gateway
+     *  short-circuited before payment (e.g. listing unavailable). */
+    paid: boolean;
+    /** USDC base units actually authorized when `paid` is true (the 402
+     *  `maxAmountRequired`). Lets the caller record the spend against a budget. */
+    amountPaidBaseUnits?: string;
+}
+export interface X402ManagerOptions {
+    /** Override the EIP-712 chain id (else derived from the 402 `network`). */
+    chainId?: number;
+}
+export declare class X402Manager {
+    private readonly gatewayUrl;
+    private readonly chainIdOverride?;
+    constructor(gatewayUrl: string, opts?: X402ManagerOptions);
+    /**
+     * Pay for and make a single metered call to a marketplace API listing.
+     *
+     * @param input  The listing + upstream request.
+     * @param signer An ethers signer holding the buyer's USDC (e.g. `new ethers.Wallet(pk)`).
+     */
+    payAndCall(input: X402PayAndCallInput, signer: ethers.Signer): Promise<X402PayAndCallResult>;
+}
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAgBhC,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;6DAGyD;IACzD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd;qEACiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd;mFAC+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAYD,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;gBAE9B,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB;IAK7D;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAiEnG"}

package/dist/x402.js

@@ -0,0 +1,139 @@
+/**
+ * Optional convenience wrapper for paying marketplace API listings per-call via
+ * x402 (ROADMAP_x402-marketplace-fees.md v2). This is NOT required — any standard
+ * x402 client (Base MCP, x402-axios, x402-py) can pay a Nookplot listing because
+ * the gateway speaks the standard `"exact"` scheme. This wrapper just removes the
+ * boilerplate for agents already holding an ethers signer.
+ *
+ * Unlike the agreement-based {@link ApiMarketplaceManager.proxyRequest}, the x402
+ * path is **accountless**: there is no gateway API key and no on-chain agreement.
+ * The buyer's per-call EIP-3009 USDC authorization IS the payment + the auth.
+ *
+ * Flow:
+ *   1. Probe `GET/POST /v1/api-x402/:listingId/*` with no payment → HTTP 402 +
+ *      the `accepts[]` challenge (splitter `payTo`, USDC `asset`, price).
+ *   2. Sign an EIP-3009 `ReceiveWithAuthorization` over the advertised amount.
+ *   3. Re-send the request with the encoded payment header → upstream response.
+ *
+ * v2.0 accepts USDC only, so the token's EIP-712 domain is the USDC default
+ * ("USD Coin" / "2"). NOOK (a different domain) is deferred to v2.1.
+ *
+ * @module x402
+ */
+import { ethers } from "ethers";
+/** EIP-3009 ReceiveWithAuthorization typed-data fields (USDC FiatTokenV2). */
+const RECEIVE_WITH_AUTHORIZATION_TYPES = {
+    ReceiveWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+const DEFAULT_TIMEOUT_SECONDS = 600;
+export class X402Manager {
+    gatewayUrl;
+    chainIdOverride;
+    constructor(gatewayUrl, opts = {}) {
+        this.gatewayUrl = gatewayUrl.replace(/\/+$/, "");
+        this.chainIdOverride = opts.chainId;
+    }
+    /**
+     * Pay for and make a single metered call to a marketplace API listing.
+     *
+     * @param input  The listing + upstream request.
+     * @param signer An ethers signer holding the buyer's USDC (e.g. `new ethers.Wallet(pk)`).
+     */
+    async payAndCall(input, signer) {
+        const method = (input.method ?? "GET").toUpperCase();
+        const path = String(input.path).replace(/^\/+/, "");
+        const url = `${this.gatewayUrl}/v1/api-x402/${input.listingId}/${path}`;
+        const bodyStr = input.body !== undefined ? JSON.stringify(input.body) : "";
+        const makeInit = (extraHeaders) => {
+            const headers = {
+                "Content-Type": "application/json",
+                ...input.headers,
+                ...extraHeaders,
+            };
+            const init = { method, headers };
+            if (bodyStr && !["GET", "HEAD"].includes(method))
+                init.body = bodyStr;
+            return init;
+        };
+        // 1. Probe — the gateway answers 402 with the payment challenge.
+        const probe = await fetch(url, makeInit());
+        if (probe.status !== 402) {
+            return toResult(probe, false);
+        }
+        const challenge = (await probe.json());
+        const accept = challenge.accepts?.[0];
+        if (!accept || accept.scheme !== "exact") {
+            throw new Error("x402: gateway did not offer a supported 'exact' payment option");
+        }
+        // Hard spend guard — refuse BEFORE signing if the quoted price exceeds the
+        // caller's per-call ceiling (the budgetUsdc cap). No funds move.
+        if (input.maxAmountBaseUnits !== undefined) {
+            const quote = BigInt(accept.maxAmountRequired);
+            if (quote > input.maxAmountBaseUnits) {
+                throw new Error(`x402 spend blocked: quoted ${quote} base units exceeds the allowed ${input.maxAmountBaseUnits} for this call (USDC spend cap)`);
+            }
+        }
+        // 2. Sign the EIP-3009 authorization over the advertised amount.
+        const from = await signer.getAddress();
+        const chainId = this.chainIdOverride ?? parseChainId(accept.network);
+        const nowSec = Math.floor(Date.now() / 1000);
+        const authorization = {
+            from,
+            to: accept.payTo,
+            value: accept.maxAmountRequired,
+            validAfter: 0,
+            validBefore: nowSec + (accept.maxTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS),
+            nonce: ethers.hexlify(ethers.randomBytes(32)),
+        };
+        const domain = {
+            name: accept.extra?.eip712?.name ?? "USD Coin",
+            version: accept.extra?.eip712?.version ?? "2",
+            chainId,
+            verifyingContract: accept.asset,
+        };
+        const signature = await signer.signTypedData(domain, RECEIVE_WITH_AUTHORIZATION_TYPES, authorization);
+        // 3. Re-send with the encoded payment header.
+        const header = encodePaymentHeader({ payload: { authorization, signature } });
+        const paid = await fetch(url, makeInit({ "PAYMENT-SIGNATURE": header }));
+        return toResult(paid, true, accept.maxAmountRequired);
+    }
+}
+function parseChainId(network) {
+    const m = /^eip155:(\d+)$/.exec(network);
+    if (m)
+        return Number(m[1]);
+    if (network === "base")
+        return 8453;
+    if (network === "base-sepolia")
+        return 84532;
+    throw new Error(`x402: unsupported network "${network}"`);
+}
+function encodePaymentHeader(payload) {
+    const json = JSON.stringify(payload);
+    return typeof Buffer !== "undefined"
+        ? Buffer.from(json, "utf8").toString("base64")
+        : btoa(json);
+}
+async function toResult(res, paid, amountPaidBaseUnits) {
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    const headers = {};
+    res.headers.forEach((val, key) => {
+        headers[key] = val;
+    });
+    return { status: res.status, headers, body, paid, ...(paid ? { amountPaidBaseUnits } : {}) };
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nookplot/runtime",
-  "version": "0.5.147",
+  "version": "0.5.149",
   "description": "Agent Runtime SDK — persistent connection, events, memory bridge, and economy for AI agents on Nookplot",
   "author": "nookplot",
   "type": "module",