@itpay/cli 0.1.6 → 0.1.8

package/bin/itp

@@ -8,7 +8,6 @@ import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
 
-const VERSION = "0.1.5";
 const DEFAULT_API_BASE = process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || "https://dev.api.itpay.ai";
 const CONFIG_DIR = path.join(os.homedir(), ".itp");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
@@ -19,6 +18,7 @@ const LOCK_PATH = path.join(CONFIG_DIR, "state.lock");
 const CLI_FILE = fileURLToPath(import.meta.url);
 const CLI_DIR = path.dirname(CLI_FILE);
 const PACKAGE_ROOT = path.dirname(CLI_DIR);
+const VERSION = packageVersion();
 
 main().catch((error) => {
   outputError(error);
@@ -213,13 +213,14 @@ async function main() {
           "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
           "buyer deliveries list --checkout <checkout_id> --json",
           "buyer deliveries show <delivery_id> --checkout <checkout_id> --json",
+          "buyer refund create --order <order_id> --amount-minor 1000 --currency CNY --reason buyer_requested --json",
+          "buyer refund list --order <order_id> --json",
+          "buyer refund show <refund_id> --json",
+          "buyer refund cancel <refund_id> --reason buyer_changed_mind --json",
           "buyer vault grants list --checkout <checkout_id> --json",
           "buyer vault grants read <agent_read_grant_id> --json",
           "buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
           "account login-link --json",
-          "ops sandbox worker run-once --json",
-          "ops sandbox recover-alipay-once --json",
-          "ops sandbox payment query <payment_intent_id> --json",
           "status --json",
           "docs list --role buyer --json",
           "docs show quickstart --role buyer --json",
@@ -842,6 +843,58 @@ async function buyer(command, rest, flags) {
       return;
     }
   }
+  if (command === "refund") {
+    if (subcommand === "create") {
+      const orderID = flags.order || flags.order_id || positional(rest, 1);
+      if (!orderID) throw new Error("order_id is required");
+      const refund = await createBuyerRefund(orderID, flags);
+      if (refund.status === "policy_risk_confirmation_required") {
+        output(buyerRunOutput(refund));
+        return;
+      }
+      output(buyerRunOutput({
+        status: refund.status || "refund_requested",
+        refund,
+        refund_eligibility: refund.refund_eligibility || null,
+        agent_next_actions: ["watch_refund_status", "explain_refund_policy"]
+      }));
+      return;
+    }
+    if (subcommand === "list") {
+      const orderID = flags.order || flags.order_id || positional(rest, 1);
+      if (!orderID) throw new Error("order_id is required");
+      const refunds = await listBuyerRefunds(orderID, flags);
+      output(buyerRunOutput({
+        status: "refunds",
+        order_id: orderID,
+        ...refunds,
+        agent_next_actions: ["show_refund_status"]
+      }));
+      return;
+    }
+    if (subcommand === "show") {
+      const refundID = flags.refund || flags.refund_id || positional(rest, 1);
+      if (!refundID) throw new Error("refund_id is required");
+      const refund = await getBuyerRefund(refundID, flags);
+      output(buyerRunOutput({
+        status: refund.status || "refund",
+        refund,
+        agent_next_actions: ["show_refund_status"]
+      }));
+      return;
+    }
+    if (subcommand === "cancel") {
+      const refundID = flags.refund || flags.refund_id || positional(rest, 1);
+      if (!refundID) throw new Error("refund_id is required");
+      const refund = await cancelBuyerRefund(refundID, flags);
+      output(buyerRunOutput({
+        status: refund.status || "refund_canceled",
+        refund,
+        agent_next_actions: ["show_refund_status", "claim_delivery_if_still_needed"]
+      }));
+      return;
+    }
+  }
   if (command === "vault") {
     if (subcommand === "grants") {
       const action = rest[1] && !String(rest[1]).startsWith("--") ? rest[1] : "list";
@@ -966,6 +1019,12 @@ function booleanFlag(value) {
   throw new Error(`invalid boolean flag value: ${value}`);
 }
 
+function intFlag(value, name) {
+  const number = Number(value);
+  if (!Number.isInteger(number)) throw new Error(`${name} must be an integer`);
+  return number;
+}
+
 async function ops(command, rest, flags) {
   if (command !== "sandbox") throw new Error(`unknown ops command: ${command || ""}`);
   const area = rest[0];
@@ -984,6 +1043,75 @@ async function ops(command, rest, flags) {
     output(await coreApi(`/v1/payment-intents/${encodeURIComponent(paymentIntentID)}/alipay-sandbox-query`, { method: "POST", ops: true }, flags));
     return;
   }
+  if (area === "refund") {
+    const refundID = flags.refund || flags.refund_id || positional(rest, 2);
+    if (!refundID) throw new Error("refund_id is required");
+    if (action === "show") {
+      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}`, { method: "GET", ops: true }, flags));
+      return;
+    }
+    if (action === "approve" || action === "reject") {
+      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}/${action}`, {
+        method: "POST",
+        ops: true,
+        idempotencyKey: flags.idempotency_key || `idem_cli_refund_${action}_${refundID}`,
+        body: {
+          reason_code: flags.reason || flags.reason_code || (action === "approve" ? "approved_by_ops" : "not_eligible"),
+          note: flags.note || ""
+        }
+      }, flags));
+      return;
+    }
+    if (action === "execute") {
+      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}/execute`, {
+        method: "POST",
+        ops: true,
+        idempotencyKey: flags.idempotency_key || `idem_cli_refund_execute_${refundID}`
+      }, flags));
+      return;
+    }
+  }
+  if (area === "ledger" && action === "entries") {
+    const params = new URLSearchParams();
+    if (flags.order || flags.order_id) params.set("order_id", String(flags.order || flags.order_id));
+    if (flags.refund || flags.refund_id) params.set("refund_id", String(flags.refund || flags.refund_id));
+    if (flags.payment_intent || flags.payment_intent_id) params.set("payment_intent_id", String(flags.payment_intent || flags.payment_intent_id));
+    if ([...params.keys()].length === 0) {
+      throw new Error("ledger filter is required: use --order, --refund, or --payment-intent");
+    }
+    output(await coreApi(`/v1/sandbox/ops/ledger/entries${queryString(params)}`, { method: "GET", ops: true }, flags));
+    return;
+  }
+  if (area === "reconciliation") {
+    if (action === "run") {
+      output(await coreApi("/v1/sandbox/ops/reconciliation-runs", {
+        method: "POST",
+        ops: true,
+        idempotencyKey: flags.idempotency_key || `idem_cli_reconciliation_${cryptoRandom()}`,
+        body: {
+          reconciliation_run_id: flags.reconciliation_run_id || flags.run_id || "",
+          status: flags.status || "matched",
+          expected_amount_minor: intFlag(flags.expected_amount_minor || flags.expected || 0, "expected_amount_minor"),
+          observed_amount_minor: intFlag(flags.observed_amount_minor || flags.observed || 0, "observed_amount_minor"),
+          currency: flags.currency || "CNY",
+          raw_statement_ref: flags.raw_statement_ref || flags.statement_ref || ""
+        }
+      }, flags));
+      return;
+    }
+    if (action === "show") {
+      const runID = flags.reconciliation_run_id || flags.run_id || positional(rest, 2);
+      if (!runID) throw new Error("reconciliation_run_id is required");
+      output(await coreApi(`/v1/sandbox/ops/reconciliation-runs/${encodeURIComponent(runID)}`, { method: "GET", ops: true }, flags));
+      return;
+    }
+  }
+  if (area === "settlement" && action === "show") {
+    const settlementBatchID = flags.settlement_batch || flags.settlement_batch_id || positional(rest, 2);
+    if (!settlementBatchID) throw new Error("settlement_batch_id is required");
+    output(await coreApi(`/v1/sandbox/ops/settlement-batches/${encodeURIComponent(settlementBatchID)}`, { method: "GET", ops: true }, flags));
+    return;
+  }
   throw new Error(`unknown ops sandbox command: ${rest.join(" ")}`);
 }
 
@@ -1462,6 +1590,67 @@ async function getBuyerCheckout(checkoutID, flags = {}) {
   return await coreApi(`/v1/checkouts/${encodeURIComponent(checkoutID)}`, { method: "GET" }, flags);
 }
 
+async function createBuyerRefund(orderID, flags = {}) {
+  if (flags.amount !== undefined) {
+    throw new Error("use --amount-minor for refund amount");
+  }
+  if (flags.refund_scope && flags.refund_scope !== "order") {
+    throw new Error("unsupported_refund_scope");
+  }
+  const order = await getBuyerOrderDetail(orderID, flags);
+  const eligibility = order.refund_eligibility || order.order_detail?.refund_eligibility || null;
+  if (eligibility && eligibility.likely_refundable === false && !booleanFlag(flags.confirm_policy_risk || false)) {
+    return {
+      status: "policy_risk_confirmation_required",
+      order_id: orderID,
+      refund_eligibility: eligibility,
+      agent_next_actions: [
+        "explain_refund_policy",
+        "ask_human_to_confirm_policy_risk",
+        `retry_with_${cliCommand("buyer", "refund", "create", orderID, "--confirm-policy-risk", "true", "--json")}`
+      ],
+      submitted: false
+    };
+  }
+  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}/refunds`, {
+    method: "POST",
+    headers: { "X-ItPay-Client-Surface": "cli" },
+    idempotencyKey: flags.idempotency_key || `idem_cli_refund_create_${orderID}`,
+    body: {
+      refund_scope: flags.refund_scope || "order",
+      order_line_item_ids: csvValues(flags.order_line_item_ids || flags.line_ids || flags.line_id),
+      amount_minor: intFlag(flags.amount_minor, "amount_minor"),
+      currency: flags.currency || "CNY",
+      reason_code: flags.reason || flags.reason_code || "buyer_requested",
+      reason_note: flags.note || flags.reason_note || ""
+    }
+  }, flags);
+}
+
+async function getBuyerOrderDetail(orderID, flags = {}) {
+  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}`, { method: "GET" }, flags);
+}
+
+async function listBuyerRefunds(orderID, flags = {}) {
+  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}/refunds`, { method: "GET" }, flags);
+}
+
+async function getBuyerRefund(refundID, flags = {}) {
+  return await coreApi(`/v1/me/refunds/${encodeURIComponent(refundID)}`, { method: "GET" }, flags);
+}
+
+async function cancelBuyerRefund(refundID, flags = {}) {
+  return await coreApi(`/v1/me/refunds/${encodeURIComponent(refundID)}/cancel`, {
+    method: "POST",
+    headers: { "X-ItPay-Client-Surface": "cli" },
+    idempotencyKey: flags.idempotency_key || `idem_cli_refund_cancel_${refundID}`,
+    body: {
+      reason_code: flags.reason || flags.reason_code || "buyer_changed_mind",
+      reason_note: flags.note || flags.reason_note || ""
+    }
+  }, flags);
+}
+
 async function getBuyerPaymentIntent(paymentIntentID, flags = {}) {
   return await coreApi(`/v1/payment-intents/${encodeURIComponent(paymentIntentID)}`, { method: "GET" }, flags);
 }
