@itpay/cli 2.0.0 → 2.0.2

package/README.md

@@ -8,7 +8,7 @@ itpay readyz
 itpay docs show quickstart
 ```
 
-This test release defaults to `https://test.itpay.ai`. Set
+The CLI defaults to the production API at `https://api.itpay.ai`. Set
 `ITPAY_BACKEND_URL` only when intentionally using another backend.
 
 ## Commands
@@ -28,7 +28,7 @@ This test release defaults to `https://test.itpay.ai`. Set
 - `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, bind it to the server cart item when present, persist the handoff, and render the branded ItPay checkout
+- `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
@@ -54,7 +54,7 @@ Aliases: `tg` and `openclaw-telegram` map to `telegram`; `feishu_im` and `fs` ma
 
 ## Environment
 
-- `ITPAY_BACKEND_URL` — optional backend override (test-release default `https://test.itpay.ai`)
+- `ITPAY_BACKEND_URL` — optional backend override (default `https://api.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`)

package/dist/src/commands/catalog.js

@@ -1,4 +1,3 @@
-import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
 export async function runCatalogList(backend, options = {}) {
     const manifest = await backend.getCatalogManifest();
@@ -8,19 +7,46 @@ export async function runCatalogList(backend, options = {}) {
         out(JSON.stringify(manifest, null, 2) + "\n");
         return;
     }
-    out(`Catalog: ${manifest.version} (${manifest.status}, ${items.length} items)\n\n`);
+    out(`ItPay 当前上线 ${items.length} 个服务（目录版本 ${manifest.version}）\n\n`);
     for (const item of items) {
-        out(`  ${item.catalog_item_id}\n`);
-        out(`    title:    ${item.title}\n`);
-        out(`    provider: ${item.provider} | type: ${item.service_type} | category: ${item.category}\n`);
+        out(`  ${item.title}\n`);
+        if (item.description)
+            out(`    ${item.description}\n`);
+        if (item.service_flow) {
+            const discovery = item.service_flow.discovery;
+            const primary = item.service_flow.primary_service;
+            out(`\n    先做什么：${discovery.title}\n`);
+            out(`    ${discovery.description}\n`);
+            if (discovery.free_quota_limit !== undefined) {
+                out(`    每台已登记设备可免费使用 ${discovery.free_quota_limit} 次。\n`);
+            }
+            if (discovery.paid_continuation) {
+                const continuation = discovery.paid_continuation;
+                out(`    免费次数用完后：${formatProductMoney(continuation.amount_minor, continuation.currency)}/次，继续使用该辅助步骤；结果直接返回给 agent${continuation.delivery_email_required ? "，需要用户提供收件邮箱" : "，不需要邮箱"}。\n`);
+            }
+            out(`\n    确认主体后：${primary.title}，${formatProductMoney(primary.amount_minor, primary.currency)}/次\n`);
+            out(`    ${primary.description}\n`);
+            if (primary.delivery_description)
+                out(`    ${primary.delivery_description}\n`);
+        }
+        out(`\n    服务 ID：${item.service_id ?? "未发布"}`);
         if (item.service_id)
-            out(`    service:  ${item.service_id} (use: itpay services start ${item.service_id})\n`);
+            out(`（启动：itpay services start ${item.service_id}）`);
+        out("\n");
         if (item.variants.length > 0) {
-            out(`    variants:\n`);
+            out(`    可购买项目：\n`);
             for (const variant of item.variants) {
-                out(`      - ${variant.catalog_variant_id}  ${variant.title}  ${variant.offer_id}  ${formatMoney(variant.amount_minor, variant.currency)}\n`);
+                out(`      - ${variant.catalog_variant_id}  ${variant.title}  ${variant.offer_id}  ${formatProductMoney(variant.amount_minor, variant.currency)}\n`);
             }
         }
         out("\n");
     }
 }
+function formatProductMoney(amountMinor, currency) {
+    return new Intl.NumberFormat("zh-CN", {
+        style: "currency",
+        currency,
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    }).format(amountMinor / 100);
+}

package/dist/src/commands/guidance.js

@@ -106,9 +106,10 @@ export function buildServiceReadModelGuidance(model) {
         deliveryBindings: model.delivery_bindings,
     });
 }
