@itpay/cli 0.2.11 → 0.2.13

package/lib/render-human.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import QRCode from "qrcode";
+import { clientCommandArgs, clientHost, clientTarget } from "./client-context.js";
 import { apiTimeoutMs, cliCommand, commandExists, mergeRun, readRun, readState, safeErrorMessage, writeRun } from "./env.js";
 
 async function renderItPayPaymentAction(intent, flags = {}) {
@@ -423,6 +424,8 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
     media: mediaURL || undefined,
     presentation,
     command_args: compactObject({
+      channel: "telegram",
+      target: clientTarget() || undefined,
       message: text,
       media: mediaURL || undefined,
       presentation
@@ -431,55 +434,6 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
   });
 }
 
-function humanOutputFromRenderPlan(plan = {}) {
-  if (!plan || typeof plan !== "object") return null;
-  const selected = plan.selected || {};
-  const platforms = plan.platforms || {};
-  const base = {
-    required: true,
-    kind: plan.kind,
-    proof_rule: plan.proof_rule,
-    instruction: "Send this human_output to the human before running the next ItPay command."
-  };
-  if (selected.platform === "telegram") return { ...base, ...openclawHumanOutput(selected.openclaw_message) };
-  if (selected.platform === "codex_app" || selected.platform === "claude_code") return { ...base, method: "markdown_reply", markdown: selected.markdown };
-  if (selected.platform === "terminal") return { ...base, method: "terminal_display", print_terminal_qr: true, print_links: true };
-  if (selected.platform && selected.platform !== "current_channel_required") return { ...base, ...plainChatHumanOutput(selected) };
-  return {
-    ...base,
-    method: "current_channel_required",
-    instruction: "Choose the branch matching the current chat platform, send it to the human, then stop until the human responds or clicks a platform button.",
-    channels: compactObject({
-      openclaw_telegram: openclawHumanOutput(platforms.telegram?.openclaw_message),
-      codex_app: { method: "markdown_reply", markdown: platforms.codex_app?.markdown },
-      claude_code: { method: "markdown_reply", markdown: platforms.claude_code?.markdown },
-      plain_chat: plainChatHumanOutput(platforms.plain_chat),
-      terminal: { method: "terminal_display", print_terminal_qr: true, print_links: true }
-    })
-  };
-}
-
-function openclawHumanOutput(message = {}) {
-  if (!message) return null;
-  return compactObject({
-    method: "openclaw_message_send",
-    channel: "telegram",
-    message: message.command_args?.message || message.message,
-    media: message.command_args?.media || message.media,
-    presentation: message.command_args?.presentation || message.presentation,
-    callbacks: message.callbacks
-  });
-}
-
-function plainChatHumanOutput(plan = {}) {
-  if (!plan) return null;
-  return compactObject({
-    method: "plain_chat_reply",
-    text: plan.text,
-    links: plan.links
-  });
-}
-
 function openclawURLButton(text, url) {
   return compactObject({ text, url });
 }
@@ -490,15 +444,16 @@ function openclawCallbackButton(text, intent, action = {}) {
 }
 
 function openclawCallbackCommands(action = {}) {
+  const contextArgs = clientCommandArgs();
   if (action.kind === "payment_qr") {
     const id = action.payment_intent_id || action.id || "";
     return compactObject({
-      refresh_payment_qr: id ? `itp buyer payment refresh-qr ${id} --json` : undefined,
-      check_payment_status: id ? `itp buyer payment wait ${id} --timeout 1 --json` : undefined
+      refresh_payment_qr: id ? cliCommand("buyer", "payment", "refresh-qr", id, ...contextArgs, "--json") : undefined,
+      check_payment_status: id ? cliCommand("buyer", "payment", "wait", id, "--timeout", "1", ...contextArgs, "--json") : undefined
     });
   }
   if (action.checkout_id) {
-    return { check_checkout_status: `itp buyer checkout resume ${action.checkout_id} --json` };
+    return { check_checkout_status: cliCommand("buyer", "checkout", "resume", action.checkout_id, ...contextArgs, "--json") };
   }
   return undefined;
 }
