@itpay/cli 2.0.2 → 2.0.5

package/dist/src/commands/install.js

@@ -1,95 +1,58 @@
 import { DEFAULT_BASE_URL } from "../state/config.js";
-const INSTALL_TARGETS = {
-    "claude-code": {
-        name: "Claude Code",
-        configFile: "~/.claude/settings.json",
-        instructions: [
-            "1. Ensure itpay is installed:  npm install -g @itpay/cli",
-            `2. Default API:                 ${DEFAULT_BASE_URL}`,
-            "3. Use --agent-type claude-code-cli or claude-code-desktop",
-            "4. Use --host claude-code for human-facing output",
-            "5. The CLI renders checkout QR as markdown images and links",
-        ],
-    },
-    codex: {
-        name: "Codex / Trae",
-        configFile: "~/.codex/config.toml",
-        instructions: [
-            "1. Ensure itpay is installed:  npm install -g @itpay/cli",
-            `2. Default API:                 ${DEFAULT_BASE_URL}`,
-            "3. Use --agent-type codex-cli or codex-desktop",
-            "4. Use --host trae or --host codex for human-facing output",
-            "5. Attach the emitted QR image and show the checkout link",
-            "6. Collect missing contact fields from the user; never invent them",
-        ],
-    },
-    terminal: {
-        name: "Terminal",
-        configFile: "shell profile (~/.zshrc, ~/.bashrc)",
-        instructions: [
-            "1. Install globally:            npm install -g @itpay/cli",
-            `2. Default API:                 ${DEFAULT_BASE_URL}`,
-            "3. Set the real runtime type with --agent-type <type>",
-            "4. Use --host terminal for text/QR output in terminal",
-            "5. Override ITPAY_BACKEND_URL only for local or test backends",
-        ],
-    },
-    telegram: {
-        name: "Telegram",
-        configFile: "OpenClaw gateway config",
-        instructions: [
-            "1. Install itpay:               npm install -g @itpay/cli",
-            `2. Default API:                 ${DEFAULT_BASE_URL}`,
-            "3. Set the real OpenClaw runtime with --agent-type <type>",
-            "4. Use --host telegram --target <chat_id> for human-facing output",
-            "5. The CLI emits openclaw_message payloads with buttons and QR images",
-        ],
-    },
-    feishu: {
-        name: "Feishu / Lark",
-        configFile: "Feishu bot config",
-        instructions: [
-            "1. Install itpay:               npm install -g @itpay/cli",
-            `2. Default API:                 ${DEFAULT_BASE_URL}`,
-            "3. Set the real agent runtime with --agent-type <type>",
-            "4. Use --host feishu --target <open_id> or --host lark --target <open_id>",
-            "5. The CLI emits Interactive Card JSON with buttons and QR images",
-        ],
-    },
+import { defaultHostForAgentType } from "../state/client_context.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+export const INSTALL_AGENT_TYPES = [
+    "codex-desktop",
+    "codex-cli",
+    "claude-code-desktop",
+    "claude-code-cli",
+    "workbuddy",
+];
+const INSTRUCTIONS = {
+    "codex-desktop": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
+    "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
+    "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
+    "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type；当前使用 plain-chat 交接，必须把链接和可用图片发到当前会话。",
 };
