@itpay/cli 0.2.16 → 2.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +148 -447
  2. package/bin/itp +1 -150
  3. package/dist/src/client/backend.js +154 -0
  4. package/dist/src/client/http.js +76 -0
  5. package/dist/src/client/types.js +4 -0
  6. package/dist/src/commands/buy.js +351 -0
  7. package/dist/src/commands/cart.js +264 -0
  8. package/dist/src/commands/catalog.js +26 -0
  9. package/dist/src/commands/checkout.js +106 -0
  10. package/dist/src/commands/docs.js +61 -0
  11. package/dist/src/commands/guidance.js +422 -0
  12. package/dist/src/commands/install.js +95 -0
  13. package/dist/src/commands/order.js +78 -0
  14. package/dist/src/commands/orders.js +22 -0
  15. package/dist/src/commands/pay.js +26 -0
  16. package/dist/src/commands/readyz.js +8 -0
  17. package/dist/src/commands/refund.js +20 -0
  18. package/dist/src/commands/services.js +317 -0
  19. package/dist/src/main.js +606 -0
  20. package/dist/src/render/feishu.js +201 -0
  21. package/dist/src/render/ide.js +321 -0
  22. package/dist/src/render/index.js +57 -0
  23. package/dist/src/render/interaction.js +49 -0
  24. package/dist/src/render/markdown.js +83 -0
  25. package/dist/src/render/output.js +42 -0
  26. package/dist/src/render/plain_chat.js +60 -0
  27. package/dist/src/render/plan.js +31 -0
  28. package/dist/src/render/qr.js +32 -0
  29. package/dist/src/render/sink.js +6 -0
  30. package/dist/src/render/status.js +37 -0
  31. package/dist/src/render/telegram.js +172 -0
  32. package/dist/src/render/terminal.js +148 -0
  33. package/dist/src/render/terminal_image.js +19 -0
  34. package/dist/src/state/cart_session.js +151 -0
  35. package/dist/src/state/client_context.js +73 -0
  36. package/dist/src/state/config.js +82 -0
  37. package/dist/src/state/device_authority.js +217 -0
  38. package/dist/src/state/operation_journal.js +80 -0
  39. package/docs/agent/buyer/cart-checkout.json +56 -94
  40. package/docs/agent/buyer/catalog-list.json +47 -0
  41. package/docs/agent/buyer/install-and-setup.json +82 -0
  42. package/docs/agent/buyer/orders-refunds.json +76 -0
  43. package/docs/agent/buyer/payment-flow.json +77 -0
  44. package/docs/agent/buyer/quickstart.json +143 -75
  45. package/docs/agent/buyer/render-hosts.json +79 -0
  46. package/package.json +32 -13
  47. package/skills/itpay-buyer/SKILL.md +107 -238
  48. package/docs/agent/buyer/account-portal.json +0 -81
  49. package/docs/agent/buyer/catalog-search.json +0 -106
  50. package/docs/agent/buyer/human-claim-ui.json +0 -77
  51. package/docs/agent/buyer/payment-qr.json +0 -97
  52. package/docs/agent/buyer/payment-wait.json +0 -84
  53. package/docs/agent/buyer/product-recommendation.json +0 -80
  54. package/docs/agent/buyer/qr-refresh.json +0 -67
  55. package/docs/agent/buyer/recovery.json +0 -85
  56. package/docs/agent/buyer/safety-policy.json +0 -70
  57. package/docs/agent/buyer/secure-delivery.json +0 -90
  58. package/docs/agent/buyer/vault-agent-read.json +0 -95
  59. package/install.ps1 +0 -65
  60. package/install.sh +0 -66
  61. package/lib/account-status.js +0 -157
  62. package/lib/buyer.js +0 -2332
  63. package/lib/client-context.js +0 -126
  64. package/lib/docs.js +0 -200
  65. package/lib/env.js +0 -723
  66. package/lib/http.js +0 -151
  67. package/lib/ops.js +0 -135
  68. package/lib/render-human.js +0 -718
  69. package/lib/runtime.js +0 -1456
@@ -2,142 +2,104 @@
2
2
  "schema_version": "itp.agent_doc.v1",
3
3
  "role": "buyer",
4
4
  "topic": "cart-checkout",