@@ -526,14 +481,7 @@ function selectedRenderPlan(host = "", platforms = {}) {
   if (selectedPlatform && platforms[selectedPlatform]) {
     return { platform: selectedPlatform, ...platforms[selectedPlatform] };
   }
-  return compactObject({
-    platform: "current_channel_required",
-    rule: "Use render_plan.platforms.<current channel> when available; fallback is only for unsupported plain chat clients.",
-    telegram: platforms.telegram,
-    codex_app: platforms.codex_app,
-    claude_code: platforms.claude_code,
-    fallback: platforms.plain_chat
-  });
+  return { platform: "plain_chat", ...platforms.plain_chat };
 }
 
 function compactObject(value = {}) {
@@ -641,20 +589,7 @@ function shouldReturnAfterAgentTextQR(flags = {}) {
 }
 
 function agentHost(flags = {}) {
-  const explicit = String(
-    process.env.ITP_HOST ||
-    flags.host ||
-    flags.channel ||
-    process.env.OPENCLAW_CURRENT_CHANNEL_PROVIDER ||
-    process.env.OPENCLAW_CHANNEL ||
-    process.env.CURRENT_CHANNEL_PROVIDER ||
-    process.env.AGENT_CHANNEL ||
-    ""
-  ).toLowerCase();
-  if (explicit) return explicit;
-  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SHELL || process.env.CODEX_CI) return "codex";
-  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDECODE_SESSION_ID) return "claude-code";
-  return "";
+  return clientHost(flags);
 }
 
 function agentTextQRHosts() {
@@ -780,4 +715,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, humanOutputFromRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };
+export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -20,10 +20,27 @@ protocol from this file. Use the CLI docs graph whenever you need details.
 
 ## Start Here
 
+Every non-doc ItPay command must include the current client context. The CLI
+will stop with `client_context_required` or `client_target_required` rather
+than guess.
+
+```text
+Codex app:        --host codex
+Claude Code app:  --host claude-code
+Terminal:         --host terminal
+Plain chat:       --host plain-chat
+OpenClaw Telegram private/group chat: --host telegram --target <inbound_meta.chat_id>
+```
+
+For Telegram groups or @mention flows, use the same OpenClaw inbound
+`chat_id` as the target, for example `--target telegram:-1001234567890`.
+OpenClaw owns group allowlists and mention policy; ItPay only echoes the target
+into `openclaw message send`.
+
 Run these commands before buying:
 
 ```bash
-itp status --refresh --json
+itp status --refresh --host <client> --json
 itp docs show quickstart --role buyer --json
 itp docs list --role buyer --json
 ```
@@ -59,41 +76,41 @@ read this skill
 The high-level command can wrap this flow:
 
 ```bash
-itp buy <variant_id> --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 --host <client> --json
 ```
 
 For step-by-step testing:
 
 ```bash
-itp buyer catalog search --query "<user request>" --json
-itp buyer catalog search --query "企业工商信息 查询" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --json
-itp buyer catalog get --variant <variant_id> --json
-itp buyer cart create --variant <variant_id> --json
-itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,1 --json
-itp buyer cart show <cart_id> --json
-itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --json
-itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
-itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json
-itp buyer checkout resume <checkout_id> --json
-itp buyer payment wait <payment_intent_id> --timeout 1 --json
-itp buyer checkout status <checkout_id> --json
-itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --json
-itp buyer refund list --order <order_id> --json
-itp buyer refund show <refund_id> --json
-itp buyer refund cancel <refund_id> --reason buyer_changed_mind --json
-itp buyer vault grants list --checkout <checkout_id> --json
-itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json
+itp buyer catalog search --query "<user request>" --host <client> --json
+itp buyer catalog search --query "企业工商信息 查询" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --host <client> --json
+itp buyer catalog get --variant <variant_id> --host <client> --json
+itp buyer cart create --variant <variant_id> --host <client> --json
+itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,1 --host <client> --json
+itp buyer cart show <cart_id> --host <client> --json
+itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --host <client> --json
+itp buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json
+itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --host <client> --json
+itp buyer checkout resume <checkout_id> --host <client> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json
+itp buyer checkout status <checkout_id> --host <client> --json
+itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --host <client> --json
+itp buyer refund list --order <order_id> --host <client> --json
+itp buyer refund show <refund_id> --host <client> --json
+itp buyer refund cancel <refund_id> --reason buyer_changed_mind --host <client> --json
+itp buyer vault grants list --checkout <checkout_id> --host <client> --json
+itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json
 ```
 
 For API products, read the product metadata input schema before cart creation.
 Enterprise data products require query input at cart time:
 
 ```bash
-itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json
-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 --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --json
+itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --host <client> --json
+itp buyer cart show <cart_id> --host <client> --json
+itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --host <client> --json
+itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --host <client> --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --host <client> --json
 ```
 
 For cart edits, always read the server cart first with `buyer cart show`.
