@paidfor/mcp 0.5.0 → 0.6.0

package/README.md

@@ -45,7 +45,7 @@ The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1
 
 ## Let your agent pay, safely (stdio only)
 
-`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.2.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses quotes over 1.1x the listed price, caps the amount per call and per day, never pays twice for the same `intent_id` (a retry returns the stored result), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
+`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.4.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses quotes over 1.1x the listed price, caps the amount per call and per day, never pays twice for the same `intent_id` (a retry returns the stored result), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
 
 **Use a dedicated wallet holding a few dollars, never your main wallet.** There is no custody and no account: the key stays on your machine, is read only to sign, and is never logged, returned by a tool or sent anywhere.
 
@@ -76,7 +76,15 @@ Verify by asking the agent to call `wallet_status`.
 PAIDFOR_TEAM_KEY=pft_... npx -y @paidfor/mcp wallet register --label "research agent"
 ```
 
-It asks paidfor for a challenge, signs it with the wallet's key (the key is sent nowhere) and sends the signature back. The wallet is `PAIDFOR_WALLET_KEY_FILE` or `PAIDFOR_WALLET_KEY` when set, else `~/.paidfor/wallet.key`. A wallet registered with a key starts paused: open the team page, check its limits, untick Paused and save. The team key is read from the environment only, never from an argument.
+It asks paidfor for a challenge, signs it with the wallet's key (the key is sent nowhere) and sends the signature back. The wallet is `PAIDFOR_WALLET_KEY_FILE` or `PAIDFOR_WALLET_KEY` when set, else `~/.paidfor/wallet.key`; if the MCP client is configured with a key file elsewhere, set `PAIDFOR_WALLET_KEY_FILE` to that same path for this command too, or it registers the default wallet instead. A wallet registered with a key starts paused: open the team page, check its limits, untick Paused and save. The team key is read from the environment only, never from an argument. Written into the command it stays in your shell history; to keep it out, `read -rs PAIDFOR_TEAM_KEY && export PAIDFOR_TEAM_KEY` first and run the command without the prefix. Registering does not configure the server: `pay_x402` still needs `PAIDFOR_WALLET_KEY_FILE` in the MCP client config, as above.
+
+**Ask the team before each payment (0.6.0).** Registering alone does not put payments under the team's rules. Give the server the team key too:
+
+```json
+"env": { "PAIDFOR_WALLET_KEY_FILE": "/Users/you/.paidfor/wallet.key", "PAIDFOR_TEAM_KEY": "pft_..." }
+```
+
+With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks `POST /v1/team/authorize` after its own checks and before it signs, and the local caps still apply. It pays only on an approval, and signs with the approval's reference as the EIP-3009 nonce and its deadline as `validBefore`, so the payment can be matched to the ledger. If the server is unreachable or answers anything but a clear decision, nothing is paid. A decline comes back with the team's reason. A payment waiting for a person comes back with the link to approve it and the `intent_id` to call again with. After a payment the outcome goes to `POST /v1/team/outcome`; a report the server cannot take is kept in `~/.paidfor/team-outcomes/` and sent before the next payment. The key sits in your MCP client's config, so treat that file as a secret. The key cannot change rules, keys or approvals. The agent holds its own wallet key here, so a payment made some other way is not stopped. Stdio only: the hosted server never pays.
 
 **Routing a paid URL (0.4.1).** The model should reach for `pay_x402` whenever a URL is paid, metered, pay-per-call, x402, priced in USDC, said to charge a fee, or has answered 402 to any other fetch, even when the client also has a generic web fetch tool and the user never says how to pay. The tool is described as the way to fetch such a URL end to end (it sends the request, handles the 402, pays under the caps and returns the body), the description says a plain fetch fails on these URLs with 402, and the stdio server adds the same rule to its `instructions` only when the paying tools are registered; the hosted server's text is unchanged. `eval/routing.mjs` measures the first-call rate per model and prompt shape (`pnpm eval:routing`; results by date in `eval/routing-<date>.md`). `PAIDFOR_FETCH_ALIAS=1` also registers the same handler as `fetch_paid_url`, for clients that route by a fetch-shaped name; the eval compares both and the alias is off by default.
 
@@ -87,6 +95,7 @@ It asks paidfor for a challenge, signs it with the wallet's key (the key is sent
 | `PAIDFOR_MAX_PER_CALL_USD` | `0.50` | most one call may pay; `max_usd` can lower it, never raise it |
 | `PAIDFOR_DAILY_CAP_USD` | `5` | most all calls may pay per UTC day (tracked in `~/.paidfor/spend.json`) |
 | `BASE_RPC_URL` | `https://mainnet.base.org` | used only by `wallet_status` for the balance |
