@itpay/cli 2.0.3 → 2.0.7

package/README.md

@@ -1,152 +1,106 @@
 # ItPay CLI
 
-The V3 terminal and agent-facing CLI for ItPay commerce.
+The official V3 CLI for Agent-driven ItPay service discovery, checkout, delivery, order recovery, and refunds.
 
 ```bash
 npm install -g @itpay/cli
-itpay readyz
-itpay docs show quickstart
+itpay readyz --json
+itpay skill show itpay-buyer --json
+itpay install --json
+itpay --agent-type codex-desktop readyz --json
+# follow next.command: typed skill show, then catalog list
 ```
 
-The CLI defaults to the production app at `https://app.itpay.ai`. Set
-`ITPAY_BACKEND_URL` only when intentionally using another backend.
-
-## Commands
-
-- `itpay readyz` — `GET /v1/readyz`
-- `itpay next [--json]` — show the next recommended agent action from remembered server handles
-- `itpay cart add --item <id> --variant <id> --offer <id> [--quantity 1] [--input <json>] [--host <host>] [--json]` — create/update the canonical server cart; service-backed lines return `service_execution_id`
-- `itpay cart next [--json]` — show the next recommended action for the remembered canonical server cart
-- `itpay cart add --local ...` — explicit local draft compatibility mode only, not valid for service-backed flows
-- `itpay cart remove --line <cart_item_id>` — soft-remove an active line from the canonical server cart; quote-locked or checkout-bound lines are rejected
-- `itpay cart remove --local --variant <id> --offer <id>` — drop a local draft line
-- `itpay cart show` — print the canonical server cart, or local draft fallback when no server cart handle exists
-- `itpay cart clear` — abandon the canonical server cart and clear local handles
-- `itpay cart clear --local` — clear local handles/draft only
-- `itpay buy --cart <cart_id> --host <host> [--target <target>] [--qr-format ...] [--qr-file <path>]` — create checkout from a canonical server cart and render the branded checkout QR for the host
-- `itpay buy --host <host> [--target <target>] [--item ... --variant ... --offer ...] [--quantity 1]` — compatibility one-shot cart + checkout path
-- `itpay services start <service_id>` — start a generic Service Execution run
-- `itpay services invoke <service_execution_id> --capability <capability_id> --input key=value` — invoke an agent-visible capability
-- `itpay services action <service_execution_id> --action <action_type> [--result-item <id>]` — record a human/agent service action
-- `itpay services checkout <service_execution_id> --capability <capability_id> [--email <email>] [--host <host>] [--json]` — create quote lock from Service Execution state, require email only for capabilities that deliver a claim link, persist the handoff, and render the branded ItPay checkout
-- `itpay services checkout <service_execution_id> --resume --json` — reissue a lost or expired handoff for the same unpaid checkout without asking for contact information again
-- `itpay services next <service_execution_id> [--json]` — show the next recommended action from the Service Execution read model
-- `itpay services get <service_execution_id>` / `itpay services events <service_execution_id>` — read the redacted Service Execution timeline
-- `itpay checkout --id <checkout_id> --token <display_token>` — read canonical checkout presentation
-- `itpay pay --checkout <id> --method alipay|wechatpay` — CLI escape hatch for operator/manual testing only; normal buyer flow opens the ItPay checkout page first
-- `itpay order <order_id>` — read one V3 order
-- `itpay orders [--limit 20] [--status <status>]` — list account-scoped orders (requires `ITPAY_BEARER_TOKEN`)
-- `itpay refund --order <id> [--reason <reason>]` — request a refund with an account-scoped `ITPAY_BEARER_TOKEN`; payment and amount are derived by the backend
-
-## Hosts
-
-The CLI dispatches to a per-host renderer based on `--host`:
-
-| `--host` | Renderer | Native UI |
-| --- | --- | --- |
-| `terminal` | `render/terminal.ts` | terminal QR + summary |
-| `codex`, `claude-code` | `render/markdown.ts` | markdown image + links |
-| `telegram` | `render/telegram.ts` | openclaw `message send` with inline buttons |
-| `feishu`, `lark` | `render/feishu.ts` | Feishu/Lark interactive card (url + callback) |
-| `discord`, `whatsapp`, `plain-chat` | `render/plain_chat.ts` | text + links, no native buttons |
-
-Aliases: `tg` and `openclaw-telegram` map to `telegram`; `feishu_im` and `fs` map to `feishu`.
+The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional test or local environment.
+
+## Output Contract
+
+Normal JSON commands return one bounded envelope:
+
+```text
+status      current command state
+result      facts needed at this step
+handoff     optional human-visible URL/image fields for the current Host
+instruction how the Agent must use the result
+next        zero or one preferred executable command
+recovery    exceptional recovery commands only
+```
+
+Run `next.command` unchanged after filling only explicit placeholders or user-provided required fields. Do not inspect raw APIs or hardcode a service workflow.
+
+Normative per-command contracts: [CLI Command Reference](docs/cli-reference/index.md).
+
+## Supported Agent Types
+
+| Agent Type | Default Host |
+| --- | --- |
+| `codex-desktop` | `codex` |
+| `codex-cli` | `terminal` |
+| `claude-code-desktop` | `claude-code` |
+| `claude-code-cli` | `terminal` |
+| `workbuddy` | `plain-chat` |
+
+`--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
+
+The local installation keeps one Ed25519 private key. Each normalized Backend API base URL (`dev`, `test`, `app`, or local) has an independent server device registration, quota lineage, Agent instances, and sessions. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
+
+## Command Families
+
+- `readyz`, `catalog list`: compatibility and discovery.
+- `services start/invoke/action/checkout/next`: generic Service Execution flow.
+- `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
+- `checkout`: authoritative payment and fulfillment recovery.
+- `services read-result`: read one human-granted protected result.
+- `order`, `orders`: exact order and account order views.
+- `refund create/list/get/watch/cancel`: Refund Owner flow.
+- `services get/events`: redacted support diagnostics; normal flows should use `services next`.
+- `install`, `skill show`, `docs list/show/search`: offline packaged guidance.
+- `pay`: operator escape hatch only; normal buyers use the ItPay Checkout page.
+
+Run `itpay <command> --help` or browse [the command index](docs/cli-reference/index.md) for parameters.
+
+## Recovery
+
+Use server-backed recovery before creating another resource:
+
+```bash
+itpay --agent-type <agent_type> next --json
+itpay --agent-type <agent_type> services list --json
+itpay --agent-type <agent_type> services next <service_execution_id> --json
+itpay --agent-type <agent_type> services checkout <service_execution_id> --resume --json
+itpay checkout --id <checkout_id> --token <display_token> --json
+```
+
+The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 
-- `ITPAY_BACKEND_URL` — optional backend override (default `https://app.itpay.ai`)
-- `ITPAY_BEARER_TOKEN` — account-scoped session token (only needed for `orders`)
-- `ITPAY_AGENT_DEVICE_ID` — agent device id, used for cart/service execution quota identity and `client_context`
-- `ITPAY_CURRENCY` — checkout currency (default `CNY`)
-- `ITPAY_IDEMPOTENCY_KEY` — `Idempotency-Key` for pay/refund requests (auto-generated if unset)
-- `ITPAY_IDE_IMAGE_ATTACH` — set to `0` to disable the IDE image-attach contract (e.g. read-only runner FS). Default `1`.
-- `ITPAY_IDE_IMAGE_DIR_OVERRIDE` — override the canonical IDE image directory instead of `$TMPDIR/itpay-v3-qr`. Useful when the IDE file panel only knows one path.
-
-## Agent next actions
-
-Service-backed flows return progressive guidance for agents:
-
-- `itpay cart add --json`, `itpay services start`, `itpay services invoke`,
-  `itpay services action`, `itpay services get`, and
-  `itpay services checkout --json` include top-level `next_actions`.
-- `itpay next`, `itpay cart next`, and `itpay services next <id>` print only
-  the next recommended command and recovery commands.
-- The guidance is derived from server cart and Service Execution read models.
-  Local `~/.itpay-v3/cart.json` only stores handles such as `cart_id`,
-  `service_execution_id`, `checkout_id`, and `display_token`.
-
-Agents should prefer `next_actions` over hardcoded service-specific flows.
-For example, a service-backed cart add can return an invoke command for an
-agent-visible free capability, while a quote-locked execution can return the
-checkout handoff command.
-
-## IDE image attach
-
-Every `itpay buy`, `itpay services checkout` (and `itpay checkout`,
-`itpay order`) downloads the
-brand checkout QR from the backend and writes it to a stable local
-file the agent can hand to the IDE image viewer (Trae `Read` tool,
-Codex, Claude Code). The contract is:
-
-- canonical file: `<os.tmpdir()>/itpay-v3-qr/itpay-v3-<kind>-<id>.png`
-  (override with `ITPAY_IDE_IMAGE_DIR_OVERRIDE`)
-- when `/tmp/itpay-v3-qr` is a separate, writable location it gets a
-  mirror of the same file under the same name
-- filename is stable per checkout, so re-runs overwrite the same
-  local file rather than scattering copies across the scratch dir
-
-Outputs that carry the IDE image attach:
-
-- `itpay buy --json` — fields `brand_qr_local_path`, `brand_qr_mirrors`,
-  `brand_qr_stable_name`, `brand_qr_status` (`downloaded` / `failed`
-  / `disabled` / `fallback`), `brand_qr_error`, `brand_qr_data_url`,
-  `brand_qr_must_render_reason`, `brand_qr_render_action`. Read the
-  path with the IDE's `Read` tool so the human sees the picture.
-- `itpay services checkout --json` — same brand QR fields, plus
-  `next_action: "open_human_checkout"` and the checkout-scoped
-  `display_token`. Agents must show this ItPay checkout QR/URL to the
-  human and must not call `itpay pay` for the normal buyer flow.
-- Markdown (Trae / Codex / Claude Code) — inlines a `data:image/png;base64,...`
-  copy of the picture plus a `[ATTACH] IDE image` reference block that
-  points at the canonical local path and mirrors.
-- Terminal — prints `Branded QR: /path/...png` and `QR mirrors: ...`;
-  iTerm inline image renders the same file when the session supports it.
-- Telegram — the `ide_image_attach` block on `presentation.ide_image_attach`
-  carries `status`, `local_path`, `mirrors`, `mime_type`, `source`,
-  `caption`, `error` (when failed), `must_render_reason`, and a
-  step-by-step `instructions` array.
-- Feishu / Lark — same `ide_image_attach` block on the
-  `message.ide_image_attach` envelope.
-
-Disable the contract with `ITPAY_IDE_IMAGE_ATTACH=0` for runners on a
-read-only filesystem. The plan carries `status: "disabled"` instead
-of `status: "downloaded"` and no PNG is downloaded.
-
-## Layout
-
-- `src/main.ts` — `commander` entrypoint, command registration
-- `src/client/` — HTTP/JSON client and DTOs
-- `src/commands/` — one file per command family
-- `src/render/` — terminal formatting
-  - `plan.ts` — `RenderPlan` contract shared by all renderers
-  - `qr.ts` — local QR + format selection
-  - `terminal.ts`, `markdown.ts`, `plain_chat.ts`, `telegram.ts`, `feishu.ts` — per-host renderers
-  - `index.ts` — `dispatchRender()` picks the right renderer
-  - `sink.ts` — `OutputSink` so tests can silence stdout
-- `src/state/` — local CLI config, cart session, client context
-- `tests/` — node:test smoke test + in-process mock backend
-
-## Rules
-
-- commands orchestrate user intent only
-- render code must not issue HTTP calls
-- keep API access under `src/client/`
-- persist checkout-scoped `display_token` and last server handles only in the owner-only local cart session file
-- the default `buy` command must not create a payment intent unless `--pay` is explicit
-- the default `services checkout` command must render the ItPay
-  checkout handoff; provider payment intents are created by the human
-  checkout page, not by the agent
-- a renderer must consume the brand QR the V3 backend hands back
-  (`qr_payload` / `qr_png_url` / `mobile_wallet_url`) and only
-  self-generate a QR for `auth_qr` / `checkout_qr` with the explicit
-  `--qr-file` opt-in
+- `ITPAY_BACKEND_URL`: deliberate API override.
+- `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
+- `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
+- `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
+- `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.
+- `ITPAY_IDEMPOTENCY_KEY`: explicit operation key for deterministic testing; normal use persists operation IDs automatically.
+- `ITPAY_IDE_IMAGE_ATTACH=0`: disable local Checkout image download when the runtime filesystem is read-only.
+- `ITPAY_IDE_IMAGE_DIR_OVERRIDE`: override the local Checkout image directory.
+
+Provider credentials, Buyer identity, payment provider choice, amount, refund policy, quota, grant scope, and delivery access are never client-owned environment settings.
+
+## Development
+
+```bash
+npm run lint
+npm test
+npm run test:package
+npm run pack:dry-run
+```
+
+Source boundaries:
+
+- `src/main.ts`: parser and error-envelope wiring.
+- `src/client`: typed HTTP access.
+- `src/commands`: command orchestration and public output projection.
+- `src/render`: Host presentation only; no business HTTP.
+- `src/state`: local Device Authority, idempotency journal, and recovery handles.
+- `docs/cli-reference`: normative command contracts.
+- `docs/agent/buyer`: packaged progressive workflow guidance.

