@itpay/cli 0.2.3 → 0.2.5

package/README.md

@@ -213,7 +213,7 @@ redacted secure delivery status:
 ```bash
 itp buyer catalog search --query 企业工商 --json
 itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=阿里 --json
-itp buyer checkout create --cart <cart_id> --email buyer@example.com --json
+itp buyer checkout create --cart <cart_id> --email <buyer_email> --json
 itp buyer payment wait <payment_intent_id> --json
 itp buyer checkout status <checkout_id> --json
 ```
@@ -221,7 +221,7 @@ itp buyer checkout status <checkout_id> --json
 For the one-command buyer helper:
 
 ```bash
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --email buyer@example.com --input company_name=阿里 --display agent --no-wait-payment --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=阿里 --display agent --no-wait-payment --json
 ```
 
 For multi-item cart tests:
@@ -239,7 +239,8 @@ Payment QR rules:
 - Otherwise render the ItPay-hosted `qr_png_url` / `preferred_qr_url`.
 - Use `mobile_wallet_url` only as a human mobile fallback.
 - Do not generate your own QR from payment URLs.
-- In agent app clients, send `payment_handoff.markdown` to the human first, then run `payment_handoff.wait_command`.
+- In agent app clients, send `human_visible_markdown` to the human first, then run `after_human_visible_markdown.command`.
+- If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 
 If the human wants the agent to analyze delivered content, the human must reveal

package/bin/itp

