@web42/w42 0.1.20 → 0.1.22

package/README.md

@@ -1,6 +1,6 @@
 # @web42/cli
 
-CLI for the Web42 Agent Network — authenticate, publish, discover, and interact with A2A agents.
+CLI for the Web42 Agent Network — authenticate, publish, discover, interact with A2A agents, and manage AP2 payments.
 
 ## Installation
 
@@ -11,20 +11,22 @@ npm install -g @web42/cli
 ## Authentication
 
 ```bash
-web42 auth login     # Sign in via GitHub OAuth
-web42 auth logout    # Sign out
-web42 auth whoami    # Show current user
+w42 auth login     # Sign in via GitHub OAuth
+w42 auth logout    # Sign out
+w42 auth whoami    # Show current user
 ```
 
+---
+
 ## Commands
 
-### `web42 search <query>`
+### `w42 search <query>`
 
 Search the network for agents.
 
 ```bash
-web42 search "data analysis"
-web42 search "image processing" --limit 20
+w42 search "data analysis"
+w42 search "pizza ordering" --limit 20
 ```
 
 | Option | Description |
@@ -33,13 +35,14 @@ web42 search "image processing" --limit 20
 
 ---
 
-### `web42 send <agent> <message>`
+### `w42 send <agent> <message>`
 
 Send a message to an A2A agent. `<agent>` can be a slug (`@user/agent`) or a direct URL (`http://localhost:3001`).
 
 ```bash
-web42 send @alice/summarizer "Summarize this document"
-web42 send http://localhost:3001 "Hello"
+w42 send @alice/summarizer "Summarize this document"
+w42 send http://localhost:3001 "Hello"
+w42 send @alice/pizza "Margherita please" --pay tx_a1b2c3d4
 ```
 
 | Option | Description |
@@ -47,134 +50,231 @@ web42 send http://localhost:3001 "Hello"
 | `--new` | Start a new conversation (clears saved context) |
 | `--context <id>` | Use a specific context ID |
 | `--task-id <id>` | Reply to a specific task (e.g. one in `input-required` state) |
-| `--pay <token>` | Attach AP2 payment token as PaymentMandate data part |
+| `--pay <tx_id>` | Attach a `PaymentMandate` from a local transaction (use a tx ID from `w42 cart list`) |
+
+When an agent sends a `CartMandate`, the CLI auto-saves it as a local transaction (`tx_xxx`) and prints the next step. If you have a matching intent locally cached, it prints the one-liner checkout command directly.
 
 ---
 
-### `web42 serve`
+### `w42 wallet`
 
-Start a local A2A server for your agent, bridging to an OpenClaw gateway.
+View your Web42 Wallet balance.
 
 ```bash
-web42 serve
-web42 serve --port 3001 --url https://my-agent.ngrok.io --verbose
+w42 wallet
+```
+
+#### `w42 wallet topup <amount>`
+
+Add funds to your wallet. Amount is in dollars.
+
+```bash
+w42 wallet topup 50.00
+```
+
+---
+
+### `w42 cart`
+
+Manage AP2 cart payments. Carts are auto-saved as local transactions (`tx_xxx`) when received from an agent via `w42 send`.
+
+#### `w42 cart list`
+
+List all local payment transactions.
+
+```bash
+w42 cart list
+w42 cart list --status cart_received
 ```
 
 | Option | Description |
 |---|---|
-| `--port <port>` | Port to listen on (default: 4000) |
-| `--url <url>` | Public URL for registration and AgentCard (e.g. from ngrok) |
-| `--openclaw-port <port>` | OpenClaw gateway port (default: 18789) |
-| `--openclaw-token <token>` | OpenClaw gateway auth token (or `OPENCLAW_GATEWAY_TOKEN`) |
-| `--openclaw-agent <id>` | OpenClaw agent ID to target (default: `main`) |
-| `--client-id <id>` | Developer app client ID (or `W42_CLIENT_ID`) |
-| `--client-secret <secret>` | Developer app client secret (or `W42_CLIENT_SECRET`) |
-| `--visibility <vis>` | Marketplace visibility: `public` or `private` |
-| `--verbose` | Enable verbose request/response logging |
+| `--status <status>` | Filter by status: `cart_received`, `session_created`, `approved`, `sent` |
 
