@itpay/cli 0.2.11 → 0.2.13

package/docs/agent/buyer/quickstart.json

@@ -24,7 +24,7 @@
   "commands": [
     {
       "intent": "verify whether this agent/device already has a server-valid buyer session",
-      "command": "itp status --refresh --json",
+      "command": "itp status --refresh --host <client> --json",
       "success_signal": "response.status is idle when authenticated, or response.next.command tells the agent how to start human auth; if response.recoverable_context.found is true, compare it with the current user intent before continuing or ignoring it"
     },
     {
@@ -34,23 +34,26 @@
     },
     {
       "intent": "search the public catalog for the current user request",
-      "command": "itp buyer catalog search --query \"<user request>\" --json",
+      "command": "itp buyer catalog search --query \"<user request>\" --host <client> --json",
       "success_signal": "response.products contains public services and purchase options; response.catalog_guidance tells the agent how to compare and when to ask the human"
     },
     {
       "intent": "search standardized API services with category/facet filters when intent is clear",
-      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --json",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --host <client> --json",
       "success_signal": "response.products are narrowed by category/facet before recommendation"
     },
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
-      "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 human_output_required is true, send response.human_output before any payment status check"
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json",
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; in OpenClaw Telegram, if agent_instruction is present, send response.agent_instruction.openclaw_message.command_args before any payment status check"
     }
   ],
   "agent_rules": [
     "Use --json for every ItPay command.",
-    "Use `itp status --refresh --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
+    "Every non-doc ItPay command must include the current client context: --host codex, --host claude-code, --host terminal, --host plain-chat, or for OpenClaw/Telegram use --host telegram --target <inbound_meta.chat_id>.",
+    "Do not rely on the CLI to guess Telegram, Discord, WhatsApp, Codex, or Claude Code. If ItPay returns client_context_required or client_target_required, rerun the same command with the required --host/--target fields before continuing.",
+    "For Telegram group chat or @mention flows, pass the group/private chat target from OpenClaw inbound metadata, for example --target telegram:-1001234567890. ItPay only echoes the target into openclaw message send; OpenClaw owns group allowlist/mention policy.",
+    "Use `itp status --refresh --host <client> --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
     "If `status --refresh` returns `recoverable_context.found=true`, do not blindly resume or blindly ignore it. Decide whether the old task is related to the current user intent; continue related tasks, ignore clearly unrelated tasks, and ask the human when unsure.",
     "If the catalog is unclear, read catalog-search docs and use buyer shelf manifest/snapshot as the shopping-list view before guessing keywords.",
     "Search and explain purchase options before buying unless the user already named a purchase option ID.",
@@ -62,13 +65,14 @@
     "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 send human_output, then only check status after the human responds or uses a platform button.",
-    "If response.human_output_required is true, send response.human_output immediately in the same user-visible message. It includes the QR image/link/buttons.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and send the human handoff instruction, then only check status after the human responds or uses a platform button.",
+    "If response.agent_instruction is present, it is the mandatory execution path for the current client. Do not use fallback fields or handwritten prose instead.",
+    "In OpenClaw Telegram, call openclaw message send with response.agent_instruction.openclaw_message.command_args. It includes target, QR media, exact message, and native button presentation.",
     "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the human asks to check payment should you run after_human_response.check_payment_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.",
-    "When response.human_output_required is true, root human_output is the execution path. render_plan is diagnostic/compatibility detail. In OpenClaw Telegram, pass human_output.message/media/presentation to openclaw message send instead of handwritten prose."
+    "For OpenClaw Telegram, root agent_instruction is the execution path. Do not use handwritten prose when agent_instruction.openclaw_message.command_args is present."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/docs/agent/buyer/recovery.json

@@ -11,23 +11,29 @@
     "Checkout or delivery is pending."
   ],
   "required_state": {
-    "needs": ["last known checkout_id, payment_intent_id, or variant_id"],
-    "must_not_need": ["ops token", "provider raw payload", "claim token"]
+    "needs": [
+      "last known checkout_id, payment_intent_id, or variant_id"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider raw payload",
+      "claim token"
+    ]
   },
   "commands": [
     {
       "intent": "resume checkout state",
-      "command": "itp buyer checkout resume <checkout_id> --json",
+      "command": "itp buyer checkout resume <checkout_id> --host <client> --json",
       "success_signal": "response.status and agent_next_actions describe the safe next action"
     },
     {
       "intent": "wait again on the same payment intent",
-      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
     },
     {
       "intent": "refresh display QR only",
-      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --host <client> --json",
       "success_signal": "response.payment_intent.qr_image_url is present"
     }
   ],
@@ -62,5 +68,18 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["recover", "resume", "timeout", "lost", "retry", "stuck", "恢复", "重试", "卡住", "没返回", "断了", "找不到"]
+  "search_terms": [
+    "recover",
+    "resume",
+    "timeout",
+    "lost",
+    "retry",
+    "stuck",
+    "恢复",
+    "重试",
+    "卡住",
+    "没返回",
+    "断了",
+    "找不到"
+  ]
 }

package/docs/agent/buyer/safety-policy.json

