@visa/cli 5.0.0-rc.337 → 5.0.0-rc.339

package/README.md

@@ -20,11 +20,71 @@ The protected product flow has three explicit parts:
 3. **Use** — `visa pay` and the `pay` tool enforce that authority's own policy
    and approval boundary on every call.
 
-Card payment is unavailable in this build: a `pay` target that answers no 402
-challenge refuses with `card_browser_checkout_removed`, even with a saved card,
-grant or tester flag. Another enrollment or card grant will not enable payment.
-UCP discovery and checkout preparation do not prove Visa payment support.
-Preserve the existing merchant checkout for the owner to continue with the merchant.
+## Protected card purchase preview
+
+This is an explicit gated preview exception to the eight general commands and six general tools. It does not change the general `pay` URL dispatcher. The `capabilities.capabilities.card.preview` block returned by `get_status` separates callable tools and the selected protected device proof; current authority is checked per purchase, and live payment readiness remains unverified.
+
+For the initial **Codex + local MCP on your own device** cohort, builds that list
+`purchase_create`, `purchase_retrieve`, and `purchase_cancel` expose one protected
+purchase resource. Preview access still requires the current owner eligibility,
+verified card, device, spending limits and disclosure approval. Tool presence is
+not evidence of live merchant compatibility; `card.available` remains false until
+launch acceptance. Hosted MCP does not expose this device-bound path yet.
+
+```bash
+visa purchase create --request checkout.json
+visa purchase create --resume <resume-id>
+visa purchase retrieve <purchase-id>
+visa purchase retrieve <purchase-id> --include card
+visa purchase cancel <purchase-id>
+```
+
+`checkout.json` contains `merchantCountryCode` and the exact final
+`terms` described in the [purchase guide](https://app.visacli.sh/docs/protected-card-purchases).
+Fixed protocol fields and `requestKey` are optional; the client fills them deterministically. Before setup, create saves the exact nonsecret request and returns a durable `resumeId`.
+Resume with `visa purchase create --resume <resume-id>` or MCP `purchase_create {resumeId}`; the original file or stdin is no longer needed. The reference stays bound to the selected owner and agent. Repeating the unchanged request also resumes it. Never put funding-card details in this file. Use `--agent <existing-agent-id>` when selection is ambiguous.
+
+Create reuses the existing protected identity and card. A fresh user gets the
+existing owner ceremony; an existing agent gets only missing card/device approval.
+An expired identity setup link does not require re-enrollment. Follow the single
+`next` action: show `open_url` to the owner, wait for a bounded `retry`, or explicitly
+retrieve the issued card when instructed. CLI `next.argv` is an argument array,
+not shell source; execute it as argv without concatenating it into a command.
+
+Ordinary reads contain no card credential. **`--include card` / `include:"card"`
+explicitly returns issued purchase credentials to stdout or the MCP tool result,
+which may enter agent/chat history.** The owner must consent to that disclosure.
+Original funding-card details and native signing keys are never returned. A
+cryptogram is not a generic CVC; the host must establish actual merchant support.
+
+On macOS/Linux, a host with access to the same filesystem can add `--delivery file`
+(MCP: `delivery:"file"`) to the explicit card read. The result returns only
+`credentialFile.path` and ordinary status; the issued credential is saved in a new
+owner-only directory under `~/.visa-cli/purchase-deliveries` (or `VISA_CLI_HOME`).
+Remove the file after use with `visa purchase clear-files --all`. New file deliveries also sweep earlier files past their cryptogram expiry or a 24-hour local retention cap. No background cleanup runs while the CLI is closed. This still requires `agent_history` consent; reading it
+into the model can expose it to history. Windows file delivery refuses, hosted
+MCP cannot consume this local path, and write failures never fall back to stdout.
+Retry the same purchase and delivery option after fixing storage.
+
+Before merchant submission, call `purchase_retrieve` with `observed:"submission_started"`
+(CLI: `visa purchase retrieve <purchase-id> --observed submission_started`). Report a
+challenge as `buyer_action_required`, an order response as `order_reported`, or a
+failed/interrupted submission as `submission_failed`. Keep the same host checkout:
+`check_checkout` never means click Pay again. Reports cannot settle or release
+funds; a reported order remains unverified. After any report, further credential
+reads are refused. Do not combine `observed` with `include:"card"`.
+
+The host owns discovery, cart, browser and submission. UCP is optional preparation
+or a verified compatible payment path. Issuance is not proof of payment. Preserve
+the purchase ID after interruption; cancellation cannot release issued or uncertain
+liability. Hosted parity and the live canary remain tracked under [#9367](https://github.com/Visa-Crypto-Labs/Visa-mono/issues/9367).
+
+Public SDK packaging is deferred until an integrator needs direct TypeScript access.
+CLI and local MCP already use one shared purchasing client.
+
+A cold local MCP process can list and call protected enrollment/purchase tools
+without an employee RC code. Other RC tools, private resources and Tasks retain
+their access checks; purchase authority still comes from owner approval.
 
 ## Install
 
@@ -99,7 +159,7 @@ The server now exposes:
 - JSON Schema 2020-12 tool inputs and outputs, `structuredContent`, namespaced result metadata, cache hints, and receipt `resource_link` blocks.
 - Resources for agent status, capabilities, recent activity, and canonical `visa://receipt/{transactionId}` receipts.
 - Prompts for pairing/funding, spend inspection, safe purchasing, and receipt reconciliation, with completion support.
-- The `io.modelcontextprotocol/tasks` extension. Its presence does not make card payment available: a card checkout refuses before creating approval work.
+- The `io.modelcontextprotocol/tasks` extension. Its presence does not make card payment available: `pay_merchant` refuses before creating approval work.
 - Multi-round-trip `input_required` URL elicitation with HMAC-protected, client-bound request state when the client supports URL elicitation but not Tasks.
 - The `io.modelcontextprotocol/ui` Visa Control Center MCP App at `ui://visa/control-center`.
 
@@ -205,7 +265,7 @@ is required, so the CLI never guesses which agent may spend.
 
 ## MCP tools (v4 surface)
 
-Six tools are served. There used to be thirty-five, which is more names than
+Six general tools plus three protected-device preview tools are served to RC-authorized runtimes. Cold runtimes can list and call get_status, agent_enroll and the purchase preview without an employee code; protected owner rollout and authority still apply. There used to be thirty-five, which is more names than
 anyone can hold, and most of them existed because a ceremony needed a door
 rather than because an agent needed a verb.
 
@@ -221,6 +281,9 @@ a name that was ever real has to stay readable here.
 | `discover` | Find something to pay for. Takes search text, or one listing to read its live challenge without paying |
 | `pay` | Pay. The RAIL COMES FROM THE TARGET: search text searches, a listing id pays over the wallet, a payment-gated URL pays over whichever rail its challenge asks for |
 | `history` | Receipts, across every rail, with reconciliation when a payment's outcome is unresolved |
+| `purchase_create` | Gated device preview: create/resume exact checkout using existing owner setup |
+| `purchase_retrieve` | Preview: ordinary status, bounded host observation, or explicit include:card credential delivery |
+| `purchase_cancel` | Preview: stop further work; issued or uncertain liability remains |
 | `feedback` | Send feedback on a tool result, with the owner's explicit confirmation |
 | `agent_capabilities` | **Removed.** Its capability map is a block of `get_status` |
 | `agent_login` | **Removed.** `agent_enroll` runs the sign-in leg when that is the one owed |