----
+#### `w42 cart sign <tx_id>`
 
-### `web42 register <url>`
+Create a payment session for human approval. Opens a browser signing URL.
 
-Register an agent with the Web42 Network. The URL must serve `/.well-known/agent-card.json`.
+```bash
+w42 cart sign tx_a1b2c3d4
+```
+
+- Validates that the cart supports `WEB42_WALLET` before proceeding.
+- Stores `sessionCode` and `signingUrl` on the transaction.
+- Returns `{ tx, signing_url }` — present the URL to the user.
+
+#### `w42 cart poll <tx_id>`
+
+Check the status of a payment session. When completed, stores the full `PaymentMandate` on the transaction.
+
+```bash
+w42 cart poll tx_a1b2c3d4
+```
+
+#### `w42 cart checkout <tx_id> --intent <nick>`
+
+Execute a payment against a matching intent — no human approval needed.
 
 ```bash
-web42 register https://my-agent.example.com
-web42 register https://my-agent.example.com --visibility private --tags "nlp,summarization"
+w42 cart checkout tx_a1b2c3d4 --intent starbucks-daily
 ```
 
 | Option | Description |
 |---|---|
-| `--price <cents>` | Price in cents (default: 0 = free) |
-| `--license <license>` | License (e.g. `MIT`, `Apache-2.0`) |
-| `--visibility <vis>` | `public` or `private` (default: `public`) |
-| `--tags <tags>` | Comma-separated tags |
-| `--categories <cats>` | Comma-separated categories |
+| `--intent <nick>` | Intent nick to use (required) |
+
+- Validates that the cart supports `WEB42_WALLET` before proceeding.
+- Returns structured error codes when the intent is invalid (see below).
+- Stale intents (exhausted, expired, not found) are automatically evicted from the local cache.
+
+**Intent error codes:**
+
+| Code | Meaning |
+|---|---|
+| `INTENT_NOT_FOUND` | Intent doesn't exist on the platform |
+| `INTENT_INACTIVE` | Intent is exhausted or revoked |
+| `INTENT_EXPIRED` | Intent has passed its expiry date |
+| `INTENT_BUDGET_EXHAUSTED` | Lifetime budget fully consumed |
+| `INTENT_PERIOD_BUDGET_EXHAUSTED` | Daily/weekly/monthly budget hit |
+| `INTENT_AMOUNT_EXCEEDED` | Cart total exceeds the per-transaction cap |
+| `INTENT_AGENT_NOT_AUTHORIZED` | Merchant not covered by this intent |
+| `INTENT_CURRENCY_MISMATCH` | Cart currency doesn't match the intent |
 
 ---
 
-### `web42 pay`
+### `w42 intent`
 
-AP2 payment commands — intents, checkout, and human signing.
+Manage payment intents. Intents are pre-authorizations that let agents spend on your behalf without per-purchase approval.
 
-#### `web42 pay intent propose`
+#### `w42 intent propose`
 
-Generate an intent creation URL for the user to authorize in the browser.
+Generate an intent creation URL for the user to authorize in the browser (attaches a card for automatic charging).
 
 ```bash
-web42 pay intent propose --nick starbucks-daily --agents @x~starbucks --max-amount 5.00 --prompt-playback "Spend up to $5/day at Starbucks" --recurring daily
+w42 intent propose \
+  --nick starbucks-daily \
+  --agents @x~starbucks \
+  --max-amount 5.00 \
+  --prompt-playback "Spend up to $5/day at Starbucks" \
+  --recurring daily
 ```
 
 | Option | Description |
 |---|---|
-| `--nick <nick>` | Short identifier for the intent (required) |
+| `--nick <nick>` | Short identifier, 3–50 chars, lowercase alphanumeric + hyphens (required) |
 | `--agents <slugs>` | Comma-separated merchant agent slugs (required) |
 | `--max-amount <dollars>` | Max amount per transaction (required) |
 | `--prompt-playback <text>` | Human-readable description (required) |
 | `--currency <code>` | Currency code (default: `USD`) |
 | `--recurring <type>` | `once`, `daily`, `weekly`, or `monthly` (default: `once`) |