@@ -10,8 +10,13 @@
     "The agent is deciding between buyer and ops commands."
   ],
   "required_state": {
-    "needs": ["role=buyer"],
-    "must_not_need": ["ops token", "raw secret access"]
+    "needs": [
+      "role=buyer"
+    ],
+    "must_not_need": [
+      "ops token",
+      "raw secret access"
+    ]
   },
   "commands": [
     {
@@ -52,5 +57,14 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["policy", "forbidden", "security", "secret", "ops", "安全", "禁止", "权限"]
+  "search_terms": [
+    "policy",
+    "forbidden",
+    "security",
+    "secret",
+    "ops",
+    "安全",
+    "禁止",
+    "权限"
+  ]
 }

package/docs/agent/buyer/secure-delivery.json

@@ -10,23 +10,30 @@
     "The user asks where the purchased key/content is."
   ],
   "required_state": {
-    "needs": ["checkout_id"],
-    "must_not_need": ["claim token", "claim link", "raw key", "storage ref"]
+    "needs": [
+      "checkout_id"
+    ],
+    "must_not_need": [
+      "claim token",
+      "claim link",
+      "raw key",
+      "storage ref"
+    ]
   },
   "commands": [
     {
       "intent": "check redacted delivery status",
-      "command": "itp buyer checkout status <checkout_id> --json",
+      "command": "itp buyer checkout status <checkout_id> --host <client> --json",
       "success_signal": "delivery.sensitive_content_redacted == true"
     },
     {
       "intent": "list agent-safe delivery state",
-      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.deliveries contains no raw content or claim token"
     },
     {
       "intent": "after the human says they granted agent access, discover the current agent's grants",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants contains only grants for this exact agent device"
     }
   ],
@@ -68,5 +75,16 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["delivery", "claim", "email", "key", "redeem", "secure delivery", "交付", "邮件", "领取", "密钥"]
+  "search_terms": [
+    "delivery",
+    "claim",
+    "email",
+    "key",
+    "redeem",
+    "secure delivery",
+    "交付",
+    "邮件",
+    "领取",
+    "密钥"
+  ]
 }

package/docs/agent/buyer/vault-agent-read.json

@@ -10,35 +10,45 @@
     "A checkout/order has delivered a vault artifact and the human granted agent-readable access."
   ],
   "required_state": {
-    "needs": ["checkout_id or authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
-    "must_not_need": ["human portal token", "claim token", "passkey credential", "raw protected payload", "grant id copied by the human"]
+    "needs": [
+      "checkout_id or authenticated buyer account session",
+      "current agent device binding",
+      "order_id or checkout_id or vault_artifact_id"
+    ],
+    "must_not_need": [
+      "human portal token",
+      "claim token",
+      "passkey credential",
+      "raw protected payload",
+      "grant id copied by the human"
+    ]
   },
   "commands": [
     {
       "intent": "check whether this agent has active human-approved grants for a checkout",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants is an array; count > 0 means the human has granted this exact agent access"
     },
     {
       "intent": "check whether this agent has active human-approved grants for one order or artifact",
-      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "only grants scoped to this logged-in agent device are returned"
     },
     {
       "intent": "read a discovered grant view",
-      "command": "itp buyer vault grants read <agent_read_grant_id> --json",
+      "command": "itp buyer vault grants read <agent_read_grant_id> --host <client> --json",
       "success_signal": "response.grant contains selected_fields, structured_view, or summary according to the human-approved scope"
     },
     {
       "intent": "convenience read by order/artifact without asking the human for grant id",
-      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "the CLI discovers the active grant and reads its scoped view"
     }
   ],
   "agent_rules": [
     "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
-    "Prefer `itp buyer vault grants list --checkout <checkout_id> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
-    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
+    "Prefer `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
+    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --host <client> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
     "Do not ask the human to copy or paste `agent_read_grant_id`; discover it with `buyer vault grants list`.",
     "If no grant is returned, tell the human to open their ItPay account portal, reveal with Passkey, choose fields, and confirm one-key agent authorization.",
     "If no grant is returned, explain likely causes: the human has not authorized yet, selected the wrong order/page, authorization has not synced yet, checkout/order/artifact does not match, buyer session expired, or the grant expired/revoked.",
@@ -46,7 +56,7 @@
     "Use only fields returned in the grant view. Do not infer that unreturned fields are accessible.",
     "When a grant view is returned, tell the user which fields are readable. If expires_at, ttl, or valid_until is present, tell the user the time limit; if no expiry is returned, say the response did not include an explicit expiry.",
     "If the returned fields are not enough for the user's task, ask the human to reopen Give to Agent and add the needed fields. Do not ask them to paste the missing raw content.",
-    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
+    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --host <client> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
   ],
   "forbidden": [
     "Do not open, click through, scrape, or automate the human web UI yourself.",
@@ -72,5 +82,14 @@
       "command": "itp docs show safety-policy --role buyer --json"
     }
   ],
-  "search_terms": ["vault", "agent read", "passkey grant", "one key agent", "授权给 agent", "可读授权", "字段授权", "查看报告"]
+  "search_terms": [
+    "vault",
+    "agent read",
+    "passkey grant",
+    "one key agent",
+    "授权给 agent",
+    "可读授权",
+    "字段授权",
+    "查看报告"
+  ]
 }