5
- "title": "Cart-First Checkout",
6
- "purpose": "Teach the agent to use the UCP cart handoff, including CORE-033 multi-item carts, instead of bypassing cart.",
5
+ "title": "V3 Cart-First Checkout",
6
+ "purpose": "Teach the agent to use the current V3 canonical server cart flow without treating local CLI state as business truth.",
7
7
  "when_to_use": [
8
- "The user selected one or more public catalog purchase options.",
9
- "The agent needs an estimate before checkout.",
10
- "The agent needs to create a checkout from cart_id.",
11
- "A first-time wild agent may receive auth_qr as a first-purchase auth-to-payment entry before payment is verified."
8
+ "The user already chose a catalog item, variant, and offer.",
9
+ "The agent needs to add a catalog item to a server cart before checkout.",
10
+ "The agent wants to understand how service-backed cart items create or resume Service Execution."
12
11
  ],
13
12
  "required_state": {
14
13
  "needs": [
15
- "catalog_variant_id or catalog_variant_ids",
16
- "buyer email for secure delivery",
17
- "service-declared required input fields before cart creation"
14
+ "catalog_item_id",
15
+ "catalog_variant_id",
16
+ "offer_id"
18
17
  ],
19
18
  "optional": [
20
- "buyer phone"
19
+ "quantity",
20
+ "contact email",
21
+ "contact phone",
22
+ "agent_device_id for service-backed items"
21
23
  ],
22
24
  "must_not_need": [
23
- "catalog version",
24
- "expected amount",
25
- "ops token"
25
+ "catalog search support from this CLI"
26
26
  ]
27
27
  },
28
28
  "commands": [
29
29
  {
30
- "intent": "create a cart estimate for the selected purchase option",
31
- "command": "itp buyer cart create --variant <variant_id> --host <client> --json",
32
- "success_signal": "response.cart.cart_id is present and response.cart_guidance tells the agent to show the cart to the human before checkout"
30
+ "intent": "add the first line to the canonical server cart",
31
+ "command": "itpay cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --host <client> --json",
32
+ "success_signal": "JSON includes cart_id and cart_item_id; service-backed lines also include service_execution_id and top-level next_actions"
33
33
  },
34
34
  {
35
- "intent": "create a multi-item cart estimate for selected purchase options",
36
- "command": "itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,2 --host <client> --json",
37
- "success_signal": "response.cart.line_items contains every selected purchase option and response.cart_guidance.double_check_required is true"
35
+ "intent": "recover the next step for the current cart",
36
+ "command": "itpay cart next --json",
37
+ "success_signal": "JSON includes next_actions derived from the canonical server cart and Service Execution read model"
38
38
  },
39
39
  {
40
- "intent": "create an enterprise fuzzy search cart with required query input",
41
- "command": "itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --host <client> --json",
42
- "success_signal": "response.cart.cart_id is present; the raw provider result is not visible to the agent"
40
+ "intent": "inspect the current canonical server cart before checkout",
41
+ "command": "itpay cart show",
42
+ "success_signal": "server cart lines, checkout readiness, and service refs are printed"
43
43
  },
44
44
  {
45
- "intent": "create an enterprise precise lookup cart with exact registered name or credit code",
46
- "command": "itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --host <client> --json",
47
- "success_signal": "response.cart.cart_id is present; payment can proceed only after the exact query input is locked into the cart line"
45
+ "intent": "soft-remove one active line from the canonical server cart",
46
+ "command": "itpay cart remove --line <cart_item_id>",
47
+ "success_signal": "the line is removed from the server cart; quote-locked or checkout-bound lines return a conflict"
48
48
  },
49
49
  {
50
- "intent": "view the current cart state without relying on model memory",
51
- "command": "itp buyer cart show <cart_id> --host <client> --json",
52
- "success_signal": "response.cart.line_items and response.cart.totals reflect the server-side cart; show these fields to the human before checkout"
50
+ "intent": "abandon the canonical server cart",
51
+ "command": "itpay cart clear",
52
+ "success_signal": "the server cart is abandoned, active lines are soft-removed, and local handles are cleared"
53
53
  },
54
54
  {
55
- "intent": "add one more selected UCP Variant.id to an existing cart before checkout",
56
- "command": "itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --host <client> --json",
57
- "success_signal": "response.cart.cart_id is unchanged; response.cart.line_items either includes a new line for different input/settings or increments quantity for an identical line"
55
+ "intent": "create checkout from a server cart that is ready for checkout",
56
+ "command": "itpay buy --cart <cart_id> --host <client> [--contact-email <email>] [--contact-phone <phone>]",
57
+ "success_signal": "the CLI either renders checkout_qr or emits an interaction request for missing contact data"
58
58
  },
59
59
  {
60
- "intent": "remove one line from an existing cart before checkout",
61
- "command": "itp buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json",
62
- "success_signal": "response.cart.cart_id is unchanged and response.cart.line_items no longer contains that line id"
60
+ "intent": "create quote lock and checkout for a service-backed cart item",
61
+ "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email> --json",
62
+ "success_signal": "the quote lock is bound to the original server cart item when present; JSON includes checkout_id and display_token"
63
63
  },
64
64
  {
65
- "intent": "create checkout from cart_id",
66
- "command": "itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --host <client> --json",
67
- "success_signal": "response.checkout.checkout_id is present; if response.checkout.next_required_action is auth_qr, show response.checkout.human_action and poll/resume until payment_intent_id appears"
68
- },
69
- {
70
- "intent": "do both steps through the high-level command",
71
- "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json",
72
- "success_signal": "response.status is waiting_human_auth, payment_handoff_required, payment_verified, or delivery_claimable"
65
+ "intent": "read the next Service Execution action",
66
+ "command": "itpay services next <service_execution_id> --json",
67
+ "success_signal": "JSON includes next_actions such as invoke capability, select result item, or checkout"
73
68
  }
74
69
  ],