-export function runInstall(target) {
+export function runInstall(target, options = {}) {
     if (!target || target === "list") {
-        listTargets();
+        const agentTypes = INSTALL_AGENT_TYPES.map((agentType) => ({
+            agent_type: agentType,
+            default_host: defaultHostForAgentType(agentType),
+        }));
+        writeCommandEnvelope({
+            status: "install_targets",
+            result: { agent_types: agentTypes },
+            instruction: "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
+            next: null,
+            recovery: [{ command: "itpay docs show install-and-setup", reason: "查看安装与环境说明" }],
+        }, {
+            ...options,
+            plainResult: agentTypes.map((item) => `${item.agent_type}: ${item.default_host}`),
+        });
         return;
     }
-    const normalized = target.toLowerCase();
-    if (normalized === "trae") {
-        // Trae uses the codex install target
-        printInstall("codex");
-        return;
-    }
-    if (INSTALL_TARGETS[normalized]) {
-        printInstall(normalized);
-    }
-    else {
-        process.stderr.write(`unknown target "${target}". Available: ${Object.keys(INSTALL_TARGETS).join(", ")}\n`);
-        process.exitCode = 1;
+    const normalized = target.trim().toLowerCase();
+    if (!isInstallAgentType(normalized)) {
+        throw new CommandContractError("unsupported_agent_type", `unsupported install target: ${target}`, `target 只接受：${INSTALL_AGENT_TYPES.join(", ")}。`, [{ command: "itpay install --json", reason: "列出正式支持的 Agent Type" }]);
     }
+    writeCommandEnvelope({
+        status: "instructions_ready",
+        result: {
+            agent_type: normalized,
+            default_host: defaultHostForAgentType(normalized),
+            default_api: DEFAULT_BASE_URL,
+            install_command: "npm install -g @itpay/cli",
+        },
+        instruction: INSTRUCTIONS[normalized],
+        next: {
+            command: `itpay --agent-type ${normalized} readyz --json`,
+            reason: "验证 CLI 与默认 ItPay API 的兼容性",
+        },
+        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看环境覆盖和首次使用说明" }],
+    }, options);
 }
-function printInstall(key) {
-    const target = INSTALL_TARGETS[key];
-    if (!target)
-        return;
-    process.stdout.write(`\n=== ItPay V3 CLI — Install for ${target.name} ===\n`);
-    process.stdout.write(`Config file: ${target.configFile}\n\n`);
-    for (const line of target.instructions) {
-        process.stdout.write(`${line}\n`);
-    }
-    process.stdout.write("\n");
-}
-function listTargets() {
-    process.stdout.write("Available install targets:\n\n");
-    for (const [key, target] of Object.entries(INSTALL_TARGETS)) {
-        process.stdout.write(`  ${key.padEnd(14)} ${target.name.padEnd(18)} ${target.configFile}\n`);
-    }
+function isInstallAgentType(value) {
+    return INSTALL_AGENT_TYPES.includes(value);
 }

package/dist/src/commands/next.js

@@ -0,0 +1,45 @@
+import { writeCommandEnvelope } from "./guidance.js";
+export function runNext(session, options = {}) {
+    const envelope = nextEnvelope(session);
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+    });
+}
+function nextEnvelope(session) {
+    if (session.stateLoadFailed) {
+        return {
+            status: "local_state_invalid",
+            result: {},
+            instruction: "本地恢复句柄无法读取；不要猜测资源 ID，改从当前设备可见的服务执行恢复。",
+            next: { command: "itpay services list --json", reason: "从服务端恢复当前设备可见的执行" },
+            recovery: [],
+        };
+    }
+    const state = session.show();
+    if (state.lastServiceExecutionID) {
+        return resumeEnvelope("service_execution", state.lastServiceExecutionID, `itpay services next ${state.lastServiceExecutionID} --json`, "读取服务端最新状态");
+    }
+    if (state.lastCheckoutID && state.lastDisplayToken) {
+        return resumeEnvelope("checkout", state.lastCheckoutID, `itpay checkout --id ${state.lastCheckoutID} --token ${state.lastDisplayToken} --json`, "恢复同一 Checkout");
+    }
+    if (state.lastCartID) {
+        return resumeEnvelope("cart", state.lastCartID, "itpay cart next --json", "读取同一 Cart 的服务端状态");
+    }
+    return {
+        status: "nothing_to_resume",
+        result: {},
+        instruction: "本地没有可恢复句柄；先读取已发布目录，不要猜测 service_id。",
+        next: { command: "itpay catalog list --json", reason: "选择已发布服务" },
+        recovery: [],
+    };
+}
+function resumeEnvelope(resourceType, resourceID, command, reason) {
+    return {
+        status: "resume_available",
+        result: { resource_type: resourceType, resource_id: resourceID },
+        instruction: "继续已有资源，不要创建重复订单或 Checkout。",
+        next: { command, reason },
+        recovery: [],
+    };
+}

package/dist/src/commands/order.js

@@ -1,78 +1,53 @@
-// Read a single V3 order by id. Supports terminal text and agent markdown output.
-import { formatMoney, renderOrder } from "../render/output.js";
-import { hintFor } from "../render/status.js";
-import { resolveOutput } from "../render/sink.js";
-import { ensureIdeImageAttach, ideImageAttachBlock } from "../render/ide.js";
+import { formatMoney } from "../render/output.js";
+import { writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
-    const out = resolveOutput(options.output);
     const order = await backend.getOrder(orderID);
-    // Prepare an IDE image attach slot. Order responses usually do not
-    // carry a brand QR — the previous buy already produced one. We still
-    // call ensureIdeImageAttach so the disabled / failed / no-source
-    // states get surfaced consistently across commands.
-    const plan = {
-        kind: "checkout_qr",
-        host: (options.host ?? "terminal"),
-        summary: "order presentation",
-        url: "",
-        preferredQRSources: [],
-        platform: {
-            text: "order presentation",
-            links: [],
-            buttons: [],
-            blocks: [],
-        },
-    };
-    await ensureIdeImageAttach(plan, {
-        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+    const [delivery, refundResponse] = await Promise.all([
+        order.status === "delivered" ? backend.getOrderDeliveryAccess(orderID) : Promise.resolve(undefined),
+        backend.listOrderRefunds(orderID),
+    ]);
+    const lockedRefund = refundResponse.refunds.find((refund) => refund.access_locked);
+    const envelope = orderEnvelope(order, delivery, lockedRefund);
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: orderPlainResult(envelope.result),
     });
-    if (options.host === "codex" || options.host === "claude-code" || options.host === "trae") {
-        out(renderOrderMarkdown(order, plan) + "\n");
-    }
-    else {
-        out(renderOrder(order) + "\n");
-        if (plan.ideImageAttach) {
-            out(ideImageAttachBlock(plan.ideImageAttach).filter((l) => l.length > 0).join("\n") + "\n");
-        }
-        out(`hint: ${hintFor("order", order.status)}\n`);
-    }
 }
-function renderOrderMarkdown(order, plan) {
-    const lines = [];
-    lines.push(`## :package: 订单 ${order.order_id}`);
-    lines.push("");
-    const statusEmoji = order.status === "delivered" ? ":white_check_mark:" : order.status === "refunded" ? ":arrows_counterclockwise:" : ":hourglass:";
-    lines.push(`| 字段 | 值 |`);
-    lines.push(`|------|-----|`);
-    lines.push(`| 状态 | ${statusEmoji} ${order.status} |`);
-    lines.push(`| 金额 | ${formatMoney(order.amount_minor, order.currency)} |`);
-    lines.push(`| Checkout | \`${order.checkout_id}\``);
-    if (order.paid_at)
-        lines.push(`| 支付时间 | ${order.paid_at} |`);
-    lines.push("");
-    if (order.items.length > 0) {
-        lines.push(`| 项目 | 数量 | 单价 |`);
-        lines.push(`|------|:----:|------|`);
-        for (const item of order.items) {
-            lines.push(`| ${item.title} | ${item.quantity} | ${formatMoney(item.amount_minor, item.currency)} |`);
+function orderEnvelope(order, delivery, lockedRefund) {
+    const refundTerminal = lockedRefund && ["succeeded", "failed", "cancelled", "rejected"].includes(lockedRefund.status);
+    let instruction = "订单状态已读取；当前没有可用交付入口。";
+    let next = null;
+    if (lockedRefund) {
+        instruction = "退款访问锁已生效；不要 reveal、创建 grant 或读取交付结果。";
+        if (!refundTerminal) {
+            next = { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取退款的服务器状态" };
         }
-        lines.push("");
     }
-    if (order.delivery_artifacts.length > 0) {
-        lines.push(`### :lock: 交付物`);
-        lines.push("");
-        for (const artifact of order.delivery_artifacts) {
-            const notification = artifact.notification_status ? ` — notification:${artifact.notification_status}` : "";
-            const vault = artifact.vault_artifact_id ? ` — vault:\`${artifact.vault_artifact_id}\`` : "";
-            lines.push(`- \`${artifact.delivery_artifact_id}\` — ${artifact.artifact_type} — ${artifact.status}${notification}${vault}`);
-            if (artifact.public_preview)
-                lines.push(`  > ${artifact.public_preview}`);
-        }
-        lines.push("");
+    else if (delivery?.service_execution_id) {
+        instruction = "根据 delivery_mode 使用对应读取入口；不要从订单摘要猜测受保护内容。";
+        next = { command: `itpay services next ${delivery.service_execution_id} --json`, reason: "读取交付状态" };
     }
-    if (plan.ideImageAttach) {
-        lines.push(...ideImageAttachBlock(plan.ideImageAttach));
+    else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
+        instruction = "订单尚未进入交付终态；稍后查询同一订单，不要创建替代订单。";
+        next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单状态" };
     }
-    lines.push(`> :bulb: ${hintFor("order", order.status)}`);
-    return lines.join("\n");
+    return {
+        status: order.status,
+        result: {
+            order_id: order.order_id,
+            ...(order.order_code ? { order_code: order.order_code } : {}),
+            amount: formatMoney(order.amount_minor, order.currency),
+            ...(delivery ? { delivery_mode: delivery.delivery_mode } : {}),
+            access_locked: Boolean(lockedRefund),
+            ...(delivery?.service_execution_id ? { service_execution_id: delivery.service_execution_id } : {}),
+            ...(lockedRefund ? { refund: { refund_request_id: lockedRefund.refund_request_id, status: lockedRefund.status } } : {}),
+        },
+        instruction,
+        next,
+        recovery: [],
+    };
+}
+function orderPlainResult(result) {
+    return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
 }

package/dist/src/commands/orders.js

@@ -1,22 +1,50 @@
-// List V3 orders visible to the account-scoped session. Requires
-// ITPAY_BEARER_TOKEN to be set to an account-scoped buyer session token.
-// Order-scoped sessions are rejected by the backend with 403 and the
-// CLI surfaces the typed `HttpError` so `main.ts` can render it.
-import { renderOrder } from "../render/output.js";
-import { hintFor } from "../render/status.js";
+import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+const ORDER_STATUSES = new Set([
+    "pending_payment",
+    "paid",
+    "delivery_pending",
+    "delivered",
+    "failed",
+    "partially_refunded",
+    "refunded",
+    "cancelled",
+]);
 export async function runListOrders(backend, config, options) {
     const out = resolveOutput(options.output);
-    if (!config.bearerToken) {
-        throw new Error("ITPAY_BEARER_TOKEN is required to list account orders");
+    if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100) {
+        throw new CommandContractError("limit_invalid", "--limit must be an integer from 1 to 100", "使用 1 到 100 的整数 limit；本次未读取订单列表。", [{ command: "itpay orders --limit 20 --json", reason: "使用默认上限重试" }]);
     }
-    const response = await backend.listAccountOrders(options.limit, options.status, config.bearerToken);
-    if (response.orders.length === 0) {
-        out("no orders found\n");
-        return;
+    if (options.status && !ORDER_STATUSES.has(options.status)) {
+        throw new CommandContractError("order_status_invalid", `unsupported order status: ${options.status}`, "使用订单合同中的有效 status；本次未读取订单列表。", [{ command: "itpay orders --limit 20 --json", reason: "移除状态过滤后重试" }]);
     }
-    for (const order of response.orders) {
-        out(renderOrder(order) + "\n");
-        out(`hint: ${hintFor("order", order.status)}\n\n`);
+    if (!config.bearerToken) {
+        throw new CommandContractError("session_required", "account-scoped Buyer session is required", "订单历史只对网页登录账号开放；不要伪造 Buyer token。Agent 可改为恢复当前设备绑定的 Service Execution。", [{ command: "itpay services list --json", reason: "恢复当前 Agent 设备可见的执行" }]);
     }
+    const response = await backend.listAccountOrders(options.limit, options.status, config.bearerToken);
+    const orders = response.orders.map((order) => ({
+        order_id: order.order_id,
+        ...(order.order_code ? { order_code: order.order_code } : {}),
+        status: order.status,
+        amount: formatMoney(order.amount_minor, order.currency),
+        created_at: order.created_at,
+    }));
+    const latest = orders[0];
+    const envelope = {
+        status: latest ? "listed" : "no_orders",
+        result: { orders },
+        instruction: latest
+            ? "结果按最新到最旧排列；按页面编号、时间和状态选择目标订单，不要假设第一笔就是当前任务。"
+            : "当前账号没有符合条件的订单；不要猜测订单 ID。",
+        next: latest
+            ? { command: `itpay order ${latest.order_id} --json`, reason: "默认读取最新订单" }
+            : null,
+        recovery: latest ? [] : [{ command: "itpay services list --json", reason: "恢复当前 Agent 设备可见的执行" }],
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        output: out,
+        plainResult: orders.map((order) => `${order.order_code ?? order.order_id}: ${order.status} ${order.amount} created=${order.created_at}`),
+    });
 }

package/dist/src/commands/pay.js

@@ -1,26 +1,55 @@
-// Optional CLI helper: only intended for the V3 `payment-intent` flow when
-// the human checkout page is unavailable. The V3 architecture prefers
-// that the human checkout page creates the payment intent, but the CLI
-// still needs an escape hatch for sandbox/manual testing.
-import { operationID } from "../state/config.js";
-import { resolveOutput } from "../render/sink.js";
-export async function runPay(backend, config, options) {
-    const out = resolveOutput(options.output);
-    const request = {
+// Explicit Payment Intent escape hatch. Normal buyers should use the ItPay
+// Checkout page; this command exists for controlled integration recovery.
+import { formatMoney } from "../render/output.js";
+import { writeCommandEnvelope } from "./guidance.js";
+export async function runPay(backend, options) {
+    const intent = await backend.createPaymentIntent(options.checkoutID, {
         payment_method_type: options.method,
-        ...(options.preferredProvider ? { preferred_provider: options.preferredProvider } : {}),
-        ...(options.buyerID ? { buyer_id: options.buyerID } : {}),
+        display_token: options.displayToken,
         ...(options.refreshAction ? { refresh_action: true } : {}),
+    });
+    const envelope = payEnvelope(intent, options);
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+    });
+}
+function payEnvelope(intent, options) {
+    const terminal = ["failed", "expired", "refunded"].includes(intent.status);
+    const verified = intent.status === "verified" || intent.status === "partially_refunded";
+    const handoff = {};
+    if (!terminal && !verified && intent.action?.qr_image_url)
+        handoff.qr_image_url = intent.action.qr_image_url;
+    if (!terminal && !verified && intent.action?.mobile_wallet_url)
+        handoff.mobile_wallet_url = intent.action.mobile_wallet_url;
+    const hasAction = Object.keys(handoff).length > 0;
+    return {
+        status: verified ? "payment_verified" : terminal ? "payment_unavailable" : hasAction ? "payment_action_ready" : "payment_action_pending",
+        result: {
+            checkout_id: options.checkoutID,
+            payment_intent_id: intent.payment_intent_id,
+            payment: verified ? "verified" : intent.status,
+            amount: formatMoney(intent.amount_minor, intent.currency),
+        },
+        ...(hasAction ? { handoff } : {}),
+        instruction: payInstruction(options.host, verified, terminal, hasAction),
+        next: {
+            command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`,
+            reason: verified ? "读取权威订单和履约状态" : "读取同一 Checkout 的权威付款状态",
+        },
+        recovery: [],
     };
-    const intent = await backend.createPaymentIntent(options.checkoutID, request, await operationID(config, `payment.intent:${options.checkoutID}:${options.method}`));
-    out(`payment_intent_id: ${intent.payment_intent_id}\n`);
-    out(`status:            ${intent.status}\n`);
-    out(`method:            ${intent.payment_method_type}\n`);
-    out(`amount:            ${(intent.amount_minor / 100).toFixed(2)} ${intent.currency}\n`);
-    if (intent.action?.qr_image_url) {
-        out(`qr_image_url:      ${intent.action.qr_image_url}\n`);
-    }
-    if (intent.action?.mobile_wallet_url) {
-        out(`mobile_wallet_url: ${intent.action.mobile_wallet_url}\n`);
-    }
+}
+function payInstruction(host, verified, terminal, hasAction) {
+    if (verified)
+        return "付款已确认；不要再次展示付款动作，继续读取同一 Checkout。";
+    if (terminal)
+        return "Payment Intent 已终止；不要自行创建替代付款，回到同一 Checkout 读取恢复方向。";
+    if (!hasAction)
+        return "Payment Intent 尚未返回可展示动作；不要猜测渠道链接，回到同一 Checkout 查询。";
+    if (host === "codex" || host === "claude-code")
+        return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后查询同一 Checkout。";
+    if (host === "terminal")
+        return "这是受控逃生入口；只在用户可见终端展示 handoff，然后查询同一 Checkout。";
+    return "这是受控逃生入口；把 handoff 中的二维码或钱包链接发送到当前会话，然后查询同一 Checkout。";
 }

package/dist/src/commands/readyz.js

@@ -1,8 +1,12 @@
 // Liveness probe. Useful for smoke testing CLI wiring before running `buy`.
-import { renderReady } from "../render/output.js";
-import { resolveOutput } from "../render/sink.js";
+import { writeCommandEnvelope } from "./guidance.js";
 export async function runReadyz(backend, options = {}) {
-    const out = resolveOutput(options.output);
     const response = await backend.readyz();
-    out(renderReady(response) + "\n");
+    writeCommandEnvelope({
+        status: response.status,
+        result: { backend: "available" },
+        instruction: "ItPay 可用，可以读取服务目录。",
+        next: { command: "itpay catalog list", reason: "发现可用服务" },
+        recovery: [],
+    }, options);
 }

package/dist/src/commands/refund.js

@@ -1,20 +1,138 @@
-// Create a V3 refund request. The backend decides policy state and
-// returns the canonical refund status. The CLI never assumes a refund
-// succeeded locally — it always re-reads canonical state.
 import { operationID } from "../state/config.js";
-import { renderRefund } from "../render/output.js";
-import { hintFor } from "../render/status.js";
+import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
+import { writeCommandEnvelope } from "./guidance.js";
 export async function runRefund(backend, config, options) {
+    const reason = options.reason?.trim() || "buyer_requested";
+    const refund = await backend.createRefund(options.orderID, { reason }, config.bearerToken, await operationID(config, `refund.create:${options.orderID}:${reason}`));
+    const envelope = refundStateEnvelope(refund, "requested");
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
+    });
+}
+function refundStateEnvelope(refund, status) {
+    const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
+    let instruction = "退款处理中，交付已冻结；不要 reveal、授权或读取结果。";
+    if (refund.decision_mode === "manual")
+        instruction = "退款已进入人工审核，交付保持冻结；等待服务器决定。";
+    if (!refund.access_locked)
+        instruction = "退款当前未锁定交付；按服务器状态处理，不要自行推断退款结果。";
+    if (refund.status === "succeeded")
+        instruction = "退款已成功；交付永久关闭。";
+    if (refund.status === "cancelled" || refund.status === "rejected")
+        instruction = "退款未执行，交付资格可恢复；旧 grant 不会复活，需要用户重新授权。";
+    return {
+        status,
+        result: {
+            refund_request_id: refund.refund_request_id,
+            order_id: refund.order_id,
+            decision_mode: refund.decision_mode,
+            refund_status: refund.status,
+            consumption_state: refund.consumption_state,
+            ...(refund.failure_class ? { failure_class: refund.failure_class } : {}),
+            access_locked: refund.access_locked,
+            can_cancel: refund.can_cancel,
+        },
+        instruction,
+        next: terminal ? null : { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "跟踪同一退款" },
+        recovery: [],
+    };
+}
+export async function runListRefunds(backend, options) {
     const out = resolveOutput(options.output);
-    const request = {
-        payment_intent_id: options.paymentIntentID,
-        amount_minor: options.amountMinor,
-        currency: options.currency,
-        ...(options.reason ? { reason: options.reason } : {}),
-        ...(options.createdBy ? { created_by: options.createdBy } : {}),
+    const response = await backend.listOrderRefunds(options.orderID);
+    const refunds = response.refunds.map((refund) => ({
+        refund_request_id: refund.refund_request_id,
+        status: refund.status,
+        amount: formatMoney(refund.amount_minor, refund.currency),
+        created_at: refund.created_at,
+    }));
+    const active = refunds.find((refund) => !["succeeded", "failed", "cancelled", "rejected"].includes(refund.status));
+    const selected = active ?? refunds[0];
+    const envelope = {
+        status: selected ? "listed" : "empty",
+        result: { order_id: options.orderID, refunds },
+        instruction: active
+            ? "已有活跃退款；继续跟踪同一笔，不要为该订单重复创建。"
+            : selected
+                ? "结果按最新到最旧排列；按时间和状态选择退款记录，再读取权威详情。"
+                : "该订单没有退款记录；确认用户确实要求退款后再创建。",
+        next: selected
+            ? { command: `itpay refund get ${selected.refund_request_id} --json`, reason: active ? "读取活跃退款" : "读取最新退款" }
+            : { command: `itpay refund create --order ${options.orderID} --json`, reason: "为该订单创建退款" },
+        recovery: [],
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        output: out,
+        plainResult: [
+            `order_id: ${options.orderID}`,
+            ...refunds.map((refund) => `${refund.refund_request_id}: ${refund.status} ${refund.amount} created=${refund.created_at}`),
+        ],
+    });
+}
+export async function runGetRefund(backend, refundID, options = {}) {
+    const envelope = refundStateEnvelope(await backend.getRefund(refundID), "shown");
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
+    });
+}
+export async function runCancelRefund(backend, refundID, reason, options = {}) {
+    const refund = await backend.cancelRefund(refundID, reason?.trim() || "buyer_cancelled");
+    const envelope = {
+        status: "cancelled",
+        result: {
+            refund_request_id: refund.refund_request_id,
+            order_id: refund.order_id,
+            access_locked: refund.access_locked,
+        },
+        instruction: "退款已取消；如需交付，重新进入订单并取得新的授权。",
+        next: { command: `itpay order ${refund.order_id} --json`, reason: "确认订单访问状态" },
+        recovery: [],
     };
-    const refund = await backend.createRefund(options.orderID, request, await operationID(config, `refund.create:${options.orderID}:${options.paymentIntentID}:${options.amountMinor}:${options.currency}`));
-    out(renderRefund(refund) + "\n");
-    out(`hint: ${hintFor("refund", refund.status)}\n`);
+    writeRefundEnvelope(envelope, options);
+}
+export async function runWatchRefund(backend, refundID, options = {}) {
+    const intervalSeconds = options.intervalSeconds ?? 2;
+    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1)
+        throw new Error("--interval must be at least 1 second");
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)
+        throw new Error("--timeout must be a positive number");
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let refund;
+    for (;;) {
+        refund = await backend.getRefund(refundID);
+        if (["succeeded", "failed", "cancelled", "rejected"].includes(refund.status)) {
+            writeRefundEnvelope(refundStateEnvelope(refund, "watch_complete"), options);
+            return;
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(intervalSeconds * 1000, remaining)));
+    }
+    writeRefundEnvelope({
+        status: "watch_timeout",
+        result: {
+            refund_request_id: refund.refund_request_id,
+            last_status: refund.status,
+            access_locked: refund.access_locked,
+            can_cancel: refund.can_cancel,
+        },
+        instruction: "退款仍在处理，稍后继续跟踪同一退款；不要重复申请。",
+        next: { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "恢复轮询" },
+        recovery: [],
+    }, options);
+}
+function writeRefundEnvelope(envelope, options) {
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
+    });
 }