-export function buildServiceInvokedGuidance(response) {
+export function buildServiceInvokedGuidance(response, capabilities = []) {
     return buildServiceGuidance({
         execution: response.execution,
+        capabilities,
         resultItems: response.result_items,
         ...(response.next_actions ? { backendNextActions: response.next_actions } : {}),
         ...(response.effective_quota ? { effectiveQuota: response.effective_quota } : {}),
@@ -155,9 +156,9 @@ export function buildServiceHandleGuidance(serviceExecutionID, checkoutCapabilit
         actions.push({
             id: "checkout_service",
             label: "Create checkout after human confirmation",
-            command: `itpay services checkout ${serviceExecutionID} --capability ${checkoutCapabilityID} --email <email> --json`,
+            command: `itpay services checkout ${serviceExecutionID} --capability ${checkoutCapabilityID} --json`,
             requires_human: true,
-            reason: "Only use after the service contract has the required human confirmation or quote lock.",
+            reason: "Inspect the Service Execution first; the CLI will request delivery contact only when the selected capability requires it.",
         });
     }
     return {
@@ -306,12 +307,16 @@ function buildServiceGuidance(input) {
     else if (execution.checkout_required || execution.next_action === "create_checkout") {
         const capabilityID = backendCheckout?.capability_id ?? paid?.capability_id ?? input.checkoutCapabilityID ?? execution.current_capability_id;
         if (capabilityID) {
+            const checkoutCapability = capabilities.find((capability) => capability.capability_id === capabilityID);
+            const emailRequired = checkoutCapability?.delivery_email_required === true;
             nextActions.push({
                 id: "checkout_service",
                 label: "Create ItPay checkout for the paid service capability",
-                command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID} --email <email> --json`,
+                command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID}${emailRequired ? " --email <email>" : ""} --json`,
                 requires_human: true,
-                reason: "The human must provide delivery contact and pay on the ItPay checkout page.",
+                reason: emailRequired
+                    ? "Ask the human for their email. It is used to send the protected result claim link; never invent or substitute an address."
+                    : "This capability returns an agent-visible result after payment and does not require a delivery email.",
             });
         }
         else {
@@ -384,6 +389,10 @@ function buildServiceGuidance(input) {
                 capability_id: capability.capability_id,
                 agent_visible: capability.agent_visible,
                 requires_payment: capability.requires_payment,
+                vault_required: capability.vault_required,
+                delivery_email_required: capability.delivery_email_required,
+                price_amount_minor: capability.price_amount_minor,
+                price_currency: capability.price_currency,
                 free_quota_limit: capability.free_quota_limit,
             })),
             result_items: (input.resultItems ?? []).map((item) => ({

package/dist/src/commands/services.js

@@ -27,7 +27,17 @@ export async function runServicesInvoke(backend, config, serviceExecutionID, cap
         idempotency_key: idempotencyKey,
         redacted_summary: input,
     });
-    const guidance = buildServiceInvokedGuidance(response);
+    let capabilities = [];
+    if (response.next_actions?.some((action) => action.kind === "create_checkout")) {
+        try {
+            capabilities = (await backend.getServiceExecution(serviceExecutionID)).capabilities;
+        }
+        catch {
+            // Preserve the successful invocation response. Checkout performs the same
+            // capability-aware email validation before creating a handoff.
+        }
+    }
+    const guidance = buildServiceInvokedGuidance(response, capabilities);
     if (options.jsonOutput) {
         writeJSON(options.output, attachAgentGuidance(response, guidance));
         return;

package/dist/src/main.js

@@ -24,7 +24,7 @@ program
     .name("itpay")
     .description("V3 ItPay CLI — checkout, payment, order, and refund commands")
     .option("--agent-type <type>", "agent runtime type used for device enrollment and client-specific guidance")
-    .version("2.0.0");
+    .version("2.0.2");
 function withHost(value) {
     const host = normalizeHost(value);
     if (!host) {

package/dist/src/state/config.js

@@ -8,8 +8,8 @@ import { HttpClient } from "../client/http.js";
 import { BackendClient } from "../client/backend.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
-export const DEFAULT_BASE_URL = "https://test.itpay.ai";
-export const CLI_VERSION = "2.0.0";
+export const DEFAULT_BASE_URL = "https://api.itpay.ai";
+export const CLI_VERSION = "2.0.2";
 export const API_CONTRACT_REVISION = "sha256:2c2829f4618c47bc505efc0ded853cf639d775585ba13aa23012197e39efa31f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/docs/agent/buyer/cart-checkout.json

@@ -58,7 +58,7 @@
     },
     {
       "intent": "create quote lock and checkout for a service-backed cart item",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email> --json",
+      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
       "success_signal": "the quote lock is bound to the original server cart item when present; JSON includes checkout_id and display_token"
     },
     {
@@ -76,6 +76,7 @@
     "Do not remove quote-locked or checkout-bound cart lines. Continue checkout/payment or use refund/cancel owner flow after payment.",
     "If required contact data is missing, prefer --require-contact so the CLI can emit a structured interaction request.",
     "Do not invent buyer email or phone values; let the human provide them when required.",
+    "Only request --email when the selected capability declares delivery_email_required. Tell the buyer it sends the protected result claim link.",
     "The happy-path buy flow creates cart and checkout, then renders checkout_qr. It should not create a payment intent first."
   ],
   "forbidden": [

package/docs/agent/buyer/catalog-list.json

@@ -17,14 +17,16 @@
     }
   ],
   "output_interpretation": {
-    "item_format": "Each item shows catalog_item_id, title, provider, service_type, category, and a list of variants with catalog_variant_id, offer_id, title, amount, currency.",
+    "item_format": "Each item includes product description, a structured service_flow, valid IDs, and purchasable offers.",
+    "service_flow": "Explain discovery as an auxiliary identity-confirmation step, including free quota and paid continuation. Present primary_service as the actual paid outcome. Read all values from the manifest.",
     "variant_selection": "To buy, the buyer needs catalog_item_id, catalog_variant_id, and offer_id from the output.",
     "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically."
   },
   "agent_rules": [
     "Use `itpay catalog list` before suggesting purchase options.",
     "Read the variant IDs and prices from the output; do not invent them.",
-    "Present options to the buyer in a readable table or list format.",
+    "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
+    "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
     "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet)."
   ],
   "next_docs": [

package/docs/agent/buyer/install-and-setup.json

@@ -29,7 +29,7 @@
   "env_vars": {
     "ITPAY_BACKEND_URL": {
       "required": false,
-      "description": "Optional V3 backend override. This test release defaults to https://test.itpay.ai.",
+      "description": "Optional V3 backend override. The CLI defaults to https://api.itpay.ai.",
       "examples": ["http://localhost:18080", "https://test.itpay.ai"]
     },
     "ITPAY_BEARER_TOKEN": {
@@ -63,7 +63,7 @@
     "lark": "Use --host lark --target <open_id>. Same as feishu format."
   },
   "agent_rules": [
-    "Use the built-in https://test.itpay.ai test-release default; override ITPAY_BACKEND_URL only for another deliberate environment.",
+    "Use the built-in https://api.itpay.ai production default; override ITPAY_BACKEND_URL only for another deliberate environment.",
     "Install globally with npm install -g @itpay/cli for all hosts.",
     "Identify the real runtime with --agent-type or ITPAY_AGENT_TYPE; do not invent a new type to obtain quota.",
     "Run `itpay install` without arguments to see all supported targets.",

package/docs/agent/buyer/payment-flow.json

@@ -17,12 +17,12 @@
     },
     {
       "intent": "create service-execution quote lock and render ItPay checkout page handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email>",
+      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>]",
       "success_signal": "The quote lock is bound to the original server cart item when present; ItPay checkout QR/URL is rendered for the human; the checkout page handles authorization and provider payment."
     },
     {
       "intent": "create service-execution checkout with machine-readable handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email> --json",
+      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
       "success_signal": "JSON with kind='checkout_handoff_required', next_action='open_human_checkout', checkout_url, display_token, qr_png_url, and brand_qr_local_path."
     },
     {

package/docs/agent/buyer/quickstart.json

@@ -12,7 +12,7 @@
   "required_state": {
     "needs": [
       "itpay CLI installed",
-      "test-release API at https://test.itpay.ai, or an intentional ITPAY_BACKEND_URL override",
+      "production API at https://api.itpay.ai, or an intentional ITPAY_BACKEND_URL override",
       "catalog item id, variant id, and offer id from `itpay catalog list`",
       "real agent runtime type supplied through --agent-type or ITPAY_AGENT_TYPE"
     ],
@@ -80,7 +80,7 @@
     },
     {
       "intent": "create checkout from a confirmed service execution and render human handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email> --json",
+      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
       "success_signal": "quote lock is bound to the server cart item when present; JSON includes checkout_id, display_token, checkout_url, qr_png_url, and brand_qr_local_path"
     },
     {
@@ -134,6 +134,7 @@
     "For service-backed catalog items, read service_execution_id from `itpay cart add --json` before invoking service capabilities.",
     "Do not use --pay or itpay pay for the normal buyer flow; first show the ItPay checkout QR/URL so the human enters the checkout page.",
     "If buy emits an interaction request for missing contact fields, collect values and rerun with --contact-email/--contact-phone.",
+    "For services checkout, include --email only when next_actions includes it. Explain that protected delivery uses it to send the claim link; agent-visible paid results do not require email.",
     "Do not assume checkout implies payment succeeded; it only creates a handoff.",
     "Payment success is confirmed by backend checkout/order state, not by QR display or buyer claim.",
     "A human grant applies only to its service execution and expires after 15 minutes; do not claim access to other orders or executions.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -20,7 +20,7 @@ itpay readyz
 itpay docs show quickstart
 ```
 
-This test release defaults to `https://test.itpay.ai`. Set `ITPAY_BACKEND_URL`
+The CLI defaults to `https://api.itpay.ai`. Set `ITPAY_BACKEND_URL`
 only for an intentional override.
 
 Every commerce flow must identify the real runtime. Pass the global option
@@ -59,9 +59,13 @@ the checkout with the exact server-selected capability:
 
 ```bash
 itpay --agent-type <agent_type> services checkout <service_execution_id> \
-  --capability <capability_id> --email <human_email> --host <host> --json
+  --capability <capability_id> [--email <human_email>] --host <host> --json
 ```
 
+Include `--email` only when the CLI's `next_actions` command includes it. For a
+protected delivery, explain that the address receives the order claim link;
+never invent an address. Agent-visible paid results do not require email.
+
 5. Show both handoff forms to the human:
 
 - Attach `brand_qr_local_path` when `brand_qr_status` is `downloaded`.