75
70
  "agent_rules": [
76
- "CORE-033 supports multiple cart lines and bounded positive quantities when all items belong to the same supported settlement/provider group.",
77
- "Before cart creation, inspect product/selection metadata and input_schema_json. The service provider declares whether input is fuzzy, exact, or human/sensitive; the agent must not guess.",
78
- "If service metadata says fuzzy input is allowed, collect the declared field, for example input.company_name can be a keyword, brand, short name, or partial company name such as 京东.",
79
- "If service metadata says exact input is required, collect the declared exact field, for example input.company_name_or_credit_no must be a complete China mainland registered company name or unified social credit code.",
80
- "If service metadata says input is sensitive, personal, or human-authorized, do not collect it in chat. Continue through the ItPay human authorization/input flow.",
81
- "Use --input key=value for service-specific inputs. For multiple query lines, prefer separate cart add commands so each line locks its own input.",
82
- "Cart line identity includes variant, offer, price, provider product, and normalized input. Only a completely identical line should merge by increasing quantity.",
83
- "If the same variant has a different company_name, company_name_or_credit_no, page number, setting, or any other input value, it must remain a separate cart line.",
84
- "Before checkout create, confirm buyer email is available for secure delivery. If it is missing, ask the human for the email before checkout; do not guess or use a placeholder.",
85
- "Use cart_id as the checkout handoff.",
86
- "Use buyer cart show before changing an existing cart and whenever you need current cart contents. Do not rely on chat memory for cart state.",
87
- "After cart create/add/remove/show, present the cart contents to the human: service, purchase option, each input, quantity, price, and delivery mode.",
88
- "If the cart has more than one line item, double-check every line with the human unless the user's prompt was already explicit and the server cart exactly matches it.",
89
- "Cart confirmation is mandatory before checkout create. Selected service is not the same as confirmed cart.",
90
- "Use buyer cart add/remove before checkout when the user changes their mind. After checkout is created, treat the cart as locked.",
91
- "Do not override cart line_items during checkout.",
92
- "Cart, checkout, and catalog JSON money fields use minor units. For CNY, amount=10 or expected_amount=10 means CNY 0.10. Tell humans the display_amount or converted major-unit amount, never interpret amount as yuan.",
93
- "If the user asks for several compatible products, add them to one cart and create one checkout. Do not split into separate checkouts unless ItPay rejects the cart or says split checkout is required.",
94
- "If the same cart is retried, expect the same checkout unless contact/client reference changes.",
95
- "The backend revalidates catalog, price, and delivery requirements.",
96
- "For first purchase, auth_qr means the ItPay first-purchase entry: provider login/registration/profile consent first, then ItPay should continue the same checkout to payment.",
97
- "If this agent/device already has a valid buyer session token, checkout should skip auth_qr and can continue toward payment_intent_id.",
98
- "After presenting auth_qr, run buyer checkout resume and keep it active/waiting. Do not stop at QR display unless the human explicitly asks you to pause.",
99
- "Do not tell the user auth_qr is a completed payment or payment proof.",
100
- "For first purchase, show the ItPay auth entry as one human orchestration entry; after provider OAuth callback the same checkout exposes payment.",
101
- "After showing auth_qr, poll checkout or run buyer checkout resume until identity_status becomes identity_resolved and payment_intent_id appears.",
102
- "When auth completes, CLI should claim and store the buyer session so a repeat purchase by the same agent/device can skip auth.",
103
- "If checkout status/resume returns buyer_session.status=buyer_session_saved, the agent is now bound to that buyer account on this device. Continue with payment, delivery polling, or buyer vault commands; do not ask the human for a buyer session token.",
104
- "Do not enter payment unless both conditions are true: a valid/saved buyer session exists and payment_intent_id exists.",
105
- "If payment_intent_id exists but buyer_session is missing, do not show payment QR. Resume/status the same checkout until the buyer session is saved or verified."
71
+ "The current V3 CLI uses server cart as the business source of truth. Local ~/.itpay-v3/cart.json only caches last ids and explicit local drafts.",
72
+ "Prefer top-level next_actions and itpay next/cart next/services next over hardcoded service-specific flows.",
73
+ "Use cart add/show/remove/clear before checkout. Remove and clear are server-side soft state changes, not hard deletes.",
74
+ "For service-backed items, use service_execution_id from cart add/show as the canonical handle for services invoke/action/checkout.",
75
+ "Do not call buy --cart on a service-backed cart item until the required service action and quote lock are complete.",
76
+ "Do not remove quote-locked or checkout-bound cart lines. Continue checkout/payment or use refund/cancel owner flow after payment.",
77
+ "If required contact data is missing, prefer --require-contact so the CLI can emit a structured interaction request.",
78
+ "Do not invent buyer email or phone values; let the human provide them when required.",
79
+ "The happy-path buy flow creates cart and checkout, then renders checkout_qr. It should not create a payment intent first."
106
80
  ],