+| `PAIDFOR_TEAM_KEY` | | with a wallet: ask the team's rules before each payment and report the outcome (`https` only, or a server on this machine); also used by `wallet register` |
 | `PAIDFOR_FETCH_ALIAS` | off | `1` also registers `pay_x402` as `fetch_paid_url` (same handler, schema and caps) |
 
 Without a key (or with a misconfigured one, reported on stderr) the stdio server is the read-only server. The hosted server at `mcp.paidfor.dev` and the site's `/mcp` route never register `pay_x402` or `wallet_status`, by design: they never hold a key.
@@ -121,7 +130,7 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 ## Tests
 
-`pnpm test` builds and runs `test/*.test.mjs` with Node's test runner: `hosted-snapshot` fails on any change to the hosted server's tool list, instructions or empty resources/prompts lists (the ChatGPT app review rescans them daily; regenerate on purpose with `UPDATE_SNAPSHOT=1`), `pay-wording` checks the `pay_x402` framing, guarantees, annotations and the alias, `pay-replay` the replay line and the `intent_id` guidance against a local seller. The site's `vitest` suite (`test/mcp-pay.test.ts` at the repo root) covers the paying tools end to end against a local seller.
+`pnpm test` builds and runs `test/*.test.mjs` with Node's test runner: `hosted-snapshot` fails on any change to the hosted server's tool list, instructions or empty resources/prompts lists (the ChatGPT app review rescans them daily; regenerate on purpose with `UPDATE_SNAPSHOT=1`), `pay-wording` checks the `pay_x402` framing, guarantees, annotations and the alias, `pay-replay` the replay line and the `intent_id` guidance against a local seller, `pay-team` team mode against a local seller and a scripted server. The site's `vitest` suite (`test/mcp-pay.test.ts` at the repo root) covers the paying tools end to end against a local seller, and `test/mcp-team.test.ts` runs team mode against the real server code.
 
 ## Claude Desktop extension
 
@@ -133,6 +142,7 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 ## Changelog
 
+- **0.6.0** (unpublished): team mode. With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks the team before signing, fails closed, signs the approval's nonce and deadline and reports the outcome. Needs `@paidfor/x402-safe-fetch` 0.4.0. The hosted server's tools and instructions are unchanged.
 - **0.5.0** (unpublished): `paidfor-mcp wallet register` registers the configured wallet to a paidfor team (`PAIDFOR_TEAM_KEY`), signing the team's challenge locally; new test `wallet-register.test.mjs`. The hosted server's tools and instructions are unchanged.
 - **0.4.1** (unpublished): `pay_x402` is framed as the way to fetch a paid (x402) URL end to end, its description says a generic fetch fails on such URLs with 402 and that any URL called paid, metered, x402 or that answered 402 goes to it with the same method, headers and body; the stdio server with a wallet adds the same routing rule to its instructions (`PAY_ROUTING_RULE` in `rules.ts`). A replayed result (same `intent_id`) now opens with the age and time of the stored result and says to call again with a new id for a new purchase; the description, the schema and the stdio rules say to reuse an `intent_id` only when retrying the same purchase after an error or timeout and to omit it otherwise (a date-only id chosen in three fresh sessions replayed instead of buying). Optional `fetch_paid_url` alias (`PAIDFOR_FETCH_ALIAS=1`). New `pnpm test` (hosted-surface snapshot, wording) and `pnpm eval:routing`. The hosted server's tools and instructions are unchanged.
 - **0.4.0**: `report_x402_payment` on every transport; `mcpName` `dev.paidfor/paidfor`.

package/dist/pay.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Receipt, type SafeNetwork } from "@paidfor/x402-safe-fetch";
+import { type TeamDecision } from "./team.js";
 import { type Limits, type LoadedWallet } from "./wallet.js";
 export declare const PAY_TOOL_NAMES: readonly ["pay_x402", "fetch_paid_url", "wallet_status"];
 /** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
@@ -30,6 +31,10 @@ export type PayOptions = {
     balanceOf?: (address: `0x${string}`) => Promise<bigint>;
     /** Also register the same handler as fetch_paid_url (PAY_ALIAS). Off by default; stdio turns it on with PAIDFOR_FETCH_ALIAS=1. */
     fetchAlias?: boolean;
