@itpay/cli 2.0.7 → 2.0.9

package/README.md

@@ -11,7 +11,7 @@ itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional test or local environment.
+The default API is temporarily `https://dev.itpay.ai` during the 2.0.9 beta. Set `ITPAY_BACKEND_URL` only for an intentional override.
 
 ## Output Contract
 

package/dist/src/commands/compatibility.js

@@ -0,0 +1,32 @@
+import { HttpError } from "../client/http.js";
+import { API_CONTRACT_REVISION, CLI_VERSION } from "../state/config.js";
+export async function requirePlatformCompatibility(backend) {
+    const platform = await backend.compatibility();
+    const compatible = platform.api_contract_revision === API_CONTRACT_REVISION
+        && compareVersions(CLI_VERSION, platform.minimum_cli_version) >= 0
+        && versionMajor(CLI_VERSION) <= platform.maximum_cli_major;
+    if (compatible)
+        return;
+    throw new HttpError(426, {
+        code: "client_upgrade_required",
+        message: `CLI ${CLI_VERSION} contract ${API_CONTRACT_REVISION} is incompatible with platform ${platform.platform_revision} contract ${platform.api_contract_revision} (minimum CLI ${platform.minimum_cli_version}, maximum major ${platform.maximum_cli_major})`,
+    }, "CLI is incompatible with the active ItPay platform release");
+}
+function compareVersions(left, right) {
+    const a = versionParts(left);
+    const b = versionParts(right);
+    if (!a || !b)
+        return -1;
+    for (let index = 0; index < 3; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return 0;
+}
+function versionMajor(version) {
+    return versionParts(version)?.[0] ?? Number.MAX_SAFE_INTEGER;
+}
+function versionParts(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}

package/dist/src/main.js

@@ -10,6 +10,7 @@ import { HttpError } from "./client/http.js";
 import { runReadyz } from "./commands/readyz.js";
 import { runBuy } from "./commands/buy.js";
 import { runCatalogList } from "./commands/catalog.js";
+import { requirePlatformCompatibility } from "./commands/compatibility.js";
 import { runCheckoutPresentation } from "./commands/checkout.js";
 import { runPay } from "./commands/pay.js";
 import { runOrder } from "./commands/order.js";
@@ -94,6 +95,7 @@ function reportCLIError(error, contract) {
         error.code === "client_compatibility_headers_required" ||
         error.code === "platform_release_unavailable" ||
         (error.status === 404 && error.code === "unknown_error"));
+    const backendInternal = error instanceof HttpError && error.status === 500 && error.code === "internal_error";
     const deviceRecovery = deviceError ? [{
             command: "itpay skill show itpay-buyer --json",
             reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
@@ -119,10 +121,12 @@ function reportCLIError(error, contract) {
                 message: error instanceof Error ? error.message : String(error),
             },
             instruction: incompatible
-                ? "当前 Backend 不支持本 CLI 所需的交易合同。立即停止；不要尝试 services quote、services checkout、cart、buy 或 pay 作为替代路径。需要先同步 CLI 与 Backend 版本。"
-                : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                ? "立即向用户报告 error.message 并结束本次任务。不要运行任何其他 itpay、npm、which、device、docs、cart、orders 或 services 命令；不要寻找、安装或切换其他 CLI。只有运营明确提供兼容 CLI 后，才能在新的任务中重新开始。"
+                : backendInternal
+                    ? "Backend 内部故障；立即停止并向用户报告。不要重试、检查或删除 Device 身份、创建替代 Execution、切换 Backend，或尝试 quote、checkout、cart、buy、pay 等付费路径。"
+                    : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
-            recovery: incompatible ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+            recovery: incompatible || backendInternal ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
             output: (text) => { process.stderr.write(text); },
@@ -159,6 +163,7 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
+        await requirePlatformCompatibility(backend);
         await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
     }
     catch (error) {
@@ -254,8 +259,19 @@ program
     .option("--json", "output JSON instead of terminal text")
     .action(async (options) => {
     const config = loadConfig();
-    const session = CartSession.loadFromFile(cartSessionPath(), config.checkoutCurrency);
-    runNext(session, { jsonOutput: Boolean(options.json) });
+    try {
+        await requirePlatformCompatibility(newBackendClient(config));
+        const session = CartSession.loadFromFile(cartSessionPath(), config.checkoutCurrency);
+        runNext(session, { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "next_unavailable",
+            instruction: "Backend 合同可用后再读取本地恢复句柄；不要根据旧句柄继续交易。",
+            recovery: [],
+        });
+    }
 });
 // --- catalog --------------------------------------------------------------
 const catalogCmd = program.command("catalog").description("Browse V3 service catalog");
@@ -266,6 +282,7 @@ catalogCmd
     .action(async (options) => {
     const backend = newBackendClient(loadConfig());
     try {
+        await requirePlatformCompatibility(backend);
         await runCatalogList(backend, { jsonOutput: Boolean(options.json) });
     }
     catch (error) {

package/dist/src/state/config.js

@@ -9,9 +9,9 @@ import { BackendClient } from "../client/backend.js";
 import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
-export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.7";
-export const API_CONTRACT_REVISION = "sha256:47d42ab7bbe74a806b9ec989384b28ad715ffcf05a5eb913449b8bc224ffcf49";
+export const DEFAULT_BASE_URL = "https://dev.itpay.ai";
+export const CLI_VERSION = "2.0.9";
+export const API_CONTRACT_REVISION = "sha256:4ad3ff2565cc265a8c98dec3bb92be1cbfee4d37cb78756d929c78ef134a7bca";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/docs/agent/buyer/install-and-setup.json

@@ -32,7 +32,7 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
-    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
+    "Use the default https://dev.itpay.ai beta API unless an environment override is deliberate.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
     "One local private key is reused, but each exact Backend API base URL has its own server registration and quota lineage.",
     "Within one Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",

package/docs/cli-reference/commands/install.md

@@ -29,7 +29,7 @@ itpay install [target] [--json]
   "result": {
     "agent_type": "codex-desktop",
     "default_host": "codex",
-    "default_api": "https://app.itpay.ai",
+    "default_api": "https://dev.itpay.ai",
     "install_command": "npm install -g @itpay/cli"
   },
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {