@itpay/cli 2.1.17 → 2.1.18

package/dist/src/commands/checkout.js

@@ -5,11 +5,40 @@ import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
 import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
+import { openInSystemBrowser } from "../render/browser.js";
+import { hostCapabilities, normalizeViewer } from "../state/client_context.js";
 import { DEFAULT_BASE_URL } from "../state/config.js";
 import { buildCheckoutQRPlan } from "./buy.js";
 import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
-import { writeCommandEnvelope } from "./guidance.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { resolvePresentation, resolveRelay } from "./presentation.js";
 export async function runCheckoutPresentation(backend, options) {
+    const present = options.present;
+    if (present !== undefined && !["auto", "browser", "image", "link", "none"].includes(present)) {
+        throw new CommandContractError("present_invalid", `--present must be one of auto|browser|image|link|none`, "使用支持的展示方式；未知参数已被拒绝。", []);
+    }
+    const relayRequested = Boolean(options.relayOption || options.confirmRelay || options.requestKey || options.relayStatus);
+    if (relayRequested && options.present && options.present !== "none") {
+        throw new CommandContractError("present_relay_conflict", "--present and --relay-* options are mutually exclusive", "展示和消息转发二选一；不要在同一次调用中同时开页面和发消息。", []);
+    }
+    if (options.noOpen && options.present === "browser") {
+        throw new CommandContractError("present_conflict", "--present browser conflicts with --no-open", "--no-open 与浏览器展示冲突；改用 --present link 或 image。", []);
+    }
+    if (options.relayStatus) {
+        // Read-only relay status. The backend exposes no relay routes yet, so the
+        // honest answer is unavailable — never a resend, never a guessed state.
+        writeCommandEnvelope({
+            status: "relay_unavailable",
+            result: { relay_id: options.relayStatus },
+            instruction: "当前 Backend 未提供消息转发状态查询；不要重发。读取原订单/Checkout 状态核对。",
+            next: { command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`, reason: "读取原 Checkout 当前状态" },
+            recovery: [],
+        }, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
     const locale = normalizeCardLocale(options.locale);
     const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken, locale === "en" ? locale : undefined);
     const host = options.host ?? "terminal";
@@ -56,12 +85,78 @@ export async function runCheckoutPresentation(backend, options) {
     if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
         plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
     }
+    // W5: deterministic presentation plan — business state first, then declared
+    // capabilities. `present` is the explicit display request; without it (or
+    // under --json alone) nothing opens.
+    // An explicit --viewer (including "unknown") wins over the host default.
+    const viewer = options.viewer ? normalizeViewer(options.viewer) : (host === "terminal" ? "desktop" : "unknown");
+    const locality = ["terminal", "codex", "claude-code"].includes(host) ? "same_device" : "unknown";
+    const decision = resolvePresentation({
+        business: {
+            commerce_policy: "allowed",
+            payment_state: "unpaid",
+            quote_valid: presentation.rail_quote?.expires_at
+                ? Date.parse(presentation.rail_quote.expires_at) > Date.now()
+                : true,
+            amount_minor: presentation.checkout.amount_minor,
+        },
+        viewer,
+        executor_locality: locality,
+        capabilities: hostCapabilities(host),
+        ...(explicitChoiceFor(options.present) ? { explicit_choice: explicitChoiceFor(options.present) } : {}),
+    });
+    const presentationResult = {
+        recommended: decision.recommended,
+        alternatives: decision.alternatives,
+        ...(decision.blocker ? { blocker: decision.blocker } : {}),
+    };
+    let dispatch = { status: "not_attempted" };
+    // Explicit --present browser may open even under --json (the flag IS the
+    // display request); --present auto under --json stays a plan and never opens.
+    const browserRequested = options.present === "browser"
+        || (options.present === "auto" && !options.jsonOutput && !options.noOpen && decision.recommended === "open_system_browser");
+    if (browserRequested && !options.noOpen && process.env.ITPAY_NO_BROWSER !== "1") {
+        const target = decision.recommended === "open_embedded_browser" ? decision.recommended : "open_system_browser";
+        dispatch = await openInSystemBrowser(checkoutURL, options.baseURL);
+        presentationResult.dispatched = { route: target, observation: dispatch.status };
+        // Dispatch proves the request was accepted — nothing about visibility.
+        if (dispatch.status === "dispatch_accepted") {
+            envelope.instruction += " 已发起在本机浏览器打开官方确认页；只有用户确认看到页面才视为已显示，没看到时改发链接。";
+        }
+        else {
+            envelope.instruction += " 浏览器打开未成功；按 handoff 链接展示，不要重复尝试同一方式。";
+        }
+    }
+    if (relayRequested) {
+        presentationResult.relay = resolveRelay({
+            ...(options.relayOption ? { relayOption: options.relayOption } : {}),
+            ...(options.confirmRelay ? { confirmRelay: options.confirmRelay } : {}),
+            ...(options.requestKey ? { requestKey: options.requestKey } : {}),
+            backendCapability: false,
+        });
+        envelope.instruction += " 消息转发当前不可用；不要声称已发送，改用现有官方入口展示。";
+    }
+    envelope.result = { ...envelope.result, presentation: presentationResult };
+    envelope.communication = {
+        schema_version: "itpay.communication.v1",
+        tell: decision.communication.tell,
+        wait_for: decision.communication.wait_for,
+        must_convey: decision.communication.must_convey,
+    };
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
         ...(options.output ? { output: options.output } : {}),
         plainResult,
     });
 }
+function explicitChoiceFor(present) {
+    switch (present) {
+        case "browser": return "open_system_browser";
+        case "link": return "show_link";
+        case "image": return "show_official_image";
+        default: return undefined;
+    }
+}
 function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, agentType, target) {
     const platform = platformKeyForHost(plan.host);
     const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
@@ -104,13 +199,25 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
                     })),
                 } } : {}),
             ...(railPassengersPending ? { rail_passengers_confirmed: false } : {}),
+            ...(presentation.payment_deadline_at ? { payment_deadline_at: presentation.payment_deadline_at } : {}),
+            ...(typeof presentation.payment_remaining_seconds === "number"
+                ? { payment_remaining_seconds: presentation.payment_remaining_seconds }
+                : {}),
+            ...(presentation.server_now ? { server_now: presentation.server_now } : {}),
+            ...(presentation.verified_sms_contact ? { verified_sms_contact: presentation.verified_sms_contact } : {}),
+            ...(presentation.account_phone_option?.masked_recipient
+                ? { account_phone_option: { masked_recipient: presentation.account_phone_option.masked_recipient } }
+                : {}),
         },
         handoff: presentationHandoff.handoff,
         instruction: railPassengersPending
             ? `${presentationHandoff.instruction} 请用户在受保护网页填写乘车人并确认报价；姓名、证件和手机号只在网页填写，不要贴到对话中。座位偏好仅为购票请求、购票时才提交给供应商且不保证满足；无法逐人提交的偏好将自动分配座位，以实际出票为准。`
             : presentationHandoff.instruction,
         next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
-        recovery: [],
+        recovery: [{
+                command: nextCommand,
+                reason: "付款时限由服务端统一确定，刷新不会延长；到期未支付自动取消后须重新核价下单，不要重发旧付款动作",
+            }],
     };
 }
 function terminalCheckoutEnvelope(presentation) {

package/dist/src/commands/guidance.js

@@ -60,6 +60,12 @@ export function writeCommandEnvelope(value, options = {}) {
     out(`instruction: ${qualified.instruction}\n`);
     if (qualified.next)
         out(`next: ${qualified.next.command}\n`);
+    if ("interaction" in qualified && qualified.interaction) {
+        out(`interaction: ${JSON.stringify(qualified.interaction)}\n`);
+    }
+    if ("communication" in qualified && qualified.communication) {
+        out(`communication: ${JSON.stringify(qualified.communication)}\n`);
+    }
     if (qualified.recovery.length > 0) {
         out("recovery:\n");
         for (const action of qualified.recovery) {
@@ -71,6 +77,10 @@ export function writeCommandEnvelope(value, options = {}) {
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
+        result: qualifyCommandsDeep(value.result, agentType),
+        ...("handoff" in value && value.handoff ? { handoff: qualifyCommandsDeep(value.handoff, agentType) } : {}),
+        ...("interaction" in value && value.interaction ? { interaction: qualifyCommandsDeep(value.interaction, agentType) } : {}),
+        ...("communication" in value && value.communication ? { communication: qualifyCommandsDeep(value.communication, agentType) } : {}),
         next: value.next ? { ...value.next, command: qualifyBackendCommand(qualifyItPayCommand(value.next.command, agentType)) } : null,
         recovery: value.recovery.map((action) => ({
             ...action,
@@ -78,6 +88,23 @@ function qualifyEnvelope(value, agentType) {
         })),
     };
 }
+// Every `itpay ` command string anywhere in the envelope — result fields,
+// interaction recipes/templates, available_actions — keeps the same Agent
+// Type / Backend qualification as top-level next/recovery. Instruction prose
+// never starts with "itpay " so prose stays untouched.
+function qualifyCommandsDeep(value, agentType) {
+    if (typeof value === "string") {
+        return value.startsWith("itpay ")
+            ? qualifyBackendCommand(qualifyItPayCommand(value, agentType))
+            : value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => qualifyCommandsDeep(item, agentType));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, qualifyCommandsDeep(item, agentType)]));
+    }
+    return value;
+}
 export function errorRecoveryActions(error) {
     if (!(error instanceof HttpError))
         return [];

package/dist/src/commands/order.js

@@ -39,7 +39,10 @@ function orderEnvelope(order, delivery, lockedRefund) {
         instruction = "先告诉用户这笔订单已经取消，没有可继续的付款或交付；不要创建替代订单，除非用户另行提出新的购买。";
     }
     else if (order.status === "pending_payment") {
-        instruction = "先告诉用户订单正在等待付款，超时未支付会被自动取消；不要创建替代订单，也不要重复发起支付授权。";
+        const remaining = typeof order.payment_remaining_seconds === "number" && order.payment_remaining_seconds <= 0;
+        instruction = remaining
+            ? "先告诉用户这笔订单的付款时限已到，可能已被取消；如刚完成付款请说明系统正在核对到账，不要重复支付；否则引导用户重新核价下单，刷新不会延长付款期限。"
+            : `先告诉用户订单正在等待付款${order.payment_deadline_at ? `，付款截止时间为 ${order.payment_deadline_at}` : ""}，超时未支付会被自动取消；不要创建替代订单，也不要重复发起支付授权。`;
         next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单支付状态" };
     }
     else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
@@ -53,6 +56,10 @@ function orderEnvelope(order, delivery, lockedRefund) {
             ...(order.order_code ? { order_code: order.order_code } : {}),
             amount: formatMoney(order.amount_minor, order.currency),
             ...(order.payment_deadline_at ? { payment_deadline_at: order.payment_deadline_at } : {}),
+            ...(typeof order.payment_remaining_seconds === "number"
+                ? { payment_remaining_seconds: order.payment_remaining_seconds }
+                : {}),
+            ...(order.server_now ? { server_now: order.server_now } : {}),
             ...(delivery ? { delivery_mode: delivery.delivery_mode } : {}),
             access_locked: Boolean(lockedRefund),
             ...(delivery?.service_execution_id ? { service_execution_id: delivery.service_execution_id } : {}),

package/dist/src/commands/presentation.js

@@ -0,0 +1,153 @@
+// Deterministic PresentationResolver (spec 03 §5): business state first, then
+// declared viewer/executor capabilities, then the user's explicit choice and
+// failure history. Output is one recommended route plus at most two feasible
+// alternatives — never a parallel burst of open + send.
+//
+// Routes are abstract kinds; the caller maps them to concrete handoff fields
+// (url, card image, qr). "unknown" capability answers are never treated as
+// "yes", and a route that already failed is not retried without a new reason.
+const yes = (value) => value === "yes";
+export function resolvePresentation(input) {
+    const blocker = businessBlocker(input.business);
+    if (blocker) {
+        return {
+            blocker,
+            recommended: "none",
+            alternatives: [],
+            routes: [],
+            communication: communicationForBlocker(blocker),
+        };
+    }
+    const caps = input.capabilities;
+    const local = input.executor_locality === "same_device";
+    const routes = [];
+    if (input.viewer === "desktop") {
+        if (yes(caps.user_visible_browser))
+            routes.push("open_embedded_browser");
+        if (local && yes(caps.system_browser))
+            routes.push("open_system_browser");
+        if (yes(caps.clickable_https))
+            routes.push("show_link");
+        if (yes(caps.image_visible))
+            routes.push("show_official_image");
+        if (yes(caps.user_visible_terminal) && yes(caps.other_device_scan))
+            routes.push("show_terminal_qr");
+    }
+    else if (input.viewer === "mobile") {
+        if (yes(caps.native_url_button))
+            routes.push("show_mobile_button");
+        if (yes(caps.clickable_https))
+            routes.push("show_mobile_link");
+        if (yes(caps.user_visible_browser))
+            routes.push("open_user_browser");
+        if (local && yes(caps.system_browser))
+            routes.push("open_system_browser");
+        // QR never targets the same phone the human is holding.
+    }
+    else {
+        if (yes(caps.clickable_https))
+            routes.push("show_link");
+        if (routes.length === 0 && yes(caps.image_visible))
+            routes.push("ask_viewer_device");
+    }
+    // Relay is a consented fallback, not a presentation route — it only appears
+    // when an issued, verified contact option exists.
+    if (input.verified_phone_option === true)
+        routes.push("request_sms_consent");
+    if (input.verified_email_option === true)
+        routes.push("request_email_consent");
+    routes.push("show_copyable_entry");
+    const failed = new Set(input.failed_routes ?? []);
+    const feasible = routes.filter((route) => !failed.has(route));
+    const chosen = input.explicit_choice;
+    if (chosen && feasible.includes(chosen)) {
+        feasible.splice(feasible.indexOf(chosen), 1);
+        feasible.unshift(chosen);
+    }
+    const ranked = feasible.length > 0 ? feasible : ["show_copyable_entry"];
+    const [recommended, ...alternatives] = ranked;
+    return {
+        recommended: recommended,
+        alternatives: alternatives.slice(0, 2),
+        routes: ranked.slice(0, 3),
+        communication: {
+            tell: tellForRoute(recommended),
+            wait_for: "人完成官方页面上的确认/付款；dispatch 成功不等于已付款",
+            must_convey: [
+                "真实金额与订单归属以 owner 返回为准",
+                "已发起打开不代表已显示或已付款",
+                ...(input.business.amount_minor === undefined ? ["金额尚未确认，不称锁价或最终价"] : []),
+            ],
+        },
+    };
+}
+function businessBlocker(business) {
+    if (business.commerce_policy === "blocked")
+        return "policy_blocked";
+    if (business.commerce_policy === "review")
+        return "policy_review_required";
+    if (business.payment_state !== "unpaid")
+        return "read_same_order";
+    if (business.quote_valid !== true)
+        return "recover_expired_quote";
+    if (typeof business.amount_minor !== "number" || business.amount_minor <= 0)
+        return "read_same_order";
+    return undefined;
+}
+function communicationForBlocker(blocker) {
+    switch (blocker) {
+        case "policy_blocked":
+            return { tell: "该服务在当前宿主/准入策略下不可用，不绕外链或消息逃避。", wait_for: "用户更换获准渠道", must_convey: ["技术与准入分开说明"] };
+        case "policy_review_required":
+            return { tell: "当前准入策略要求复核，不发起展示动作。", wait_for: "准入复核结果", must_convey: ["不是业务失败"] };
+        case "read_same_order":
+            return { tell: "该订单不处于待付款状态；先读取原订单，不展示付款入口、不新建支付动作。", wait_for: "原订单状态", must_convey: ["用户声称已付仍须核对原单"] };
+        case "recover_expired_quote":
+            return { tell: "报价已失效或过期；读取原执行由 owner 重新核价，不向人收取旧金额。", wait_for: "新的 owner 报价", must_convey: ["旧二维码/入口不再有效"] };
+    }
+}
+function tellForRoute(route) {
+    switch (route) {
+        case "open_embedded_browser":
+        case "open_system_browser":
+        case "open_user_browser":
+            return "已发起打开官方页面；若用户未看到，换一种方式，仍是同一订单。";
+        case "show_link":
+        case "show_mobile_link":
+            return "把官方链接作为可点击入口交给用户。";
+        case "show_mobile_button":
+            return "展示原生 URL 按钮直达官方页。";
+        case "show_official_image":
+            return "展示官方图片入口（另一台设备用）。";
+        case "show_terminal_qr":
+            return "展示二维码供另一台设备扫码。";
+        case "request_sms_consent":
+            return "建议把订单入口发到已验证的手机尾号；征得明确同意后发送一条。";
+        case "request_email_consent":
+            return "建议把订单入口发到已验证的邮箱；征得明确同意后发送一封。";
+        case "ask_viewer_device":
+            return "无法判断用户在看哪种设备；最多澄清一次设备类型。";
+        case "show_copyable_entry":
+            return "给出可复制的官方入口并说明如何打开。";
+        default:
+            return "当前无可行展示方式；只说明状态，等待用户给出可用渠道。";
+    }
+}
+export function resolveRelay(input) {
+    if (!input.backendCapability) {
+        return {
+            kind: "unavailable",
+            reason: "当前 Backend 未提供消息转发（relay）能力；改用官方链接或二维码呈现，不得伪造发送结果。",
+        };
+    }
+    if (!input.relayOption) {
+        return { kind: "invalid", reason: "--relay-option 必须是服务端已签发的脱敏联系人引用。" };
+    }
+    if (!input.requestKey || !input.requestKey.trim()) {
+        return { kind: "invalid", reason: "--request-key 是必填的稳定幂等键。" };
+    }
+    if (!input.confirmRelay) {
+        return { kind: "needs_consent" };
+    }
+    return { kind: "unavailable", reason: "relay 后端未启用。" };
+}