+    /** PAIDFOR_TEAM_KEY: ask the team's rules before every payment and report the outcome. Stdio only. */
+    teamKey?: string;
+    /** Tests only: how long to wait before the second try of an outcome report. */
+    teamRetryDelayMs?: number;
 };
 /** The receipt as pay_x402 reports it: what was paid, to whom, the proof, and how to check it. */
 export declare function receiptSummary(r: Receipt): {
@@ -57,6 +62,16 @@ export declare function receiptSummary(r: Receipt): {
 export declare function describeAge(ms: number): string;
 /** The first line of a replayed pay_x402 result: the age and time of the stored result, so a second genuine purchase is not mistaken for a retry. */
 export declare function replayHead(r: Receipt, now?: number): string;
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export declare function teamRefusal(d: Exclude<TeamDecision, {
+    kind: "approve";
+}>, intentId: string, limits: unknown): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
 export declare function truncateBody(body: string): {
     body: string;
     note: string | null;

package/dist/pay.js

@@ -3,6 +3,7 @@
  * user's own wallet and report the verified outcome to the index. Only stdio.ts imports this module;
  * the hosted service (index.ts) and the site's /mcp route never do, because they never hold a key.
  */
+import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-safe-fetch";
@@ -10,6 +11,7 @@ import { createPublicClient, erc20Abi, http } from "viem";
 import { base as baseChain } from "viem/chains";
 import { z } from "zod";
 import { INSTRUCTIONS, NO_ACCOUNT_PROMISE, PAID_URL_SIGNALS, PAY_ROUTING_RULE, PLAIN_FETCH_FAILS } from "./server.js";
+import { TeamClient, outcomeFor } from "./team.js";
 import { SpendLedger, fromMicro, paidforDir, toMicro } from "./wallet.js";
 export const PAY_TOOL_NAMES = ["pay_x402", "fetch_paid_url", "wallet_status"];
 /** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
@@ -83,6 +85,20 @@ export function replayHead(r, now = Date.now()) {
     const when = at && Number.isFinite(Date.parse(at)) ? `stored ${describeAge(now - Date.parse(at))} ago (${at})` : "stored earlier (time unknown, the original receipt file is gone)";
     return `Replayed the result ${when} for intent ${r.intent_id}; nothing was paid again. If this is a new purchase, call again with a new intent_id.`;
 }
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export function teamRefusal(d, intentId, limits) {
+    const res = (head, detail, isError = false) => text(`${head}\n\n${json({ ...detail, paid: false, intent_id: intentId, limits })}`, isError);
+    switch (d.kind) {
+        case "decline":
+            return res(`Declined by your team's rules: ${d.message}\nNothing was paid.`, { refused: "team_decline", reason: d.reason, ...(d.retry_after !== undefined ? { retry_after: d.retry_after } : {}) });
+        case "needs_approval":
+            return res(`A person has to approve this payment before it can be made. Nothing was paid.\nGive the user this link: ${d.approve_url}\nAfter they approve it, call pay_x402 again with intent_id "${intentId}". The request waits until ${d.expires_at}.${d.message ? ` ${d.message}` : ""}`, { refused: "team_needs_approval", approve_url: d.approve_url, expires_at: d.expires_at });
+        case "already_settled":
+            return res(`This purchase was already paid (settlement ${d.settlement_ref}, outcome ${d.outcome}); nothing was paid again. If this is a new purchase, call again with a new intent_id.`, { refused: "team_already_settled", settlement_ref: d.settlement_ref, outcome: d.outcome });
+        case "failed":
+            return res(`The team's rules could not be checked, so nothing was paid: ${d.message}\nCalling again with intent_id "${intentId}" is safe.`, { refused: "team_authorize_failed" }, true);
+    }
+}
 export function truncateBody(body) {
     const buf = Buffer.from(body, "utf8");
     if (buf.byteLength <= BODY_LIMIT_BYTES)
@@ -103,6 +119,9 @@ export async function registerPayTools(server, o) {
     const base = o.baseUrl.replace(/\/$/, "");
     const address = o.wallet.account.address;
     const logger = { warn: (m) => void process.stderr.write(`${m}\n`) };
+    const team = o.teamKey ? new TeamClient({ baseUrl: base, teamKey: o.teamKey, dir, ...(o.fetch ? { fetch: o.fetch } : {}), warn: logger.warn, ...(o.teamRetryDelayMs !== undefined ? { retryDelayMs: o.teamRetryDelayMs } : {}) }) : null;
+    if (team)
+        void team.flush();
     const payInput = {
         url: z.string().url().describe("The URL to fetch and, if it answers 402, pay for"),
         method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
@@ -124,6 +143,20 @@ export async function registerPayTools(server, o) {
             spent_today_usdc: fromMicro(spent),
             ...(max_usd !== undefined && max_usd > o.limits.maxPerCallUsd ? { note: `max_usd ${max_usd} is above PAIDFOR_MAX_PER_CALL_USD; capped at ${o.limits.maxPerCallUsd}` } : {}),
         };
+        // Team mode needs the id before the first call: a person's approval is claimed by asking again with the same one.
+        const intentId = intent_id ?? (team ? randomUUID() : undefined);
+        const asked = {};
+        /** Say what happened to an approved payment. Undefined when the server approved nothing. */
+        const settle = async (r) => {
+            const d = asked.decision;
+            if (!team || d?.kind !== "approve")
+                return undefined;
+            if (!r) {
+                logger.warn(`paidfor-mcp: no receipt for approved intent ${intentId}, so no outcome was reported; the approval keeps counting against the budgets`);
+                return undefined;
+            }
+            return team.report(outcomeFor(r, address, d.auth_ref));
+        };
         const sf = safeFetch(o.wallet.account, {
             maxPerCallUsd: cap,
             maxOverListedRatio: 1.1,
@@ -134,31 +167,48 @@ export async function registerPayTools(server, o) {
             logger,
             ...(o.network ? { network: o.network } : {}),
             ...(o.fetch ? { fetch: o.fetch } : {}),
+            ...(team
+                ? {
+                    authorize: async (q) => {
+                        const d = await team.authorize({ wallet: q.payer, intent_id: q.intentId, resource_url: q.url, pay_to: q.payTo, amount_atomic: q.amountAtomic, network: q.network, asset: q.asset, scheme: q.scheme, protocol: "x402" });
+                        asked.decision = d;
+                        return d.kind === "approve" ? { approve: true, nonce: d.auth_ref, validBefore: d.valid_before } : { approve: false, message: d.message };
+                    },
+                }
+                : {}),
         });
         try {
-            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId: intent_id });
+            // Owed reports go first: until the server has them it answers the same purchase with pending_settlement.
+            await team?.flush();
+            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId });
             const r = res.receipt;
             if (r.paid && !r.replayed)
                 await ledger.add(toMicro(r.amount_usdc));
+            const teamReport = await settle(r);
             const { body: out, note } = truncateBody(await res.text());
             const head = r.replayed
                 ? replayHead(r)
                 : r.paid
                     ? `Paid ${r.amount_usdc} USDC to ${r.quote?.pay_to}; the seller answered HTTP ${res.status} (${r.outcome}).`
                     : `No payment was needed; the server answered HTTP ${res.status}.`;
-            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
+            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(teamReport ? { team_outcome_report: teamReport } : {}), ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
         }
         catch (e) {
+            if (asked.decision && asked.decision.kind !== "approve" && e instanceof PaymentRefusedError && e.code === "refused_authorize") {
+                return teamRefusal(asked.decision, e.receipt?.intent_id ?? intentId, limits);
+            }
+            const teamReport = await settle(e instanceof SafeFetchError ? e.receipt : undefined);
+            const reported = teamReport ? { team_outcome_report: teamReport } : {};
             if (e instanceof PaymentRefusedError) {
                 const why = e.code === "refused_max_per_call" && dailyBinds
                     ? `refused: today's cap of ${o.limits.dailyCapUsd} USD (PAIDFOR_DAILY_CAP_USD) leaves ${fromMicro(Math.max(leftMicro, 0))} USDC. ${e.message}`
                     : e.code === "refused_max_per_call"
                         ? `refused: the quote is above this call's cap of ${cap} USD (max_usd, capped by PAIDFOR_MAX_PER_CALL_USD ${o.limits.maxPerCallUsd}). ${e.message}`
                         : `refused: ${e.message}`;
-                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intent_id ?? null, limits })}`);
+                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intentId ?? null, limits, ...reported })}`);
             }
             if (e instanceof SafeFetchError) {
-                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits })}`, true);
+                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits, ...reported })}`, true);
             }
             return text(`error: ${e instanceof Error ? e.message : String(e)}`, true);
         }