107
81
  "forbidden": [
108
- "Use the UCP cart and buyer checkout commands for external-agent tests.",
109
- "Do not pass a different variant in checkout after cart is created.",
110
- "Do not create checkout before showing the cart contents and getting confirmation.",
111
- "Do not show a payment QR when buyer_session is missing, even if payment_intent_id is present.",
112
- "Do not create a second cart/checkout after a retryable timeout unless the user asks to abandon the previous one.",
113
- "Do not buy enterprise precise lookup with only a vague brand/short name unless you have resolved the exact registered company name.",
114
- "Do not claim enterprise API raw results are visible to the agent; they are delivered to the human Vault/claim UI."
82
+ "Do not treat local cart files as durable business truth.",
83
+ "Do not create duplicate checkout commands if the first handoff is still usable.",
84
+ "Do not treat QR display as proof of payment."
115
85
  ],
116
86
  "next_docs": [
117
87
  {
118
- "condition": "Checkout returns auth_qr",
119
- "topic": "payment-qr",
120
- "command": "itp docs show payment-qr --role buyer --json"
121
- },
122
- {
123
- "condition": "Checkout has payment_intent_id and payment QR is needed",
124
- "topic": "payment-qr",
125
- "command": "itp docs show payment-qr --role buyer --json"
88
+ "condition": "Need host rendering details after checkout is created",
89
+ "topic": "render-hosts",
90
+ "file": "docs/agent/buyer/render-hosts.json"
126
91
  },
127
92
  {
128
- "condition": "Cart or checkout command fails",
129
- "topic": "recovery",
130
- "command": "itp docs show recovery --role buyer --json"
93
+ "condition": "Need order or refund follow-up after payment",
94
+ "topic": "orders-refunds",
95
+ "file": "docs/agent/buyer/orders-refunds.json"
131
96
  }
132
97
  ],
133
98
  "search_terms": [
134
99
  "cart",
135
100
  "checkout",
136
- "cart_id",
137
- "line_items",
138
- "quantity",
101
+ "buy",
139
102
  "购物车",
140
- "下单",
141
103
  "结账"
142
104
  ]
143
105
  }
