@paidfor/mcp 0.5.0 → 0.7.0

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/dist/wallet.d.ts

@@ -26,8 +26,17 @@ export declare function newWallet(home?: string): Promise<{
 export declare const defaultKeyFile: (home?: string) => string;
 /** paidfor refused or could not answer a registration. The message never includes a key. */
 export declare class RegisterError extends Error {
+    readonly status?: number | undefined;
     name: string;
+    /** Builds the error; `status` is paidfor's HTTP status when it answered (401: the team key was refused). */
+    constructor(message: string, status?: number | undefined);
 }
+/**
+ * Team keys and link codes travel to paidfor in headers and bodies. Plain http is for a server on this machine only;
+ * anything else is refused before a request is made.
+ */
+export declare function assertKeySafeBase(base: string): void;
+/** What registerWallet reports: the address and whether it was already there, moved or starts paused. */
 export type Registered = {
     address: `0x${string}`;
     already: boolean;
@@ -46,6 +55,7 @@ export declare function registerWallet(o: {
     env?: Env;
     home?: string;
     fetchFn?: typeof fetch;
+    link?: string;
 }): Promise<Registered>;
 export type Limits = {
     maxPerCallUsd: number;

package/dist/wallet.js

@@ -76,7 +76,23 @@ export async function newWallet(home = homedir()) {
 export const defaultKeyFile = (home = homedir()) => join(paidforDir(home), "wallet.key");
 /** paidfor refused or could not answer a registration. The message never includes a key. */
 export class RegisterError extends Error {
+    status;
     name = "RegisterError";
+    /** Builds the error; `status` is paidfor's HTTP status when it answered (401: the team key was refused). */
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Team keys and link codes travel to paidfor in headers and bodies. Plain http is for a server on this machine only;
+ * anything else is refused before a request is made.
+ */
+export function assertKeySafeBase(base) {
+    const u = new URL(base);
+    if (u.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) {
+        throw new RegisterError(`refusing to send a team key over ${u.protocol.replace(":", "")} to ${u.hostname}; use https`);
+    }
 }
 /**
  * `paidfor-mcp wallet register`: proves to a paidfor team that this wallet is the agent's, by signing the challenge
@@ -97,11 +113,8 @@ export async function registerWallet(o) {
         throw none;
     const f = o.fetchFn ?? fetch;
     const base = o.baseUrl.replace(/\/$/, "");
-    // The team key travels in a header. Plain http is for a server on this machine only.
-    const u = new URL(base);
-    if (u.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) {
-        throw new RegisterError(`refusing to send a team key over ${u.protocol.replace(":", "")} to ${u.hostname}; use https`);
-    }
+    assertKeySafeBase(base);
+    /** POSTs to paidfor with the team key; a non-2xx answer is a RegisterError carrying the status. */
     const post = async (path, body) => {
         let res;
         try {
@@ -112,14 +125,16 @@ export async function registerWallet(o) {
         }
         const j = (await res.json().catch(() => ({})));
         if (!res.ok)
-            throw new RegisterError(`paidfor answered ${res.status}${typeof j.error === "string" ? `: ${j.error}` : ""}`);
+            throw new RegisterError(`paidfor answered ${res.status}${typeof j.error === "string" ? `: ${j.error}` : ""}`, res.status);
         return j;
     };
     const c = await post("/v1/team/wallets/challenge", { address: loaded.account.address });
     if (typeof c.message !== "string" || typeof c.token !== "string")
         throw new RegisterError("paidfor did not return a challenge to sign");
     const signature = await loaded.account.signMessage({ message: c.message });
-    const r = await post("/v1/team/wallets", { message: c.message, token: c.token, signature, label: o.label ?? "" });
+    // `link`: the device code of a link a person approved in the browser for this address (`paidfor-mcp init`), so the
+    // server can start the wallet unpaused. It is a secret, like the team key, and goes only in this body.
+    const r = await post("/v1/team/wallets", { message: c.message, token: c.token, signature, label: o.label ?? "", ...(o.link ? { link: o.link } : {}) });
     const w = (r.wallet ?? {});
     return { address: (w.address ?? loaded.account.address), already: r.already === true, moved: r.moved === true, paused: w.rules?.paused === true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.5.0",
+  "version": "0.7.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"
   },