@@ -3233,15 +3422,6 @@ async function renderHumanAction(action, flags = {}) {
         return { rendered: false, mode: "json-local-qr", outputs: [localPath] };
       }
     }
-    if (!qrImageURL && shouldGenerateLocalQRFromActionURL(action) && shouldPrepareLocalQRForJSON(mode, flags, action)) {
-      const localPath = await prepareGeneratedActionQRFile(action, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
-      if (localPath) {
-        attachAgentGeneratedQRImage(action, localPath);
-        annotateHumanActionPresentation(action, "");
-        persistHumanAction(action, flags);
-        return { rendered: false, mode: "json-local-auth-qr", outputs: [localPath] };
-      }
-    }
     return { rendered: false, mode: flags.json ? "json" : mode };
   }
   const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
@@ -3255,9 +3435,9 @@ async function renderHumanAction(action, flags = {}) {
       persistHumanAction(action, flags);
       return { rendered: false, mode: localPath ? "agent-local-image-qr" : "agent-image-qr", host, outputs: [localPath || "preferred_qr_url"] };
     }
-    await attachAgentTextQR(action, flags);
+    process.stderr.write(`No QR image available. Open payment URL: ${action.url}\n`);
     persistHumanAction(action, flags);
-    return { rendered: false, mode: "agent-text-qr", host, outputs: ["agent_text_qr"] };
+    return { rendered: false, mode: "agent-url-fallback", host, outputs: ["payment_url"] };
   }
 
   const renderResult = { rendered: false, mode, outputs: [] };