@@ -193,6 +243,7 @@ export async function registerPayTools(server, o) {
             max_per_call_usd: o.limits.maxPerCallUsd,
             daily_cap_usd: o.limits.dailyCapUsd,
             spent_today_usdc: fromMicro(spent),
+            ...(team ? { team_mode: true } : {}),
         };
         return text(`${usdc === null ? "Balance unavailable" : `${usdc} USDC on Base`} at ${address}.\n\n${json(s)}`);
     });

package/dist/stdio.js

@@ -3,7 +3,8 @@
  * `npx @paidfor/mcp`: the stdio server. With PAIDFOR_WALLET_KEY_FILE (or PAIDFOR_WALLET_KEY) set it also
  * registers pay_x402 and wallet_status; without one it is the same read-only server as the hosted one.
  * `paidfor-mcp wallet new` writes a fresh key to ~/.paidfor/wallet.key (mode 600) and prints the address.
- * `paidfor-mcp wallet register` proves that wallet to a paidfor team (PAIDFOR_TEAM_KEY), so the team's rules apply to it.
+ * `paidfor-mcp wallet register` proves that wallet to a paidfor team (PAIDFOR_TEAM_KEY). With PAIDFOR_TEAM_KEY also set on
+ * the server, pay_x402 asks the team's rules before every payment.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { DEFAULT_BASE, createServer } from "./server.js";
@@ -63,7 +64,9 @@ if (pay && limits) {
     const { INSTRUCTIONS_WITH_PAY, registerPayTools } = await import("./pay.js");
     const server = createServer({ baseUrl, instructions: INSTRUCTIONS_WITH_PAY });
     // PAIDFOR_FETCH_ALIAS=1 also registers the handler as fetch_paid_url (eval/routing.mjs measures whether the second name helps).
-    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1" });
+    // PAIDFOR_TEAM_KEY: every payment asks the team's rules first (docs/team-api.md).
+    const teamKey = process.env.PAIDFOR_TEAM_KEY?.trim() || undefined;
+    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1", ...(teamKey ? { teamKey } : {}) });
     await server.connect(new StdioServerTransport());
 }
 else {

package/dist/team.d.ts

@@ -0,0 +1,80 @@
+import type { Receipt } from "@paidfor/x402-safe-fetch";
+export declare const AUTHORIZE_TIMEOUT_MS = 10000;
+export declare const REPORT_TIMEOUT_MS = 5000;
+export type AuthorizeBody = {
+    wallet: string;
+    intent_id: string;
+    resource_url: string;
+    pay_to: string;
+    amount_atomic: string;
+    network: string;
+    asset: string;
+    scheme: string;
+    protocol: "x402";
+};
+export type TeamDecision = {
+    kind: "approve";
+    auth_ref: string;
+    valid_before: number;
+} | {
+    kind: "decline";
+    reason: string;
+    message: string;
+    retry_after?: number;
+} | {
+    kind: "needs_approval";
+    approve_url: string;
+    expires_at: string;
+    message: string;
+} | {
+    kind: "already_settled";
+    settlement_ref: string;
+    outcome: string;
+    message: string;
+} | {
+    kind: "failed";
+    message: string;
+};
+export type OutcomeBody = {
+    wallet: string;
+    intent_id: string;
+    auth_ref: string;
+    paid: boolean;
+    settlement_ref?: string;
+    outcome?: string;
+    http_status?: number;
+    response_sha256?: string;
+};
+/** sent: the server has it. queued: kept on disk, sent again before the next payment. rejected: the server refused it for good. */
+export type ReportState = "sent" | "queued" | "rejected";
+/** What to report for a payment that was approved, from its receipt. */
+export declare function outcomeFor(r: Receipt, wallet: string, authRef: string): OutcomeBody;
+/** Exported for tests: a 200's body as a decision. Anything not exactly one of the contract's answers is "failed". */
+export declare function readDecision(b: unknown): TeamDecision;
+export declare class TeamClient {
+    private readonly base;
+    private readonly key;
+    private readonly queueDir;
+    private readonly fetchFn;
+    private readonly warn;
+    private readonly retryDelayMs;
+    /** The key travels in a header. Plain http is for a server on this machine only. */
+    private readonly keySafe;
+    constructor(o: {
+        baseUrl: string;
+        teamKey: string;
+        dir: string;
+        fetch?: typeof globalThis.fetch;
+        warn?: (m: string) => void;
+        retryDelayMs?: number;
+    });
+    private post;
+    /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
+    authorize(body: AuthorizeBody): Promise<TeamDecision>;
+    /** One try. "retry" means the server could not take it now; a 4xx will never be taken, so it is not kept. */
+    private send;
+    private queueFile;
+    report(body: OutcomeBody): Promise<ReportState>;
+    /** Send what earlier reports left behind. Stops at the first one the server cannot take now. Never throws. */
+    flush(): Promise<void>;
+}

package/dist/team.js

@@ -0,0 +1,170 @@
+/**
+ * Team mode: the two calls pay_x402 makes around a payment (docs/team-api.md). `authorize` asks before signing and
+ * turns anything but a clean decision into "failed", which pays nothing. `report` says what happened afterwards; a
+ * report the server could not take is kept on disk and sent again, because an approval nobody reports keeps counting
+ * against the budgets. Only pay.ts imports this module.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const AUTHORIZE_TIMEOUT_MS = 10_000;
+export const REPORT_TIMEOUT_MS = 5_000;
+/** The words the server takes for a paid outcome. */
+const PAID_OUTCOMES = ["ok", "non_delivery", "wrong_goods", "overcharge", "duplicate", "paid_no_response"];
+/** What to report for a payment that was approved, from its receipt. */
+export function outcomeFor(r, wallet, authRef) {
+    const base = { wallet, intent_id: r.intent_id, auth_ref: authRef };
+    // Nothing left this machine, or the seller says its settlement failed: the money did not move.
+    if (!r.paid || r.settlement.parsed?.success === false)
+        return { ...base, paid: false };
+    return {
+        ...base,
+        paid: true,
+        // With no transaction hash the signed nonce is what finds the settlement on chain.
+        settlement_ref: r.tx_hash ?? r.nonce ?? authRef,
+        outcome: r.reported_outcome && PAID_OUTCOMES.includes(r.reported_outcome) ? r.reported_outcome : "non_delivery",
+        ...(r.response ? { http_status: r.response.status } : {}),
+        ...(r.response?.sha256 ? { response_sha256: r.response.sha256 } : {}),
+    };
+}
+const str = (v) => typeof v === "string" && v.length > 0;
+function failedStatus(status, body) {
+    const said = body && typeof body === "object" && str(body.error) ? ` ${body.error.slice(0, 300)}` : "";
+    if (status === 401)
+        return { kind: "failed", message: `paidfor refused the team key; check PAIDFOR_TEAM_KEY.${said}` };
+    if (status === 404)
+        return { kind: "failed", message: `this wallet is not registered to the team; run: paidfor-mcp wallet register.${said}` };
+    return { kind: "failed", message: `paidfor answered HTTP ${status}.${said}` };
+}
+/** Exported for tests: a 200's body as a decision. Anything not exactly one of the contract's answers is "failed". */
+export function readDecision(b) {
+    const bad = { kind: "failed", message: "paidfor's answer could not be read." };
+    if (!b || typeof b !== "object")
+        return bad;
+    const d = b;
+    const message = str(d.message) ? d.message : "";
+    switch (d.decision) {
+        case "approve":
+            return str(d.auth_ref) && typeof d.valid_before === "number" ? { kind: "approve", auth_ref: d.auth_ref, valid_before: d.valid_before } : bad;
+        case "decline":
+            return str(d.reason) ? { kind: "decline", reason: d.reason, message: message || d.reason, ...(typeof d.retry_after === "number" ? { retry_after: d.retry_after } : {}) } : bad;
+        case "needs_approval":
+            return str(d.approve_url) && str(d.expires_at) ? { kind: "needs_approval", approve_url: d.approve_url, expires_at: d.expires_at, message } : bad;
+        case "already_settled":
+            return { kind: "already_settled", settlement_ref: str(d.settlement_ref) ? d.settlement_ref : "unknown", outcome: str(d.outcome) ? d.outcome : "unknown", message };
+        default:
+            return bad;
+    }
+}
+export class TeamClient {
+    base;
+    key;
+    queueDir;
+    fetchFn;
+    warn;
+    retryDelayMs;
+    /** The key travels in a header. Plain http is for a server on this machine only. */
+    keySafe;
+    constructor(o) {
+        this.base = o.baseUrl.replace(/\/$/, "");
+        this.key = o.teamKey;
+        this.queueDir = join(o.dir, "team-outcomes");
+        this.fetchFn = o.fetch ?? globalThis.fetch;
+        this.warn = o.warn ?? (() => undefined);
+        this.retryDelayMs = o.retryDelayMs ?? 250;
+        const u = new URL(this.base);
+        this.keySafe = u.protocol === "https:" || ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+    }
+    post(path, body, timeoutMs) {
+        return this.fetchFn(`${this.base}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.key}` },
+            body: JSON.stringify(body),
+            redirect: "error", // the key goes to the configured origin and nowhere else
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
+    async authorize(body) {
+        if (!this.keySafe)
+            return { kind: "failed", message: `refusing to send the team key to ${this.base}; use https.` };
+        let res;
+        try {
+            res = await this.post("/v1/team/authorize", body, AUTHORIZE_TIMEOUT_MS);
+        }
+        catch {
+            return { kind: "failed", message: "paidfor could not be reached." };
+        }
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            /* an unreadable body is handled below */
+        }
+        return res.status === 200 ? readDecision(parsed) : failedStatus(res.status, parsed);
+    }
+    /** One try. "retry" means the server could not take it now; a 4xx will never be taken, so it is not kept. */
+    async send(body) {
+        if (!this.keySafe)
+            return "retry";
+        try {
+            const res = await this.post("/v1/team/outcome", body, REPORT_TIMEOUT_MS);
+            void res.body?.cancel().catch(() => undefined);
+            if (res.ok)
+                return "sent";
+            if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+                this.warn(`paidfor-mcp: the team outcome for intent ${body.intent_id} was refused with HTTP ${res.status}`);
+                return "rejected";
+            }
+            return "retry";
+        }
+        catch {
+            return "retry";
+        }
+    }
+    queueFile(body) {
+        return join(this.queueDir, `${createHash("sha256").update(`${body.intent_id}\n${body.auth_ref}`).digest("hex").slice(0, 40)}.json`);
+    }
+    async report(body) {
+        let r = await this.send(body);
+        if (r === "retry") {
+            await new Promise((d) => setTimeout(d, this.retryDelayMs));
+            r = await this.send(body);
+        }
+        if (r !== "retry")
+            return r;
+        try {
+            await mkdir(this.queueDir, { recursive: true, mode: 0o700 });
+            const file = this.queueFile(body);
+            await writeFile(`${file}.tmp`, JSON.stringify(body), { mode: 0o600 });
+            await rename(`${file}.tmp`, file);
+        }
+        catch (e) {
+            this.warn(`paidfor-mcp: could not keep the team outcome for intent ${body.intent_id}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return "queued";
+    }
+    /** Send what earlier reports left behind. Stops at the first one the server cannot take now. Never throws. */
+    async flush() {
+        let names;
+        try {
+            names = (await readdir(this.queueDir)).filter((n) => n.endsWith(".json"));
+        }
+        catch {
+            return; // nothing queued yet
+        }
+        for (const name of names) {
+            const file = join(this.queueDir, name);
+            try {
+                const r = await this.send(JSON.parse(await readFile(file, "utf8")));
+                if (r === "retry")
+                    return;
+                await unlink(file);
+            }
+            catch (e) {
+                this.warn(`paidfor-mcp: could not resend ${name}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "mcpName": "dev.paidfor/paidfor",
   "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller, list_reliable_sellers and recent_changes, plus pay_x402 (stdio, your own wallet)",
   "license": "MIT",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@paidfor/x402-safe-fetch": "0.2.0",
+    "@paidfor/x402-safe-fetch": "0.4.0",
     "viem": "^2.57.13",
     "zod": "^4.0.0"
   },