@@ -112,19 +129,19 @@ Refund commands use ItPay shared order state. If `itp buyer refund create`
 returns `policy_risk_confirmation_required`, explain the returned
 `refund_eligibility.policy` and `agent_guidance` to the human first. Only retry
 with `--confirm-policy-risk true` after explicit human confirmation.
-Do not guess `order_id`; if missing, run `buyer checkout status <checkout_id> --json`.
+Do not guess `order_id`; if missing, run `buyer checkout status <checkout_id> --host <client> --json`.
 Refund amounts use minor units: CNY 1000 means CNY 10.00.
 Refund commands require a server-verified buyer session, not a vault grant. If
 the CLI says the buyer session is required or expired, run
-`itp status --refresh --json` and follow the returned `next.command`.
+`itp status --refresh --host <client> --json` and follow the returned `next.command`.
 Current buyer refunds are whole-order only; do not use line-item refund scope.
 If the human cancels a refund before provider or money movement starts, use
-`buyer refund cancel <refund_id> --json`; after cancel, the delivery claim can
+`buyer refund cancel <refund_id> --host <client> --json`; after cancel, the delivery claim can
 be unlocked again by the ItPay backend.
 
 ## Non-Negotiable Rules
 
-1. Use `--json` for every ItPay command.
+1. Use `--json` and current client context for every non-doc ItPay command. Use `--host codex`, `--host claude-code`, `--host terminal`, `--host plain-chat`, or for OpenClaw Telegram use `--host telegram --target <inbound_meta.chat_id>`.
 2. Do not invent service IDs, variant IDs, checkout IDs, payment URLs, QR URLs,
    payment intent IDs, delivery IDs, or claim links.
 3. When the user asks for several compatible services, use one cart and one
@@ -206,18 +223,19 @@ 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> --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 --host <client> --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
-agent/chat clients, prefer `--no-wait-payment`: if `human_output_required=true`,
-send root `human_output` before any next ItPay command. In Codex or Claude Code
-app clients, send `human_output.markdown` exactly. In OpenClaw Telegram, pass
-`human_output.message/media/presentation` to `openclaw message send` so media
-and native `text/url/callback_data` buttons are sent through the adapter.
-`render_plan` is diagnostic/compatibility detail. Do not invent a table or
-rewrite the UI plan.
+agent/chat clients, prefer `--no-wait-payment`. In OpenClaw Telegram, if
+`agent_instruction` is present, call `openclaw message send` with
+`agent_instruction.openclaw_message.command_args`. The `target` field is the
+OpenClaw chat target, `media` is the QR image, `message` is the exact human text, and
+`presentation.blocks[].type="buttons"` creates Telegram native inline buttons.
+Do not rewrite it as a table or normal prose. In Codex or Claude Code app
+clients, send `agent_instruction.markdown` exactly before any next ItPay
+command.
 
 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 human