@@ -3276,15 +3456,13 @@ async function renderHumanAction(action, flags = {}) {
       await downloadQRImage(qrImageURL, file, flags);
       action.local_qr_path = file;
       action.local_qr_mime = qrMimeType(qrImageURL, action);
+      process.stderr.write(`Alipay QR image: ${file}\n`);
+      renderResult.rendered = true;
+      renderResult.outputs.push(file);
+      if (mode === "file") return renderResult;
     } else {
-      await QRCode.toFile(file, action.url, { errorCorrectionLevel: "M", width: 512, margin: 2 });
-      action.local_qr_path = file;
-      action.local_qr_mime = "image/png";
+      process.stderr.write(`No QR image available. Open payment URL: ${action.url}\n`);
     }
-    process.stderr.write(`Alipay QR image: ${file}\n`);
-    renderResult.rendered = true;
-    renderResult.outputs.push(file);
-    if (mode === "file") return renderResult;
   }
 
   if (qrImageURL) {
@@ -3354,27 +3532,7 @@ function annotateHumanActionPresentation(action, qrImageURL) {
 function shouldPrepareLocalQRForJSON(mode, flags = {}, action = {}) {
   if (mode === "file" || flags.qr_file || process.env.ITP_QR_FILE) return true;
   if (action?.qr_png_url || action?.preferred_qr_url || action?.qr_image_url) return true;
-  if (action?.kind === "auth_qr" && mode !== "none" && mode !== "json") return true;
-  return mode === "agent" || mode === "chat";
-}
-
-function shouldGenerateLocalQRFromActionURL(action = {}) {
-  return action?.kind === "auth_qr" && Boolean(action?.url);
-}
-
-async function prepareGeneratedActionQRFile(action, flags = {}, optional = false) {
-  if (!action?.url) return "";
-  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, "");
-  try {
-    await QRCode.toFile(file, action.url, { errorCorrectionLevel: "M", width: 512, margin: 2 });
-  } catch (error) {
-    if (!optional) throw error;
-    action.local_qr_error = safeErrorMessage(error);
-    return "";
-  }
-  action.local_qr_path = file;
-  action.local_qr_mime = "image/png";
-  return file;
+  return false;
 }
 
 async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = false) {
@@ -3462,57 +3620,6 @@ function attachAgentQRImage(action, qrImageURL, localPath = "") {
   return action;
 }
 
-function attachAgentGeneratedQRImage(action, localPath = "") {
-  if (!action || !localPath) return action;
-  if (!Array.isArray(action.display)) {
-    action.display = [];
-  }
-  if (!action.display.some((item) => item?.type === "image" && item?.local_path === localPath)) {
-    action.display.push({
-      type: "image",
-      format: "png",
-      local_path: localPath,
-      instructions: "Render this local ItPay first-purchase entry QR for the human to scan. It starts account login/registration/profile authorization and should continue to payment for the same checkout after approval; it is not payment proof."
-    });
-  }
-  return action;
-}
-
-async function attachAgentTextQR(action, flags = {}) {
-  if (!action?.url || action.agent_text_qr) return action;
-  const qr = await QRCode.toString(action.url, {
-    type: "utf8",
-    small: true,
-    errorCorrectionLevel: "M"
-  });
-  const lines = qr.replace(/\s+$/g, "").split(/\r?\n/);
-  const text = lines.join("\n");
-  const sha256 = crypto.createHash("sha256").update(text).digest("hex");
-  action.agent_text_qr = {
-    type: "terminal_text",
-    format: "unicode",
-    lines,
-    text,
-    fenced_text: `\`\`\`text\n${text}\n\`\`\``,
-    line_count: lines.length,
-    sha256,
-    url: action.url,
-    allowed_characters: "Only U+2588 FULL BLOCK, U+2580 UPPER HALF BLOCK, U+2584 LOWER HALF BLOCK, spaces, and newlines are valid inside the QR body.",
-    instructions: "Paste fenced_text verbatim into the normal assistant message, not the shell panel. Do not retype, translate, add line numbers, or add words inside the QR body. If any letters, digits, or Chinese characters appear inside the QR body, discard it and use the QR image URL/fallback link instead."
-  };
-  if (!Array.isArray(action.display)) {
-    action.display = [];
-  }
-  if (!action.display.some((item) => item?.type === "terminal_text")) {
-    action.display.push({
-      type: "terminal_text",
-      format: "unicode",
-      lines
-    });
-  }
-  return action;
-}
-
 async function downloadQRImage(qrImageURL, file, flags = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), apiTimeoutMs(flags));
