@itpay/cli 0.1.7 → 0.1.9

package/bin/itp

@@ -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,13 +3422,13 @@ 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 (!qrImageURL && shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
+      const localPath = await prepareLocalQRFromActionURL(action, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
       if (localPath) {
-        attachAgentGeneratedQRImage(action, localPath);
+        attachAgentLocalQR(action, localPath);
         annotateHumanActionPresentation(action, "");
         persistHumanAction(action, flags);
-        return { rendered: false, mode: "json-local-auth-qr", outputs: [localPath] };
+        return { rendered: false, mode: "json-local-url-qr", outputs: [localPath] };
       }
     }
     return { rendered: false, mode: flags.json ? "json" : mode };
@@ -3255,9 +3444,18 @@ 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);
+    if (shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
+      const localPath = await prepareLocalQRFromActionURL(action, flags, true);
+      if (localPath) {
+        attachAgentLocalQR(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        persistHumanAction(action, flags);
+        return { rendered: false, mode: "agent-local-url-qr", host, outputs: [localPath] };
+      }
+    }
+    process.stderr.write(`No QR image available. Open action 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: ["action_url"] };
   }
 
   const renderResult = { rendered: false, mode, outputs: [] };
@@ -3276,15 +3474,25 @@ 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";
+      const localPath = shouldGenerateLocalQRFromActionURL(action, mode, flags)
+        ? await prepareLocalQRFromActionURL(action, flags, false)
+        : "";
+      if (localPath) {
+        attachAgentLocalQR(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        process.stderr.write(`Alipay action QR image: ${localPath}\n`);
+        renderResult.rendered = true;
+        renderResult.outputs.push(localPath);
+        if (mode === "file") return renderResult;
+      } else {
+        process.stderr.write(`No QR image available. Open action 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,41 +3562,48 @@ 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";
+  return false;
 }
 
-function shouldGenerateLocalQRFromActionURL(action = {}) {
-  return action?.kind === "auth_qr" && Boolean(action?.url);
+function shouldGenerateLocalQRFromActionURL(action = {}, mode = "", flags = {}) {
+  if (!action?.url) return false;
+  if (action.kind === "auth_qr") return true;
+  return mode === "file" || Boolean(flags.qr_file || process.env.ITP_QR_FILE);
 }
 
-async function prepareGeneratedActionQRFile(action, flags = {}, optional = false) {
-  if (!action?.url) return "";
-  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, "");
+async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = false) {
+  if (!qrImageURL) return "";
+  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, qrImageURL);
   try {
-    await QRCode.toFile(file, action.url, { errorCorrectionLevel: "M", width: 512, margin: 2 });
+    await downloadQRImage(qrImageURL, file, flags);
   } catch (error) {
     if (!optional) throw error;
     action.local_qr_error = safeErrorMessage(error);
     return "";
   }
   action.local_qr_path = file;
-  action.local_qr_mime = "image/png";
+  action.local_qr_mime = qrMimeType(qrImageURL, action);
   return file;
 }
 
-async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = false) {
-  if (!qrImageURL) return "";
-  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, qrImageURL);
+async function prepareLocalQRFromActionURL(action, flags = {}, optional = false) {
+  if (!action?.url) return "";
+  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultGeneratedQRFilePath(action);
   try {
-    await downloadQRImage(qrImageURL, file, flags);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    await QRCode.toFile(file, action.url, {
+      type: "png",
+      errorCorrectionLevel: "M",
+      margin: 2,
+      width: 512
+    });
   } catch (error) {
     if (!optional) throw error;
     action.local_qr_error = safeErrorMessage(error);
     return "";
   }
   action.local_qr_path = file;
-  action.local_qr_mime = qrMimeType(qrImageURL, action);
+  action.local_qr_mime = "image/png";
   return file;
 }
 
@@ -3397,6 +3612,11 @@ function defaultQRFilePath(action, qrImageURL) {
   return path.join(os.tmpdir(), `itp-${id}.${qrFileExtension(qrImageURL, action)}`);
 }
 
+function defaultGeneratedQRFilePath(action) {
+  const id = sanitizeFilename(action?.payment_intent_id || action?.id || "qr");
+  return path.join(os.tmpdir(), `itp-${id}.png`);
+}
+
 function qrFileExtension(qrImageURL, action = {}) {
   const mime = qrMimeType(qrImageURL, action);
   if (mime === "image/png") return "png";
@@ -3462,7 +3682,7 @@ function attachAgentQRImage(action, qrImageURL, localPath = "") {
   return action;
 }
 
-function attachAgentGeneratedQRImage(action, localPath = "") {
+function attachAgentLocalQR(action, localPath = "") {
   if (!action || !localPath) return action;
   if (!Array.isArray(action.display)) {
     action.display = [];
@@ -3472,42 +3692,7 @@ function attachAgentGeneratedQRImage(action, localPath = "") {
       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
+      instructions: "Render this local QR image for the human to scan. It encodes the ItPay human action URL, not a provider raw QR payload."
     });
   }
   return action;
@@ -3648,6 +3833,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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.