-| `--budget <dollars>` | Lifetime budget |
+| `--budget <dollars>` | Lifetime budget cap |
 | `--expires <date>` | Expiry date (ISO 8601) |
 
-#### `web42 pay intent get --nick <nick>`
+#### `w42 intent get <nick>`
 
-Fetch an intent by nick. Caches locally if active.
+Fetch an intent by nick. Caches it locally if active.
 
-#### `web42 pay intent list`
+```bash
+w42 intent get starbucks-daily
+```
 
-List all your payment intents.
+#### `w42 intent list`
 
-#### `web42 pay intent revoke --nick <nick>`
+List all your payment intents and sync the local cache.
+
+```bash
+w42 intent list
+```
+
+#### `w42 intent revoke <nick>`
 
 Revoke an active intent.
 
-#### `web42 pay checkout`
+```bash
+w42 intent revoke starbucks-daily
+```
 
-Execute a payment against a matching intent (no human approval needed).
+---
+
+### `w42 serve`
+
+Start a local A2A server for your agent, bridging to an OpenClaw gateway.
 
 ```bash
-web42 pay checkout --cart '<json>' --agent @x~starbucks --intent starbucks-daily
+w42 serve
+w42 serve --port 3001 --url https://my-agent.ngrok.io --verbose
 ```
 
 | Option | Description |
 |---|---|
-| `--cart <json>` | CartMandate JSON (required) |
-| `--agent <slug>` | Merchant agent slug (required) |
-| `--intent <nick>` | Intent nick to use (required) |
+| `--port <port>` | Port to listen on (default: 4000) |
+| `--url <url>` | Public URL for registration and AgentCard (e.g. from ngrok) |
+| `--openclaw-port <port>` | OpenClaw gateway port (default: 18789) |
+| `--openclaw-token <token>` | OpenClaw gateway auth token (or `OPENCLAW_GATEWAY_TOKEN`) |
+| `--openclaw-agent <id>` | OpenClaw agent ID to target (default: `main`) |
+| `--client-id <id>` | Developer app client ID (or `W42_CLIENT_ID`) |
+| `--client-secret <secret>` | Developer app client secret (or `W42_CLIENT_SECRET`) |
+| `--visibility <vis>` | Marketplace visibility: `public` or `private` |
+| `--verbose` | Enable verbose request/response logging |
+
+Requires an `agent-card.json` in the current directory with at least a `name` field.
 
-#### `web42 pay sign create`
+---
 
-Create a payment session for human approval (when no matching intent exists).
+### `w42 register <url>`
+
+Register an agent with the Web42 Network. The URL must serve `/.well-known/agent-card.json`.
 
 ```bash
-web42 pay sign create --cart '<json>' --agent @x~bookstore
+w42 register https://my-agent.example.com
+w42 register https://my-agent.example.com --tags "nlp,summarization"
 ```
 
 | Option | Description |
 |---|---|
-| `--cart <json>` | CartMandate JSON (required) |
-| `--agent <slug>` | Merchant agent slug (required) |
+| `--tags <tags>` | Comma-separated discovery tags |
+| `--categories <cats>` | Comma-separated categories |
 
-Returns `{ code, signing_url }`. Present the URL to the user.
+---
 
-#### `web42 pay sign get <code>`
+### `w42 telemetry`
 
-Check the status of a payment session.
+Control usage telemetry.
 
 ```bash
-web42 pay sign get a1b2c3d4e5f6g7h8
+w42 telemetry         # Show current state
+w42 telemetry on      # Enable
+w42 telemetry off     # Disable
 ```
 
 ---
 
-### `web42 telemetry`
+## AP2 Payment flow
 
-Control usage telemetry.
+The full end-to-end flow for session-based (human approval) payments:
 