@@ -3648,6 +3755,7 @@ async function coreApi(pathname, options = {}, flags = {}) {
   if (options.ops) {
     headers["X-ItPay-Ops-Token"] = sandboxOpsToken(flags);
   }
+  Object.assign(headers, options.headers || {});
   if (flags.request_id) headers["X-Request-ID"] = String(flags.request_id);
   if (flags.correlation_id) headers["X-Correlation-ID"] = String(flags.correlation_id);
   const targetURL = coreURL(pathname, flags);
@@ -3869,6 +3977,14 @@ function readConfig() {
   return readJSON(CONFIG_PATH, {});
 }
 
+function packageVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
 function writeConfig(value) {
   writeJSON0600(CONFIG_PATH, value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "json5": "^2.2.3"
   }
 }

package/skills/itpay-buyer/SKILL.md

@@ -73,6 +73,10 @@ itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_
 itp buyer checkout resume <checkout_id> --json
 itp buyer payment wait <payment_intent_id> --json
 itp buyer checkout status <checkout_id> --json
+itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --json
+itp buyer refund list --order <order_id> --json
+itp buyer refund show <refund_id> --json
+itp buyer refund cancel <refund_id> --reason buyer_changed_mind --json
 itp buyer vault grants list --checkout <checkout_id> --json
 itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json
 ```
@@ -100,6 +104,15 @@ registered company name or unified social credit code. If the user says
 "京东" or "那个京东商城", do not buy precise lookup until you resolve the exact
 registered name or run fuzzy search first.
 
+Refund commands use ItPay shared order state. If `itp buyer refund create`
+returns `policy_risk_confirmation_required`, explain the returned
+`refund_eligibility.policy` and `agent_guidance` to the human first. Only retry
+with `--confirm-policy-risk true` after explicit human confirmation.
+Current buyer refunds are whole-order only; do not use line-item refund scope.
+If the human cancels a refund before provider or money movement starts, use
+`buyer refund cancel <refund_id> --json`; after cancel, the delivery claim can
+be unlocked again by the ItPay backend.
+
 ## Non-Negotiable Rules
 
 1. Use `--json` for every ItPay command.