package/dist/src/client/backend.js

@@ -32,17 +32,16 @@ export class BackendClient {
         return this.http.delete(`/v1/carts/${encodeURIComponent(cartID)}`);
     }
     // --- Checkout ---
-    createCheckout(input) {
-        return this.http.post("/v1/checkouts", input);
+    createCheckout(input, idempotencyKey) {
+        return this.http.post("/v1/checkouts", input, idempotencyKey ? { idempotencyKey } : undefined);
     }
     getCheckoutPresentation(checkoutID, displayToken) {
         const qs = new URLSearchParams({ display_token: displayToken });
         return this.http.get(`/v1/checkouts/${encodeURIComponent(checkoutID)}/presentation?${qs}`);
     }
     // --- Payment intents ---
-    createPaymentIntent(checkoutID, input, idempotencyKey) {
-        const options = idempotencyKey ? { idempotencyKey } : {};
-        return this.http.post(`/v1/checkouts/${encodeURIComponent(checkoutID)}/payment-intents`, input, options);
+    createPaymentIntent(checkoutID, input) {
+        return this.http.post(`/v1/checkouts/${encodeURIComponent(checkoutID)}/payment-intents`, input);
     }
     // --- SSE streaming ---
     streamCheckoutEvents(checkoutID, displayToken, onEvent, signal) {
@@ -54,6 +53,9 @@ export class BackendClient {
     getOrder(orderID) {
         return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}`);
     }
+    getOrderDeliveryAccess(orderID) {
+        return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/delivery-access`);
+    }
     listAccountOrders(limit, status, bearer) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (status) {
@@ -63,9 +65,18 @@ export class BackendClient {
     }
     // --- Refund ---
     createRefund(orderID, input, bearer, idempotencyKey) {
-        const options = { bearer, ...(idempotencyKey ? { idempotencyKey } : {}) };
+        const options = { ...(bearer ? { bearer } : {}), ...(idempotencyKey ? { idempotencyKey } : {}) };
         return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/refunds`, input, options);
     }
+    listOrderRefunds(orderID) {
+        return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/refunds`);
+    }
+    getRefund(refundRequestID) {
+        return this.http.get(`/v1/refunds/${encodeURIComponent(refundRequestID)}`);
+    }
+    cancelRefund(refundRequestID, reason = "buyer_cancelled") {
+        return this.http.post(`/v1/refunds/${encodeURIComponent(refundRequestID)}/cancel`, { reason });
+    }
     // --- Service Execution ---
     startServiceExecution(input) {
         return this.http.post("/v1/service-executions", input);
@@ -79,14 +90,21 @@ export class BackendClient {
     createServiceExecutionCheckout(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/checkout`, input);
     }
+    prepareServiceQuote(serviceExecutionID, input) {
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input);
+    }
     getServiceExecution(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);
     }
     listServiceExecutions(limit = 50) {
         return this.http.get(`/v1/service-executions?limit=${limit}`);
     }
-    listServiceExecutionEvents(serviceExecutionID) {
-        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/events`);
+    listServiceExecutionEvents(serviceExecutionID, afterSequence = 0, limit = 50) {
+        const query = new URLSearchParams({
+            after_sequence: String(afterSequence),
+            limit: String(limit),
+        });
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/events?${query}`);
     }
     getGrantedServiceResult(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/granted-result`);

package/dist/src/client/http.js

@@ -17,6 +17,7 @@ export class HttpClient {
     fetchImpl;
     defaultHeaders;
     requestAuthorizer;
+    recoverAuthorization;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, "");
         this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
@@ -26,35 +27,40 @@ export class HttpClient {
             ...(config.defaultHeaders ?? {}),
         };
         this.requestAuthorizer = config.requestAuthorizer;
+        this.recoverAuthorization = config.recoverAuthorization;
     }
     async request(path, options = {}) {
         const url = path.startsWith("http") ? path : this.baseURL + path;
-        const headers = { ...this.defaultHeaders };
         const method = options.method ?? "GET";
         const body = options.body !== undefined ? JSON.stringify(options.body) : "";
-        if (this.requestAuthorizer) {
-            Object.assign(headers, await this.requestAuthorizer({ method, path: new URL(url).pathname + new URL(url).search, body }));
+        const requestPath = new URL(url).pathname + new URL(url).search;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const headers = { ...this.defaultHeaders };
+            if (this.requestAuthorizer) {
+                Object.assign(headers, await this.requestAuthorizer({ method, path: requestPath, body }));
+            }
+            if (options.bearer)
+                headers.Authorization = `Bearer ${options.bearer}`;
+            if (options.idempotencyKey)
+                headers["Idempotency-Key"] = options.idempotencyKey;
+            const response = await this.fetchImpl(url, {
+                method,
+                headers,
+                ...(options.body !== undefined ? { body } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            const text = await response.text();
+            const parsed = text.length > 0 ? safeParseJson(text) : undefined;
+            if (response.ok)
+                return parsed;
+            const error = new HttpError(response.status, parsed, `HTTP ${response.status}`);
+            if (attempt === 0 && error.status === 401 && error.code === "agent_device_session_required" && this.recoverAuthorization) {
+                await this.recoverAuthorization();
+                continue;
+            }
+            throw error;
         }
-        if (options.bearer) {
-            headers.Authorization = `Bearer ${options.bearer}`;
-        }
-        if (options.idempotencyKey) {
-            headers["Idempotency-Key"] = options.idempotencyKey;
-        }
-        const requestInit = {
-            method,
-            headers,
-            ...(options.body !== undefined ? { body } : {}),
-            ...(options.signal ? { signal: options.signal } : {}),
-        };
-        const response = await this.fetchImpl(url, requestInit);
-        const text = await response.text();
-        const parsed = text.length > 0 ? safeParseJson(text) : undefined;
-        if (!response.ok) {
-            const errPayload = parsed;
-            throw new HttpError(response.status, errPayload, `HTTP ${response.status}`);
-        }
-        return parsed;
+        throw new Error("unreachable HTTP retry state");
     }
     get(path, options = {}) {
         return this.request(path, { ...options, method: "GET" });