-```bash
-web42 telemetry         # Show current state
-web42 telemetry on      # Enable
-web42 telemetry off     # Disable
+```
+1. w42 send @merchant/agent "I want to buy X"
+   → Agent sends back a CartMandate
+   → CLI auto-saves it as tx_xxx, prints next step
+
+2. w42 cart sign tx_xxx
+   → Creates a payment session, returns signing_url
+   → User opens the URL and approves in the browser
+
+3. w42 cart poll tx_xxx
+   → Polls until status = "completed"
+   → Stores the full PaymentMandate on tx_xxx
+
+4. w42 send @merchant/agent "paid" --pay tx_xxx
+   → Sends the PaymentMandate to the merchant agent
+```
+
+For intent-based (automatic) payments, replace steps 2–3 with:
+
+```
+2. w42 cart checkout tx_xxx --intent <nick>
+   → Charges the saved card, stores PaymentMandate immediately
 ```
 
 ---

package/dist/commands/auth.js

@@ -59,7 +59,8 @@ authCommand
     }
     catch (error) {
         spinner.fail("Failed to start auth flow");
-        console.error(error);
+        console.error(chalk.red(String(error)));
+        console.error(chalk.dim("Check your network connection and try again."));
         process.exit(1);
     }
 });

package/dist/commands/cart.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const cartCommand: Command;

package/dist/commands/cart.js

@@ -0,0 +1,219 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import ora from "ora";
+import { ApiError, apiGet, apiPost, hintForError } from "../utils/api.js";
+import { requireAuth, setConfigValue } from "../utils/config.js";
+import { getTx, listTxs, updateTx } from "../utils/tx-store.js";
+function handleIntentError(err, intentNick) {
+    const code = err instanceof ApiError ? err.code : undefined;
+    const msg = err instanceof Error ? err.message : String(err);
+    switch (code) {
+        case "INTENT_NOT_FOUND":
+            setConfigValue(`intents.${intentNick}`, "");
+            console.error(chalk.red(`Intent "${intentNick}" not found.`));
+            console.error(chalk.dim(`Run \`w42 intent list\` to see available intents.`));
+            break;
+        case "INTENT_INACTIVE":
+        case "INTENT_EXPIRED":
+        case "INTENT_BUDGET_EXHAUSTED":
+            setConfigValue(`intents.${intentNick}`, "");
+            console.error(chalk.red(`Intent "${intentNick}" is no longer valid: ${msg}`));
+            console.error(chalk.dim(`Run \`w42 intent list\` to see available intents.`));
+            break;
+        case "INTENT_PERIOD_BUDGET_EXHAUSTED":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            console.error(chalk.dim(`Try again later or run \`w42 intent list\` to find another intent.`));
+            break;
+        case "INTENT_AMOUNT_EXCEEDED":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            console.error(chalk.dim(`Use \`w42 cart sign\` for manual approval instead.`));
+            break;
+        case "INTENT_AGENT_NOT_AUTHORIZED":
+            console.error(chalk.red(`Intent "${intentNick}" does not cover this merchant.`));
+            console.error(chalk.dim(`Use \`w42 cart sign\` for manual approval instead.`));
+            break;
+        case "INTENT_CURRENCY_MISMATCH":
+            console.error(chalk.red(`Intent "${intentNick}": ${msg}`));
+            break;
+        default:
+            console.error(chalk.red(`Checkout failed: ${msg}`));
+    }
+    process.exit(1);
+}
+export const cartCommand = new Command("cart").description("Manage AP2 cart payments — sign, poll, checkout, and list");
+// ─── sign ─────────────────────────────────────────────────
+cartCommand
+    .command("sign")
+    .description("Create a payment session for human approval")
+    .argument("<tx_id>", "Transaction ID from tx-store")
+    .action(async (txId) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    // Check that the cart supports WEB42_WALLET payment method
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const methodData = pr?.method_data;
+        const supportsWeb42 = methodData?.some((m) => m.supported_methods === "WEB42_WALLET");
+        if (!supportsWeb42) {
+            console.error(chalk.yellow(`⚠ This cart does not accept Web42 Wallet as a payment method.\n` +
+                `  Tell your shopping agent: "I cannot pay with Web42 Wallet — ` +
+                `please ask the user how they would like to proceed."`));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(chalk.red("Could not read payment method data from cart"));
+        process.exit(1);
+    }
+    // Extract total from stored cart
+    let totalCents = 0;
+    let currency = "usd";
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const details = pr?.details;
+        const total = details?.total;
+        totalCents = Math.round(total.amount.value * 100);
+        currency = total.amount.currency.toLowerCase();
+    }
+    catch {
+        console.error(chalk.red("Could not extract total from stored cart"));
+        process.exit(1);
+    }
+    const spinner = ora("Creating payment session...").start();
+    try {
+        const res = await apiPost("/api/pay/session", {
+            agent_slug: tx.agentSlug,
+            cart: tx.cartMandate,
+            total_cents: totalCents,
+            currency,
+        });
+        spinner.stop();
+        updateTx(txId, {
+            sessionCode: res.code,
+            signingUrl: res.signing_url,
+            status: "session_created",
+        });
+        console.log(JSON.stringify({ tx: txId, signing_url: res.signing_url }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to create session");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+// ─── poll ─────────────────────────────────────────────────
+cartCommand
+    .command("poll")
+    .description("Check the status of a payment session")
+    .argument("<tx_id>", "Transaction ID")
+    .action(async (txId) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    if (!tx.sessionCode) {
+        console.error(chalk.red(`No session created yet. Run: w42 cart sign ${txId}`));
+        process.exit(1);
+    }
+    const spinner = ora("Fetching session...").start();
+    try {
+        const res = await apiGet(`/api/pay/session/${encodeURIComponent(tx.sessionCode)}`);
+        spinner.stop();
+        if (res.status === "completed" && res.payment_mandate) {
+            updateTx(txId, {
+                paymentMandate: res.payment_mandate,
+                status: "approved",
+            });
+        }
+        console.log(JSON.stringify({ tx: txId, ...res }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Failed to fetch session");
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim(hintForError(err)));
+        process.exit(1);
+    }
+});
+// ─── checkout ─────────────────────────────────────────────
+cartCommand
+    .command("checkout")
+    .description("Execute a payment against a matching intent (no human needed)")
+    .argument("<tx_id>", "Transaction ID from tx-store")
+    .requiredOption("--intent <nick>", "Intent nick to use")
+    .action(async (txId, opts) => {
+    requireAuth();
+    const tx = getTx(txId);
+    if (!tx) {
+        console.error(chalk.red(`Transaction ${txId} not found. Run: w42 cart list`));
+        process.exit(1);
+    }
+    // Check that the cart supports WEB42_WALLET payment method
+    try {
+        const contents = tx.cartMandate.contents;
+        const pr = contents?.payment_request;
+        const methodData = pr?.method_data;
+        const supportsWeb42 = methodData?.some((m) => m.supported_methods === "WEB42_WALLET");
+        if (!supportsWeb42) {
+            console.error(chalk.yellow(`⚠ This cart does not accept Web42 Wallet as a payment method.\n` +
+                `  Tell your shopping agent: "I cannot pay with Web42 Wallet — ` +
+                `please ask the user how they would like to proceed."`));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(chalk.red("Could not read payment method data from cart"));
+        process.exit(1);
+    }
+    const spinner = ora("Processing checkout...").start();
+    try {
+        const res = await apiPost("/api/pay/checkout", {
+            cart: tx.cartMandate,
+            agent_slug: tx.agentSlug,
+            intent_nick: opts.intent,
+        });
+        spinner.stop();
+        if (res.payment_mandate) {
+            updateTx(txId, {
+                paymentMandate: res.payment_mandate,
+                status: "approved",
+            });
+        }
+        console.log(JSON.stringify({ tx: txId, ...res }, null, 2));
+    }
+    catch (err) {
+        spinner.fail("Checkout failed");
+        handleIntentError(err, opts.intent);
+    }
+});
+// ─── list ─────────────────────────────────────────────────
+cartCommand
+    .command("list")
+    .description("List local payment transactions")
+    .option("--status <status>", "Filter by status (cart_received, session_created, approved, sent)")
+    .action((opts) => {
+    const txs = listTxs(opts.status);
+    if (txs.length === 0) {
+        console.log(chalk.dim("No transactions found."));
+        return;
+    }
+    for (const tx of txs) {
+        const cart = tx.cartMandate;
+        const contents = cart?.contents;
+        const pr = contents?.payment_request;
+        const details = pr?.details;
+        const total = details?.total;
+        const amount = total?.amount
+            ? `${total.amount.currency} ${total.amount.value?.toFixed(2)}`
+            : "?";
+        console.log(`${chalk.cyan(tx.id)}  ${chalk.dim(tx.status.padEnd(16))}  ${amount}  ${chalk.dim(tx.agentSlug)}`);
+    }
+});

package/dist/commands/intent.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const intentCommand: Command;