@@ -0,0 +1,47 @@
1
+ {
2
+ "schema_version": "itp.agent_doc.v1",
3
+ "role": "buyer",
4
+ "topic": "catalog-list",
5
+ "title": "Browse ItPay V3 Service Catalog",
6
+ "purpose": "Teach the agent how to browse and display available catalog services to the buyer.",
7
+ "when_to_use": [
8
+ "The buyer wants to see available services before purchasing.",
9
+ "The agent needs to know valid item / variant / offer IDs for cart or buy commands.",
10
+ "The buyer asks 'what can I buy?' or 'show me services'."
11
+ ],
12
+ "commands": [
13
+ {
14
+ "intent": "list all published services",
15
+ "command": "itpay catalog list",
16
+ "success_signal": "Catalog version, item count, and item details with variants and prices are printed."
17
+ }
18
+ ],
19
+ "output_interpretation": {
20
+ "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.",
21
+ "variant_selection": "To buy, the buyer needs catalog_item_id, catalog_variant_id, and offer_id from the output.",
22
+ "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically."
23
+ },
24
+ "agent_rules": [
25
+ "Use `itpay catalog list` before suggesting purchase options.",
26
+ "Read the variant IDs and prices from the output; do not invent them.",
27
+ "Present options to the buyer in a readable table or list format.",
28
+ "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet)."
29
+ ],
30
+ "next_docs": [
31
+ {
32
+ "condition": "Buyer selected a service and wants to purchase",
33
+ "topic": "cart-checkout",
34
+ "file": "docs/agent/buyer/cart-checkout.json"
35
+ }
36
+ ],
37
+ "search_terms": [
38
+ "catalog",
39
+ "list",
40
+ "browse",
41
+ "services",
42
+ "products",
43
+ "what to buy",
44
+ "有哪些",
45
+ "服务列表"
46
+ ]
47
+ }
@@ -0,0 +1,82 @@
1
+ {
2
+ "schema_version": "itp.agent_doc.v1",
3
+ "role": "buyer",
4
+ "topic": "install-and-setup",
5
+ "title": "Install and Configure ItPay V3 CLI for Agent Hosts",
6
+ "purpose": "Guide the agent or runtime owner through installing and configuring the itpay CLI for different agent hosts.",
7
+ "when_to_use": [
8
+ "First-time setup of the itpay CLI.",
9
+ "The agent needs to be configured for a specific host (Codex, Claude Code, etc.).",
10
+ "The buyer wants to use itpay in a new environment."
11
+ ],
12
+ "commands": [
13
+ {
14
+ "intent": "list all supported install targets",
15
+ "command": "itpay install",
16
+ "success_signal": "Table of targets (claude-code, codex, terminal, telegram, feishu) with config file paths."
17
+ },
18
+ {
19
+ "intent": "show install instructions for a specific target",
20
+ "command": "itpay install claude-code",
21
+ "success_signal": "Step-by-step instructions for Claude Code setup."
22
+ },
23
+ {
24
+ "intent": "show install instructions for Codex / Trae",
25
+ "command": "itpay install codex",
26
+ "success_signal": "Step-by-step instructions for Codex/Trae setup."
27
+ }
28
+ ],
29
+ "env_vars": {
30
+ "ITPAY_BACKEND_URL": {
31
+ "required": false,
32
+ "description": "Optional V3 backend override. This prerelease defaults to https://test.itpay.ai.",
33
+ "examples": ["http://localhost:18080", "https://test.itpay.ai"]
34
+ },
35
+ "ITPAY_BEARER_TOKEN": {
36
+ "required": false,
37
+ "description": "Bearer token for authenticated operations (orders list, vault, profile). Not needed for anonymous cart/checkout.",
38
+ "acquired_from": "Sign in via web at /signin, then copy the session token."
39
+ },
40
+ "ITPAY_CART_SESSION_PATH": {
41
+ "required": false,
42
+ "description": "Custom path for the cart session file. Default: ~/.itpay-v3/cart.json"
43
+ },
44
+ "ITPAY_AGENT_DEVICE_ID": {
45
+ "required": false,
46
+ "description": "Legacy compatibility input. V3 enrolls a signed device identity under ~/.itpay-v3/device; agents should not rotate or invent this value."
47
+ },
48
+ "ITPAY_AGENT_TYPE": {
49
+ "required": false,
50
+ "description": "Agent runtime type. Set this or pass --agent-type for commerce commands, for example codex-desktop or claude-code-cli."
51
+ },
52
+ "ITPAY_CURRENCY": {
53
+ "required": false,
54
+ "description": "Default currency for cart operations. Default: CNY"
55
+ }
56
+ },
57
+ "host_requirements": {
58
+ "terminal": "No special config needed. QR renders as ASCII in terminal or saved as PNG file.",
59
+ "codex": "Use --host codex or --host trae. Markdown output with images and links.",
60
+ "claude-code": "Use --host claude-code. Markdown format with image references.",
61
+ "telegram": "Use --host telegram --target <chat_id>. Output includes openclaw_message payloads.",
62
+ "feishu": "Use --host feishu --target <open_id>. Output is Feishu Interactive Card JSON.",
63
+ "lark": "Use --host lark --target <open_id>. Same as feishu format."
64
+ },
65
+ "agent_rules": [
66
+ "Use the built-in https://test.itpay.ai prerelease default; override ITPAY_BACKEND_URL only for another deliberate environment.",
67
+ "Install globally with npm install -g @itpay/cli for all hosts.",
68
+ "Identify the real runtime with --agent-type or ITPAY_AGENT_TYPE; do not invent a new type to obtain quota.",
69
+ "Run `itpay install` without arguments to see all supported targets.",
70
+ "Server cart facts persist in backend Postgres. ~/.itpay-v3/cart.json only caches last ids, checkout display token, and explicit local drafts."
71
+ ],
72
+ "search_terms": [
73
+ "install",
74
+ "setup",
75
+ "configure",
76
+ "first time",
77
+ "setup",
78
+ "安装",
79
+ "配置",
80
+ "environment"
81
+ ]
82
+ }
@@ -0,0 +1,76 @@
1
+ {
2
+ "schema_version": "itp.agent_doc.v1",
3
+ "role": "buyer",
4
+ "topic": "orders-refunds",
5
+ "title": "Orders, Payment Escape Hatch, And Refund Requests",
6
+ "purpose": "Teach the agent how to inspect orders and create refund requests with the current V3 CLI package.",
7
+ "when_to_use": [
8
+ "The user wants to inspect one order.",
9
+ "The agent needs to list orders for an account-scoped bearer session.",
10
+ "The user wants to request a refund.",
11
+ "The checkout page is unavailable and the operator needs the payment-intent escape hatch."
12
+ ],
13
+ "required_state": {
14
+ "needs": [
15
+ "order_id for order or refund flows",
16
+ "payment_intent_id for refund flows"
17
+ ],
18
+ "optional": [
19
+ "ITPAY_BEARER_TOKEN for account order listing"
20
+ ]
21
+ },
22
+ "commands": [
23
+ {
24
+ "intent": "read one canonical order by id",
25
+ "command": "itpay order <order_id>",
26
+ "success_signal": "order details and a status hint are printed"
27
+ },
28
+ {
29
+ "intent": "list account-visible orders",
30
+ "command": "ITPAY_BEARER_TOKEN=<account_scoped_token> itpay orders --limit 20",
31
+ "success_signal": "orders are listed, or the CLI prints that no orders were found"
32
+ },
33
+ {
34
+ "intent": "create a payment intent only when the normal checkout page cannot do it",
35
+ "command": "itpay pay --checkout <checkout_id> --method alipay",
36
+ "success_signal": "payment_intent_id and current payment state are printed"
37
+ },
38
+ {
39
+ "intent": "request a refund for an order",
40
+ "command": "itpay refund --order <order_id> --payment-intent <payment_intent_id> --amount-minor <n> --currency CNY --reason buyer_requested",
41
+ "success_signal": "refund request id and refund status are printed"
42
+ }
43
+ ],
44
+ "agent_rules": [
45
+ "Use itpay order when you already know the exact order id.",
46
+ "Use itpay orders only with an account-scoped bearer token. Missing or wrong scope should be surfaced as an error, not guessed away.",
47
+ "Treat itpay pay as an operator escape hatch. The checkout handoff remains the preferred path.",
48
+ "Refund amounts are minor units. For CNY, 100 means CNY 1.00.",
49
+ "The refund response is the current source of truth; do not assume success locally."
50
+ ],
51
+ "forbidden": [
52
+ "Do not fabricate bearer tokens.",
53
+ "Do not create a payment intent first if normal checkout rendering is available.",
54
+ "Do not claim a refund succeeded before the backend response says so."
55
+ ],
56
+ "next_docs": [
57
+ {
58
+ "condition": "Need the initial buyer flow",
59
+ "topic": "quickstart",
60
+ "file": "docs/agent/buyer/quickstart.json"
61
+ },
62
+ {
63
+ "condition": "Need host-specific render behavior for checkout handoff",
64
+ "topic": "render-hosts",
65
+ "file": "docs/agent/buyer/render-hosts.json"
66
+ }
67
+ ],
68
+ "search_terms": [
69
+ "order",
70
+ "orders",
71
+ "refund",
72
+ "payment intent",
73
+ "退款",
74
+ "订单"
75
+ ]
76
+ }
@@ -0,0 +1,77 @@
1
+ {
2
+ "schema_version": "itp.agent_doc.v1",
3
+ "role": "buyer",
4
+ "topic": "payment-flow",
5
+ "title": "ItPay V3 Payment Flow — From Checkout to Verified Payment",
6
+ "purpose": "Teach the agent how to hand a checkout to the human, let the ItPay checkout page create provider payment, and verify payment state.",
7
+ "when_to_use": [
8
+ "The agent has created a checkout and needs to hand it to the human.",
9
+ "The buyer wants to pay via Alipay or WeChat Pay.",
10
+ "The agent needs to wait for payment verification before confirming success."
11
+ ],
12
+ "commands": [
13
+ {
14
+ "intent": "create checkout from a canonical server cart and render ItPay checkout page handoff",
15
+ "command": "itpay buy --cart <cart_id> --host <client> --contact-email <email>",
16
+ "success_signal": "ItPay checkout QR/URL is rendered for the human; payment intent is not created by the agent."
17
+ },
18
+ {
19
+ "intent": "create service-execution quote lock and render ItPay checkout page handoff",
20
+ "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email>",
21
+ "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."
22
+ },
23
+ {
24
+ "intent": "create service-execution checkout with machine-readable handoff",
25
+ "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> --email <email> --json",
26
+ "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."
27
+ },
28
+ {
29
+ "intent": "recover a service checkout after output loss, process restart, or token expiry",
30
+ "command": "itpay services checkout <service_execution_id> --resume --json",
31
+ "success_signal": "The existing checkout is reused and a fresh handoff is persisted before rendering."
32
+ },
33
+ {
34
+ "intent": "inspect checkout state after payment",
35
+ "command": "itpay checkout --id <checkout_id> --token <display_token>",
36
+ "success_signal": "Current checkout status, any payment intents, and buyer session state."
37
+ }
38
+ ],
39
+ "payment_flow_states": {
40
+ "quote_bound": "Checkout created, no payment intent yet. Show the ItPay checkout QR/URL to the human.",
41
+ "payment_pending": "Payment intent created, waiting for buyer to complete payment.",
42
+ "payment_succeeded": "Payment verified via SSE event payment_intent.verified.",
43
+ "completed": "Order delivered."
44
+ },
45
+ "agent_rules": [
46
+ "Do not call itpay pay or use --pay for the normal buyer flow; those are operator escape hatches.",
47
+ "The human opens the ItPay checkout page first; the page handles authorization and creates the Alipay/WeChat payment intent.",
48
+ "For JSON output, render brand_qr_local_path or qr_png_url to the human; do not render provider qr.alipay.com directly.",
49
+ "After timeout, re-run checkout --id ... --token ... to check current state before retrying.",
50
+ "Payment success is confirmed ONLY by backend events, not by QR display or buyer claim."
51
+ ],
52
+ "next_docs": [
53
+ {
54
+ "condition": "Payment verified, need to check order state",
55
+ "topic": "orders-refunds",
56
+ "file": "docs/agent/buyer/orders-refunds.json"
57
+ },
58
+ {
59
+ "condition": "Need to understand render behavior per host",
60
+ "topic": "render-hosts",
61
+ "file": "docs/agent/buyer/render-hosts.json"
62
+ }
63
+ ],
64
+ "search_terms": [
65
+ "payment",
66
+ "pay",
67
+ "alipay",
68
+ "wechat",
69
+ "QR",
70
+ "payment intent",
71
+ "wait",
72
+ "SSE",
73
+ "verified",
74
+ "支付",
75
+ "扫码"
76
+ ]
77
+ }