@@ -93,8 +93,8 @@ async function main() {
       output({
         version: VERSION,
         commands: [
-          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --display agent --no-wait-payment --json",
-          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --no-wait --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --display agent --no-wait-payment --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --no-wait --json",
           "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --json",
           "buyer catalog get --variant var_pubg_couple_skin_cny20 --json",
           "buyer cart create --variant var_pubg_couple_skin_cny20 --json",
@@ -105,7 +105,7 @@ async function main() {
           "buyer shelf manifest --json",
           "buyer shelf snapshot --version <catalog_version> --json",
           "buyer shelf delta --since <catalog_version> --json",
-          "buyer checkout create --cart <cart_id> --method alipay --email buyer@example.com --phone +8613800000000 --json",
+          "buyer checkout create --cart <cart_id> --method alipay --email <buyer_email> --phone +8613800000000 --json",
           "buyer checkout status <checkout_id> --json",
           "buyer checkout resume <checkout_id> --json",
           "buyer auth status --json",

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

@@ -68,8 +68,8 @@
     },
     {
       "intent": "do both steps through the high-level command",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status is waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "success_signal": "response.status is waiting_human_auth, payment_handoff_required, payment_verified, or delivery_claimable"
     }
   ],
   "agent_rules": [

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

@@ -8,7 +8,7 @@
     "Checkout returns human_action.kind=auth_qr for the first-purchase auth-to-payment entry.",
     "PaymentIntent has been created.",
     "The CLI returned human_action.kind=payment_qr, qr_png_url, preferred_qr_url, or qr_image_url.",
-    "The human needs to scan with Alipay sandbox."
+    "The human needs to scan with the payment provider."
   ],
   "required_state": {
     "needs": ["payment_intent_id", "human_action", "qr_png_url/preferred_qr_url or local_qr_path"],
@@ -17,8 +17,8 @@
   "commands": [
     {
       "intent": "create payment intent through the high-level buy flow",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.payment_handoff.markdown and response.payment_handoff.wait_command are present"
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "success_signal": "response.status is payment_handoff_required; response.human_visible_markdown is present; response.after_human_visible_markdown.command is the wait command to run after showing the QR/link"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -33,17 +33,18 @@
     "Payment QR display requires both a valid/saved buyer session and payment_intent_id. If payment_intent_id appears before buyer_session is saved, run buyer checkout resume/status instead of showing payment QR.",
     "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
     "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
-    "In Codex or Claude Code app clients, the default UX is show-then-wait: show response.payment_handoff.markdown first, then run response.payment_handoff.wait_command.",
-    "For Telegram-style message clients, show response.payment_handoff.markdown and stop unless the human asks you to keep waiting or returns with a payment question.",
+    "In Codex or Claude Code app clients, the default UX is show-then-wait: send response.human_visible_markdown to the human first, then run response.after_human_visible_markdown.command.",
+    "For Telegram-style message clients, show response.human_visible_markdown and stop unless the human asks you to keep waiting or returns with a payment question.",
+    "When response.status is payment_handoff_required, response.next is the human reply step, not payment wait.",
     "MUST show local_qr_path first when present. Many agent clients do not reliably render remote QR images; local_qr_path is the most reliable desktop/chat display artifact.",
     "If local_qr_path is not present, show qr_png_url or preferred_qr_url as the primary scannable QR. This is an ItPay-hosted human QR image; it may render the native provider payment code for scanner reliability, but the agent must not request or decode the raw provider payload.",
     "Use qr_image_url/SVG only as a fallback when PNG/local rendering is unavailable.",
     "For mobile users, present mobile_wallet_url as a clickable payment button when present.",
     "payment_entry_url is the stable ItPay status/payment page. qr_png_url/local_qr_path is usually the better desktop scanner artifact.",
-    "In Alipay sandbox, the provider can briefly show order not found even after precreate succeeded. Tell the human to wait 30-60 seconds and retry the same QR/page. Do not create a new checkout, do not create a new payment intent, and do not repeatedly refresh unless the ItPay page or CLI explicitly asks for recovery.",
+    "The provider can briefly show order not found even after precreate succeeded. Tell the human to wait 30-60 seconds and retry the same QR/page. Do not create a new checkout, do not create a new payment intent, and do not repeatedly refresh unless the ItPay page or CLI explicitly asks for recovery.",
     "Opening the payment page must not be treated as paid.",
-    "Do not run payment wait before the QR/link has been sent to the human.",
-    "After showing QR, run payment_handoff.wait_command or buyer payment wait for the same payment_intent_id."
+    "Do not run payment wait before the QR/link has been sent to the human. If you accidentally do, CLI returns payment_handoff_required instead of blocking.",
+    "After showing QR, run after_human_visible_markdown.command or buyer payment wait <payment_intent_id> --qr-shown for the same payment_intent_id."
   ],
   "forbidden": [
     "Do not encode payment_entry_url into a new QR yourself when qr_png_url/local_qr_path is available.",
@@ -61,7 +62,7 @@
       "command": "itp docs show payment-wait --role buyer --json"
     },
     {
-      "condition": "Alipay sandbox says order not found after waiting on the same QR/page",
+      "condition": "the payment provider says order not found after waiting on the same QR/page",
       "topic": "qr-refresh",
       "command": "itp docs show qr-refresh --role buyer --json"
     }

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

@@ -17,7 +17,7 @@
   "commands": [
     {
       "intent": "wait for payment verified event",
-      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "command": "itp buyer payment wait <payment_intent_id> --qr-shown --json",
       "success_signal": "response.payment_event.event_type == payment_intent.verified"
     },
     {
@@ -27,7 +27,8 @@
     }
   ],
   "agent_rules": [
-    "Start payment wait only after the QR image/link has already been sent to the human.",
+    "Start payment wait only after the QR image/link has already been sent to the human; use --qr-shown to confirm that step is complete.",
+    "If you run payment wait without --qr-shown while payment is still pending, CLI returns payment_handoff_required and human_visible_markdown instead of long-polling.",
     "Payment wait is a recovery loop around the same payment_intent_id, not a one-shot command.",
     "wait.timeout is a heartbeat, not a payment failure.",
     "In Codex or Claude Code app clients, after showing QR, wait online for a short visible cycle first. If the human still has not paid, explain that the same QR/link remains valid and pause for their reply.",

package/docs/agent/buyer/qr-refresh.json

@@ -5,7 +5,7 @@
   "title": "QR Refresh Recovery",
   "purpose": "Teach the agent how to recover scanner problems without changing payment truth or creating a second order.",
   "when_to_use": [
-    "The human reports Alipay sandbox says order not found after waiting 30-60 seconds on the same QR/page.",
+    "The human reports the payment provider says order not found after waiting 30-60 seconds on the same QR/page.",
     "The QR expired or the wallet cannot load it.",
     "The payment intent is still not verified."
   ],
@@ -29,7 +29,7 @@
     "QR refresh is display recovery only. ItPay may return the same QR again when the current provider QR is still valid.",
     "Use the same payment_intent_id.",
     "If QR does not render, first use the returned local_qr_path, qr_png_url, or preferred_qr_url. Do not generate a new QR from guessed provider payload.",
-    "For Alipay sandbox order-not-found, first ask the human to wait and scan/open the same QR/page again; use refresh only after that wait has failed.",
+    "For provider order-not-found, first ask the human to wait and scan/open the same QR/page again; use refresh only after that wait has failed.",
     "If refresh succeeds, show only the returned ItPay QR/display URL and continue waiting on the same payment_intent_id.",
     "After refresh, continue waiting through the normal wait contract."
   ],

package/docs/agent/buyer/quickstart.json

@@ -36,8 +36,8 @@
     },
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
-      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status becomes waiting_human_auth or waiting_user_payment; if waiting_user_payment, response.payment_handoff contains markdown and wait_command"
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if payment_handoff_required, send response.human_visible_markdown to the human before running response.after_human_visible_markdown.command"
     }
   ],
   "agent_rules": [
@@ -54,8 +54,9 @@
     "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
     "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
     "Vault grants are only for reading approved delivered artifacts. They are not buyer session credentials and do not authorize refunds or account/order management.",
-    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show payment_handoff, then run payment_handoff.wait_command.",
-    "If response.payment_handoff.markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown, then run after_human_visible_markdown.command.",
+    "If response.human_visible_markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the QR/link is visible may you run after_human_visible_markdown.command.",
     "Show the returned payment QR exactly as provided before starting payment wait.",
     "Payment truth comes only from payment_intent.verified.",
     "Secure delivery goes to the human first; report redacted delivery status only."

package/lib/buyer.js

@@ -7,9 +7,10 @@ import { coreApi, coreApiBase } from "./http.js";
 import { renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
+  rejectBuyerSandboxFlag(flags);
   const showThenWait = shouldReturnAfterAgentTextQR(flags);
   const selectionID = flags.selection || flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id;
-  if (!selectionID) throw new Error("catalog variant id is required, for example: itp buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --json");
+  if (!selectionID) throw new Error("catalog variant id is required, for example: itp buy <variant_id> --email <buyer_email> --json");
   const selection = await resolveBuyerCatalogSelection(selectionID, flags);
   const cart = await createBuyerCart(selection, flags);
   let checkout = await createBuyerCheckoutFromCart(cart, selection, flags);
@@ -44,18 +45,15 @@ async function buyerBuy(flags) {
 
   if (flags.no_wait || flags.no_wait_payment || showThenWait) {
     output(buyerRunOutput({
-      status: "waiting_user_payment",
+      status: "payment_handoff_required",
       selection,
       cart,
       checkout,
       payment_intent: intent,
       payment_handoff: paymentHandoff(intent),
-      agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-      next: {
-        command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-        safe_for_agent: true,
-        instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-      }
+      agent_next_actions: paymentHandoffAgentNextActions(),
+      next: paymentHandoffNext(),
+      after_human_visible_markdown: paymentHandoffAfter(intent)
     }));
     return;
   }
@@ -81,6 +79,7 @@ async function buyerBuy(flags) {
 }
 
 async function buyer(command, rest, flags) {
+  rejectBuyerSandboxFlag(flags);
   const subcommand = rest[0] && !String(rest[0]).startsWith("--") ? rest[0] : "";
   if (command === "catalog") {
     if (subcommand === "search") {
@@ -315,19 +314,16 @@ async function buyer(command, rest, flags) {
           const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
           await renderItPayPaymentAction(intent, flags);
           output(buyerRunOutput({
-            status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
+            status: intent.status === "verified" ? "payment_verified" : "payment_handoff_required",
             checkout,
             payment_intent: intent,
             payment_handoff: intent.status === "verified" ? undefined : paymentHandoff(intent),
             buyer_session: buyerSessionClaimStatus(claimedSession),
-            agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"],
+            agent_next_actions: intent.status === "verified" ? (intent.agent_next_actions || checkout.agent_next_actions || ["poll_checkout"]) : paymentHandoffAgentNextActions(),
             next: intent.status === "verified"
               ? { command: cliCommand("buyer", "checkout", "status", checkout.checkout_id, "--json"), safe_for_agent: true }
-              : {
-                command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-                safe_for_agent: true,
-                instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-              }
+              : paymentHandoffNext(),
+            after_human_visible_markdown: intent.status === "verified" ? undefined : paymentHandoffAfter(intent)
           }));
           return;
         }
@@ -341,16 +337,13 @@ async function buyer(command, rest, flags) {
         const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
         await renderItPayPaymentAction(intent, flags);
         output(buyerRunOutput({
-          status: "waiting_user_payment",
+          status: "payment_handoff_required",
           checkout,
           payment_intent: intent,
           payment_handoff: paymentHandoff(intent),
-          agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-          next: {
-            command: paymentWaitCommand(intent.payment_intent_id, { short: true }),
-            safe_for_agent: true,
-            instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-          }
+          agent_next_actions: paymentHandoffAgentNextActions(),
+          next: paymentHandoffNext(),
+          after_human_visible_markdown: paymentHandoffAfter(intent)
         }));
         return;
       }
@@ -369,6 +362,19 @@ async function buyer(command, rest, flags) {
     const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
     if (!paymentIntentID) throw new Error("payment_intent_id is required");
     const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
+    if (intent.status !== "verified" && !paymentQRShown(flags)) {
+      await renderItPayPaymentAction(intent, flags);
+      output(buyerRunOutput({
+        status: "payment_handoff_required",
+        payment_intent: intent,
+        payment_handoff: paymentHandoff(intent),
+        payment_guidance: paymentRecoveryGuidance(intent, { event_type: "payment_display_required" }),
+        agent_next_actions: paymentHandoffAgentNextActions(),
+        next: paymentHandoffNext(),
+        after_human_visible_markdown: paymentHandoffAfter(intent)
+      }));
+      return;
+    }
     const event = intent.status === "verified"
       ? { event_type: "payment_intent.verified", payment_intent_id: paymentIntentID, agent_next_actions: intent.agent_next_actions || ["poll_checkout"] }
       : await waitBuyerPayment(intent, flags);
@@ -380,7 +386,7 @@ async function buyer(command, rest, flags) {
       agent_next_actions: event.agent_next_actions || intent.agent_next_actions || paymentAgentNextActions(intent, event),
       next: event.event_type === "payment_intent.verified"
         ? { command: intent.checkout_id ? cliCommand("buyer", "checkout", "status", intent.checkout_id, "--json") : undefined, safe_for_agent: true }
-        : { command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json"), safe_for_agent: true }
+        : { command: paymentWaitCommand(paymentIntentID, { qrShown: true }), safe_for_agent: true }
     }));
     return;
   }
@@ -390,18 +396,15 @@ async function buyer(command, rest, flags) {
     const refreshed = await refreshBuyerPaymentQR(paymentIntentID, flags);
     await renderItPayPaymentAction(refreshed, flags);
     output(buyerRunOutput({
-      status: refreshed.status === "verified" ? "payment_verified" : "waiting_user_payment",
+      status: refreshed.status === "verified" ? "payment_verified" : "payment_handoff_required",
       payment_intent: refreshed,
       payment_handoff: refreshed.status === "verified" ? undefined : paymentHandoff(refreshed),
       payment_guidance: paymentRecoveryGuidance(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
-      agent_next_actions: refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: refreshed.status === "verified" ? "payment_intent.verified" : "qr_refreshed" }),
+      agent_next_actions: refreshed.status === "verified" ? (refreshed.agent_next_actions || paymentAgentNextActions(refreshed, { event_type: "payment_intent.verified" })) : paymentHandoffAgentNextActions(),
       next: refreshed.status === "verified"
         ? { command: cliCommand("buyer", "checkout", "status", refreshed.checkout_id, "--json"), safe_for_agent: true }
-        : {
-          command: paymentWaitCommand(refreshed.payment_intent_id, { short: true }),
-          safe_for_agent: true,
-          instruction: "Send payment_handoff.markdown to the human first, then run this wait command unless the human explicitly asked you to pause."
-        }
+        : paymentHandoffNext(),
+      after_human_visible_markdown: refreshed.status === "verified" ? undefined : paymentHandoffAfter(refreshed)
     }));
     return;
   }
@@ -822,7 +825,7 @@ async function createBuyerCheckoutFromCart(cart, selection = null, flags = {}) {
   const cartID = typeof cart === "string" ? cart : (cart?.cart_id || cart?.id);
   if (!cartID) throw new Error("cart_id is required");
   const deliveryContact = {};
-  if (flags.email) deliveryContact.email = flags.email;
+  if (flags.email) deliveryContact.email = realBuyerEmail(flags.email);
   if (flags.phone) deliveryContact.phone = flags.phone;
   const missing = requiredDeliveryContactFields(selection).filter((field) => !deliveryContact[field]);
   if (missing.length) {
@@ -861,6 +864,21 @@ function requiredDeliveryContactFields(selection) {
   return Array.isArray(fields) ? fields.map((field) => String(field).trim()).filter(Boolean) : [];
 }
 
+function rejectBuyerSandboxFlag(flags = {}) {
+  if (!flags?.sandbox) return;
+  throw new Error("--sandbox is not used by buyer commands; environment is selected by the ItPay API base. Run the command without --sandbox.");
+}
+
+function realBuyerEmail(value) {
+  const email = String(value || "").trim();
+  if (!email) return "";
+  const domain = email.split("@").pop().toLowerCase();
+  if (["example.com", "example.net", "example.org"].includes(domain)) {
+    throw new Error("placeholder email rejected; ask the human for their real delivery email before checkout.");
+  }
+  return email;
+}
+
 async function createBuyerPaymentIntent(checkoutID, flags = {}) {
   if (!checkoutID) throw new Error("checkout_id is required");
   const method = String(flags.method || flags.payment_method || "alipay").toLowerCase();
@@ -1035,7 +1053,7 @@ function paymentHandoff(intent = {}) {
   const preferredQRURL = action.preferred_qr_url || qrPNGURL || action.qr_image_url || intent.qr_image_url || intent.qr?.image_url || "";
   const localQRPath = action.local_qr_path || intent.local_qr_path || "";
   const mobileWalletURL = action.mobile_wallet_url || intent.mobile_wallet_url || "";
-  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true });
+  const waitCommand = paymentWaitCommand(paymentIntentID, { short: true, qrShown: true });
   return {
     type: "payment_qr_handoff",
     payment_intent_id: paymentIntentID || null,
@@ -1049,7 +1067,8 @@ function paymentHandoff(intent = {}) {
     markdown: paymentHandoffMarkdown({ localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL }),
     wait_command: waitCommand || null,
     safe_for_agent: true,
-    instruction: "Show markdown to the human first. Then run wait_command and wait for payment_intent.verified unless the human asked you to pause."
+    instruction: "Show markdown to the human first. Then run wait_command and wait for payment_intent.verified unless the human asked you to pause.",
+    display_targets: paymentHandoffDisplayTargets()
   };
 }
 
@@ -1063,11 +1082,46 @@ function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRUR
   return lines.join("\n\n");
 }
 
-function paymentWaitCommand(paymentIntentID, { short = false } = {}) {
+function paymentWaitCommand(paymentIntentID, { short = false, qrShown = false } = {}) {
   if (!paymentIntentID) return "";
-  return short
-    ? cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "60", "--json")
-    : cliCommand("buyer", "payment", "wait", paymentIntentID, "--json");
+  const args = ["buyer", "payment", "wait", paymentIntentID];
+  if (short) args.push("--timeout", "60");
+  if (qrShown) args.push("--qr-shown");
+  args.push("--json");
+  return cliCommand(...args);
+}
+
+function paymentQRShown(flags = {}) {
+  if (flags.qr_shown === undefined) return false;
+  return booleanFlag(flags.qr_shown);
+}
+
+function paymentHandoffAgentNextActions() {
+  return ["show_human_visible_markdown"];
+}
+
+function paymentHandoffNext() {
+  return {
+    type: "reply_to_human",
+    safe_for_agent: false,
+    instruction: "Send human_visible_markdown to the human now. Do not run payment wait until this message is visible to the human."
+  };
+}
+
+function paymentHandoffAfter(intent = {}) {
+  return {
+    command: paymentWaitCommand(intent.payment_intent_id, { short: true, qrShown: true }),
+    safe_for_agent: true,
+    instruction: "Run this only after human_visible_markdown has been sent to the human."
+  };
+}
+
+function paymentHandoffDisplayTargets() {
+  return {
+    desktop_app: ["local_qr_path", "qr_png_url", "payment_entry_url"],
+    terminal: ["qr_png_url", "payment_entry_url", "mobile_wallet_url"],
+    chat_cloud: ["qr_png_url", "payment_entry_url", "mobile_wallet_url"]
+  };
 }
 
 function paymentRecoveryGuidance(intent = {}, event = {}) {
@@ -1367,7 +1421,7 @@ async function refreshBuyerPaymentQR(paymentIntentID, flags = {}) {
   if (intent.status === "verified") return intent;
   const refreshURL = intent.qr_refresh_url;
   if (!refreshURL) {
-    throw new Error("payment intent does not expose qr_refresh_url; refresh is supported only for refreshable Alipay sandbox QR intents");
+    throw new Error("payment intent does not expose qr_refresh_url; refresh is supported only for refreshable provider QR intents");
   }
   return await coreApi(refreshURL, {
     method: "POST",
@@ -1409,7 +1463,7 @@ async function waitBuyerPayment(intent, flags = {}) {
       action: intent?.human_action || null,
       lastHeartbeatAt,
       flags,
-      command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json")
+      command: paymentWaitCommand(paymentIntentID, { qrShown: true })
     });
   }
   return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["wait_payment"] };
@@ -1436,10 +1490,11 @@ function isBuyerDeliveryComplete(result) {
 }
 
 function buyerRunOutput(value = {}) {
+  const body = compactBuyerOutput(value);
   return normalizeBuyerMoneyFields(stripInternalBuyerFields({
     schema_version: "itp.buyer.v1",
+    ...body,
     docs: value.docs || buyerDocsFor(value),
-    ...value,
     secrets: {
       raw_content_included: false,
       claim_token_included: false,
@@ -1448,6 +1503,158 @@ function buyerRunOutput(value = {}) {
   }));
 }
 
+function compactBuyerOutput(value = {}) {
+  const result = {};
+  if (value.status !== undefined) result.status = value.status;
+  if (value.payment_handoff?.markdown) {
+    result.must_reply_to_human_before_next_command = true;
+    result.human_visible_markdown = value.payment_handoff.markdown;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (["docs", "status"].includes(key)) continue;
+    result[key] = compactBuyerField(key, item);
+  }
+  return result;
+}
+
+function compactBuyerField(key, value) {
+  if (key === "selection") return compactSelection(value);
+  if (key === "selections") return Array.isArray(value) ? value.map(compactSelection) : value;
+  if (key === "product") return compactProduct(value);
+  if (key === "products") return Array.isArray(value) ? value.map(compactProduct) : value;
+  if (key === "cart") return compactCart(value);
+  if (key === "checkout") return compactCheckout(value);
+  if (key === "payment_intent") return compactPaymentIntent(value);
+  return value;
+}
+
+function compactSelection(selection = {}) {
+  if (!selection || typeof selection !== "object") return selection;
+  return compactObject({
+    catalog_item_id: selection.catalog_item_id,
+    catalog_variant_id: selection.catalog_variant_id,
+    ucp_variant_id: selection.ucp_variant_id,
+    offer_id: selection.offer_id,
+    title: selection.title,
+    variant_title: selection.variant_title,
+    amount: selection.expected_amount,
+    currency: selection.currency,
+    required_contact_fields: selection.required_contact_fields,
+    purchasable: selection.purchasable
+  });
+}
+
+function compactProduct(product = {}) {
+  if (!product || typeof product !== "object") return product;
+  return compactObject({
+    id: product.id,
+    title: product.title,
+    description: product.description,
+    selected: product.selected,
+    variants: Array.isArray(product.variants) ? product.variants.map(compactVariant) : undefined
+  });
+}
+
+function compactVariant(variant = {}) {
+  const metadata = variant.metadata || {};
+  return compactObject({
+    id: variant.id,
+    title: variant.title,
+    description: variant.description,
+    price: variant.price,
+    availability: variant.availability,
+    required_profile_fields: metadata["ai.itpay.required_profile_fields"],
+    input_schema_json: metadata["ai.itpay.api.input_schema_json"],
+    agent_explanation_zh: metadata["ai.itpay.agent_explanation_zh"]
+  });
+}
+
+function compactCart(cart = {}) {
+  if (!cart || typeof cart !== "object") return cart;
+  return compactObject({
+    cart_id: cart.cart_id || cart.id,
+    status: cart.status,
+    amount: cart.amount,
+    currency: cart.currency,
+    line_items: Array.isArray(cart.line_items) ? cart.line_items.map(compactCartLine) : undefined
+  });
+}
+
+function compactCartLine(line = {}) {
+  return compactObject({
+    id: line.id,
+    quantity: line.quantity,
+    amount: line.amount,
+    currency: line.currency,
+    input: line.input,
+    item: line.item ? compactObject({
+      id: line.item.id,
+      title: line.item.title,
+      catalog_item_id: line.item.catalog_item_id,
+      catalog_variant_id: line.item.catalog_variant_id,
+      offer_id: line.item.offer_id
+    }) : undefined
+  });
+}
+
+function compactCheckout(checkout = {}) {
+  if (!checkout || typeof checkout !== "object") return checkout;
+  return compactObject({
+    checkout_id: checkout.checkout_id,
+    cart_id: checkout.cart_id,
+    order_id: checkout.order_id,
+    status: checkout.status,
+    delivery_status: checkout.delivery_status,
+    identity_status: checkout.identity_status,
+    next_required_action: checkout.next_required_action,
+    payment_intent_id: checkout.payment_intent_id,
+    amount: checkout.amount,
+    currency: checkout.currency,
+    delivery: checkout.delivery,
+    human_action: checkout.human_action,
+    agent_next_actions: checkout.agent_next_actions
+  });
+}
+
+function compactPaymentIntent(intent = {}) {
+  if (!intent || typeof intent !== "object") return intent;
+  return compactObject({
+    payment_intent_id: intent.payment_intent_id,
+    payment_attempt_id: intent.payment_attempt_id,
+    checkout_id: intent.checkout_id,
+    order_id: intent.order_id,
+    status: intent.status,
+    amount: intent.amount,
+    currency: intent.currency,
+    human_action: compactHumanAction(intent.human_action),
+    qr_png_url: intent.qr_png_url,
+    qr_image_url: intent.qr_image_url,
+    mobile_wallet_url: intent.mobile_wallet_url,
+    agent_wait: intent.agent_wait,
+    agent_next_actions: intent.agent_next_actions
+  });
+}
+
+function compactHumanAction(action = null) {
+  if (!action || typeof action !== "object") return action;
+  return compactObject({
+    kind: action.kind,
+    url: action.url,
+    local_qr_path: action.local_qr_path,
+    local_qr_mime: action.local_qr_mime,
+    qr_png_url: action.qr_png_url,
+    qr_image_url: action.qr_image_url,
+    preferred_qr_url: action.preferred_qr_url,
+    mobile_wallet_url: action.mobile_wallet_url,
+    agent_display_hint: action.agent_display_hint,
+    expires_at: action.expires_at
+  });
+}
+
+function compactObject(value = {}) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null));
+}
+
 function normalizeBuyerMoneyFields(value) {
   if (Array.isArray(value)) return value.map((item) => normalizeBuyerMoneyFields(item));
   if (!value || typeof value !== "object") return value;
@@ -1481,7 +1688,7 @@ function buyerDocsFor(value = {}) {
     topics.add("cart-checkout");
     topics.add("payment-qr");
   }
-  if (status.includes("waiting_user_payment") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
+  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("show_human_visible_markdown") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
     topics.add("payment-qr");
     topics.add("payment-wait");
   }

package/lib/runtime.js

@@ -448,7 +448,7 @@ async function maybeMockApproveDeviceAuth(authId, flags) {
     return;
   }
   if (!fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
+    throw new Error("mock approval is developer-only and disabled for agent runs; use real payment-provider authentication");
   }
   const alipayUserId = flags.alipay_user_id || process.env.ITPAY_MOCK_ALIPAY_USER_ID || `2088${crypto.randomInt(100000000000, 999999999999)}`;
   await api(`/api/itp/auth/device/${encodeURIComponent(authId)}/mock-approve`, {
@@ -692,10 +692,10 @@ async function createCheckoutResult(flags) {
 
 function validateLivePaymentFlags(method, flags = {}) {
   if (String(method).toLowerCase() === "fake" && !fakeTestingAllowed(flags)) {
-    throw new Error("fake payment is developer-only and disabled for agent runs; use --method alipay for local, sandbox, and live testing");
+    throw new Error("fake payment is developer-only and disabled for agent runs; use --method alipay for local and live testing");
   }
   if ((flags.mock_approve || process.env.ITPAY_MOCK_APPROVE === "true" || process.env.ITPAY_MOCK_APPROVE === "1") && !fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
+    throw new Error("mock approval is developer-only and disabled for agent runs; use real payment-provider authentication");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -59,7 +59,7 @@ read this skill
 The high-level command can wrap this flow:
 
 ```bash
-itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
+itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
 ```
 
 For step-by-step testing:
@@ -93,7 +93,7 @@ itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input
 itp buyer cart show <cart_id> --json
 itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --json
 itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --sandbox --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --json
 ```
 
 For cart edits, always read the server cart first with `buyer cart show`.
@@ -206,23 +206,28 @@ Each docs page includes `next_docs`. Follow those links as the state changes.
 For payment creation in an agent/chat client, prefer:
 
 ```bash
-itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
+itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
 ```
 
 This keeps JSON output machine-readable while allowing the CLI to prepare a
 local QR image path for clients that cannot render remote SVG reliably. In
 Codex or Claude Code app clients, prefer `--no-wait-payment`: send
-`payment_handoff.markdown` to the human first, then run
-`payment_handoff.wait_command`. If the human is on mobile, present
+`human_visible_markdown` to the human first, then run
+`after_human_visible_markdown.command`. If the human is on mobile, present
 `mobile_wallet_url` as a clickable human-only fallback; do not convert it into a
 QR.
 
+If a response has `status=payment_handoff_required`, `next` is the user-visible
+reply step, not payment wait. Do not run `buyer payment wait` until the QR/link
+has been sent to the human; then use the returned
+`after_human_visible_markdown.command` with `--qr-shown`.
+
 For first-purchase auth, treat the returned ItPay authorization entry as a
 single human orchestration entry. It may open Alipay login/registration first
 and then payment after ItPay receives the OAuth callback. Do not call
 `oauth_start_url` directly unless the ItPay auth page asks for fallback.
-If the payment page says the Alipay sandbox entry is stabilizing/preparing,
-or if Alipay sandbox says "order not found", tell the human to wait 30-60
+If the payment page says provider entry is stabilizing/preparing,
+or if the payment provider says "order not found", tell the human to wait 30-60
 seconds and use the same page/QR again. Do not ask them to refresh repeatedly,
 and do not create another checkout or payment intent. Use
 `itp buyer payment refresh-qr ... --reason order-not-found` only after the
@@ -238,7 +243,7 @@ I found the service and selected the matching variant.
 I created the cart and checkout.
 Please open the returned ItPay authorization link and approve Alipay login.
 I am waiting for ItPay account authorization.
-Please scan the returned ItPay-hosted QR image with Alipay sandbox.
+Please scan the returned ItPay-hosted QR image with the payment provider.
 I am waiting for ItPay payment verification.
 Payment is verified.
 Delivery is claimable by the human buyer. Please check your email.