@rozoai/checkout 0.1.15 → 0.1.17

package/scripts/dist/status.js

@@ -41,7 +41,20 @@ function redact(text) {
   );
   return s;
 }
+var PublicHash = class {
+  constructor(value) {
+    this.value = value;
+  }
+  toJSON() {
+    return this.value;
+  }
+};
+var TX_HASH_VALUE = /^(0x[0-9a-fA-F]{64}|[1-9A-HJ-NP-Za-km-z]{86,88})$/;
+function publicHash(value) {
+  return typeof value === "string" && TX_HASH_VALUE.test(value) ? new PublicHash(value) : value;
+}
 function redactDeep(value) {
+  if (value instanceof PublicHash) return value.value;
   if (typeof value === "string") return redact(value);
   if (Array.isArray(value)) return value.map(redactDeep);
   if (value && typeof value === "object") {
@@ -194,6 +207,57 @@ function getJson(url, opts) {
   return request("GET", url, opts);
 }
 
+// scripts/src/lib/state.mjs
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+function stateRoot() {
+  return process.env.ROZO_CHECKOUT_STATE_DIR || path.join(os.homedir(), ".rozo-checkout", "state");
+}
+function statePath(rozoPaymentId) {
+  if (!/^[A-Za-z0-9-]{8,64}$/.test(String(rozoPaymentId || ""))) {
+    throw new SkillError("BAD_ROZO_PAYMENT_ID", "Refusing to build a state path from that id.");
+  }
+  return path.join(stateRoot(), `${rozoPaymentId}.json`);
+}
+function readState(rozoPaymentId) {
+  const file = statePath(rozoPaymentId);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw new SkillError("STATE_UNREADABLE", `Cannot read local state: ${err.code}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new SkillError(
+      "STATE_CORRUPT",
+      "The local state file for this order is corrupt. Refusing to act; inspect it manually."
+    );
+  }
+}
+function findByLinkId(linkId) {
+  const dir = stateRoot();
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const f of files) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      if (s?.linkId !== linkId) continue;
+      if (!best || String(s.createdAt) > String(best.createdAt)) best = s;
+    } catch {
+    }
+  }
+  return best;
+}
+
 // scripts/src/lib/api.mjs
 var PKG_VERSION = (() => {
   const requireFrom = createRequire(import.meta.url);
@@ -352,6 +416,72 @@ function receiptSignal(source) {
     return { money: true, receipt: null, unparsable: true };
   }
 }
+function checkPayable(statusResponse, now = Date.now()) {
+  const cb = statusResponse?.coinbase;
+  if (!cb) {
+    return {
+      ok: false,
+      code: "LINK_NO_LONGER_PAYABLE",
+      reason: "invoice-status returned no Coinbase state; cannot prove the link is still payable.",
+      derived: null
+    };
+  }
+  const protocolVersion = cb.protocolVersion ?? statusResponse?.protocolVersion ?? null;
+  const derived = {
+    protocolVersion,
+    status: cb.status ?? null,
+    settled: cb.settled ?? null,
+    usageCount: cb.usageCount ?? null,
+    maxUsage: cb.maxUsage ?? null,
+    preApprovalExpiry: cb.preApprovalExpiry ?? null
+  };
+  if (cb.settled === true) {
+    return {
+      ok: false,
+      code: "LINK_NO_LONGER_PAYABLE",
+      reason: "The Coinbase resource is already settled \u2014 someone has paid it.",
+      derived
+    };
+  }
+  if (protocolVersion === "v3") {
+    if (!cb.status) {
+      return {
+        ok: false,
+        code: "LINK_PAYABILITY_UNKNOWN",
+        reason: "The Payment Session response carries no status; cannot prove it is still payable.",
+        derived
+      };
+    }
+    if (cb.status !== "PAYMENT_SESSION_STATUS_CREATED") {
+      return {
+        ok: false,
+        code: "LINK_NO_LONGER_PAYABLE",
+        reason: `Payment Session status is ${cb.status}; only PAYMENT_SESSION_STATUS_CREATED is payable.`,
+        derived
+      };
+    }
+    return { ok: true, code: null, reason: null, derived };
+  }
+  const usage2 = Number(cb.usageCount);
+  const max = Number(cb.maxUsage);
+  if (cb.usageCount === null || cb.usageCount === void 0 || cb.maxUsage === null || cb.maxUsage === void 0 || !Number.isFinite(usage2) || !Number.isFinite(max)) {
+    return {
+      ok: false,
+      code: "LINK_PAYABILITY_UNKNOWN",
+      reason: "The payment link response is missing usageCount/maxUsage; cannot prove it has not already been used.",
+      derived
+    };
+  }
+  if (usage2 >= max) {
+    return {
+      ok: false,
+      code: "LINK_NO_LONGER_PAYABLE",
+      reason: `Payment link already used (${usage2}/${max}).`,
+      derived
+    };
+  }
+  return { ok: true, code: null, reason: null, derived };
+}
 function classifyStatus({
   payment,
   routerState,
@@ -393,9 +523,6 @@ function classifyStatus({
       { escalate: true }
     );
   }
-  if (!bitrefill && (routerStatus === "paid" || coinbase?.settled === true)) {
-    return mk("settled", "Coinbase invoice settled by the funder wallet.", { terminal: true });
-  }
   if (routerStatus === "failed_pay_invoice" || routerStatus === "failed_insufficient_balance") {
     return mk(
       "stuck_after_payment",
@@ -403,6 +530,9 @@ function classifyStatus({
       { terminal: false, escalate: true }
     );
   }
+  if (!bitrefill && (routerStatus === "paid" || coinbase?.settled === true)) {
+    return mk("settled", "Coinbase invoice settled by the funder wallet.", { terminal: true });
+  }
   if (moneyDetected && receipt && receipt.state === "underpaid") {
     return mk(
       "underpaid",
@@ -500,6 +630,10 @@ function formatRemaining(ms) {
   const m = totalMinutes % 60;
   return m ? `${h}h ${m}m` : `${h}h`;
 }
+function marginFor(chainId) {
+  const key = String(chainId);
+  return MARGINS_MS[key] ?? MARGINS_MS[chainId] ?? DEFAULT_MARGIN_MS;
+}
 function parseDeadline(value) {
   if (value === null || value === void 0 || value === "") return null;
   if (typeof value === "number" && Number.isFinite(value)) {
@@ -513,56 +647,86 @@ function parseDeadline(value) {
   const t = Date.parse(s);
   return Number.isFinite(t) ? t : null;
 }
-
-// scripts/src/lib/state.mjs
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-function stateRoot() {
-  return process.env.ROZO_CHECKOUT_STATE_DIR || path.join(os.homedir(), ".rozo-checkout", "state");
-}
-function statePath(rozoPaymentId) {
-  if (!/^[A-Za-z0-9-]{8,64}$/.test(String(rozoPaymentId || ""))) {
-    throw new SkillError("BAD_ROZO_PAYMENT_ID", "Refusing to build a state path from that id.");
+function checkExpiry({
+  now,
+  chainId,
+  intentExpiresAt,
+  coinbaseExpiry,
+  bolt11ExpiresAt = void 0
+}) {
+  const marginMs = marginFor(chainId);
+  const intentMs = parseDeadline(intentExpiresAt);
+  const coinbaseMs = parseDeadline(coinbaseExpiry);
+  const bolt11Ms = bolt11ExpiresAt === void 0 ? void 0 : parseDeadline(bolt11ExpiresAt);
+  const deadlines = { intentMs, coinbaseMs, bolt11Ms: bolt11Ms ?? null };
+  const base = {
+    marginMs,
+    effectiveDeadlineMs: null,
+    msRemaining: null,
+    msOfSlack: null,
+    deadlines
+  };
+  if (intentMs === null) {
+    return {
+      ...base,
+      ok: false,
+      code: "EXPIRY_UNPARSABLE",
+      reason: "Intent expiresAt is missing or unparsable."
+    };
   }
-  return path.join(stateRoot(), `${rozoPaymentId}.json`);
-}
-function readState(rozoPaymentId) {
-  const file = statePath(rozoPaymentId);
-  let raw;
-  try {
-    raw = fs.readFileSync(file, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return null;
-    throw new SkillError("STATE_UNREADABLE", `Cannot read local state: ${err.code}`);
+  if (coinbaseMs === null) {
+    return {
+      ...base,
+      ok: false,
+      code: "EXPIRY_UNPARSABLE",
+      reason: "Coinbase preApprovalExpiry is missing or unparsable."
+    };
   }
-  try {
-    return JSON.parse(raw);
-  } catch {
-    throw new SkillError(
-      "STATE_CORRUPT",
-      "The local state file for this order is corrupt. Refusing to act; inspect it manually."
-    );
+  const effective = Math.min(intentMs, coinbaseMs);
+  const msRemaining = effective - now;
+  const msOfSlack = msRemaining - marginMs;
+  const withDeadline = {
+    ...base,
+    effectiveDeadlineMs: effective,
+    msRemaining,
+    msOfSlack
+  };
+  if (msRemaining <= 0) {
+    return {
+      ...withDeadline,
+      ok: false,
+      code: "EXPIRED",
+      reason: "The order or the Coinbase link has already expired."
+    };
   }
-}
-function findByLinkId(linkId) {
-  const dir = stateRoot();
-  let files = [];
-  try {
-    files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
-  } catch {
-    return null;
+  if (msOfSlack <= 0) {
+    return {
+      ...withDeadline,
+      ok: false,
+      code: "EXPIRY_MARGIN",
+      reason: `Only ${Math.floor(msRemaining / 1e3)}s left before the earliest deadline; this chain needs a ${Math.floor(marginMs / 6e4)} min safety margin.`
+    };
   }
-  let best = null;
-  for (const f of files) {
-    try {
-      const s = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
-      if (s?.linkId !== linkId) continue;
-      if (!best || String(s.createdAt) > String(best.createdAt)) best = s;
-    } catch {
+  if (bolt11ExpiresAt !== void 0) {
+    if (bolt11Ms === null) {
+      return {
+        ...withDeadline,
+        ok: false,
+        code: "EXPIRY_UNPARSABLE",
+        reason: "BOLT11 invoice expiry is missing or unparsable."
+      };
+    }
+    const bolt11Remaining = bolt11Ms - now;
+    if (bolt11Remaining < BOLT11_MIN_VALIDITY_MS) {
+      return {
+        ...withDeadline,
+        ok: false,
+        code: "BOLT11_TOO_SHORT",
+        reason: `BOLT11 invoice has ${Math.max(0, Math.floor(bolt11Remaining / 1e3))}s of validity left; at least 10 min is required. Request a fresh invoice.`
+      };
     }
   }
-  return best;
+  return { ...withDeadline, ok: true, code: null, reason: null };
 }
 
 // scripts/src/lib/bitrefill.mjs
@@ -586,6 +750,153 @@ function intentBitrefillExpiry(payment) {
   return payment?.metadata?.bitrefillExpiresAt ?? null;
 }
 
+// scripts/src/lib/receipt.mjs
+var SCHEMA_VERSION = 1;
+var PAYMENT_OUTCOMES = Object.freeze([
+  "awaiting_payment",
+  "processing",
+  "settled",
+  "expired_unfunded",
+  "needs_attention",
+  "unknown"
+]);
+var NEXT_ACTION_TYPES = Object.freeze([
+  "pay",
+  "check_status",
+  "choose_method",
+  "request_new_invoice",
+  "contact_support",
+  "none"
+]);
+var STATE_TO_OUTCOME = Object.freeze({
+  awaiting_deposit: "awaiting_payment",
+  payin_detected: "processing",
+  payin_confirmed: "processing",
+  bridging: "processing",
+  paying_coinbase: "processing",
+  settled: "settled",
+  expired_unfunded: "expired_unfunded",
+  invoice_expired: "expired_unfunded",
+  deadline_unknown: "needs_attention",
+  underpaid: "needs_attention",
+  stuck_after_payment: "needs_attention",
+  unknown: "unknown"
+});
+function merchantSettlementProved(result) {
+  if (result?.provider === "bitrefill") return result?.state === "settled";
+  return result?.backend?.coinbaseSettled === true;
+}
+function hasLocalSend(result) {
+  return Boolean(result?.localSend && result.localSend.status);
+}
+function paymentOutcomeFor(result) {
+  if (!result) return "unknown";
+  if (result.escalate) return "needs_attention";
+  if (result.unknown) return "unknown";
+  let outcome = Object.prototype.hasOwnProperty.call(STATE_TO_OUTCOME, result.state) ? STATE_TO_OUTCOME[result.state] : "unknown";
+  if (outcome === "settled" && !merchantSettlementProved(result)) outcome = "processing";
+  if (outcome === "settled" && result.provider !== "bitrefill") {
+    const router = result.backend?.routerStatus ?? null;
+    if (router && router.startsWith("failed_")) return "needs_attention";
+    if (router && router !== "paid") outcome = "processing";
+  }
+  if (!result.authoritativeView && (outcome === "awaiting_payment" || outcome === "expired_unfunded")) {
+    return "unknown";
+  }
+  if ((result.moneyDetected || hasLocalSend(result)) && outcome === "expired_unfunded") {
+    return "needs_attention";
+  }
+  if (result.moneyDetected && outcome === "awaiting_payment") return "processing";
+  return outcome;
+}
+function nextActionFor(result, outcome = paymentOutcomeFor(result)) {
+  const locked = Boolean(result?.moneyDetected) || hasLocalSend(result);
+  const base = { canRetryQuery: true, canCreateOrder: false, canSend: false };
+  const bitrefill = result?.provider === "bitrefill";
+  switch (outcome) {
+    case "awaiting_payment":
+      if (locked) {
+        return {
+          ...base,
+          type: "check_status",
+          message: "A send was already recorded for this order. Do NOT pay again; poll status until the pay-in shows up."
+        };
+      }
+      if (!result?.sendWindow?.ok) {
+        const code = result?.sendWindow?.code ?? "SEND_WINDOW_UNKNOWN";
+        if (code === "LINK_NO_LONGER_PAYABLE") {
+          return {
+            ...base,
+            type: "request_new_invoice",
+            reason: code,
+            message: "The merchant link no longer accepts payment. Do NOT fund this order; get a new payment link."
+          };
+        }
+        if (code === "EXPIRED" || code === "EXPIRY_MARGIN") {
+          return {
+            ...base,
+            type: "check_status",
+            reason: code,
+            message: "Too little time is left to pay this order safely. Do NOT fund it. Once it shows expired_unfunded, run pay again on the same link for a new order."
+          };
+        }
+        return {
+          ...base,
+          type: "check_status",
+          reason: code,
+          message: "Whether this order can still be paid could not be proved. Do NOT fund it on a guess; retry."
+        };
+      }
+      return {
+        ...base,
+        type: "pay",
+        canSend: true,
+        message: "Send the exact amount from the order deposit block, once."
+      };
+    case "processing":
+      return {
+        ...base,
+        type: "check_status",
+        message: "Funds are moving. Do NOT pay again; poll status."
+      };
+    case "settled":
+      return { ...base, type: "none", canRetryQuery: false, message: "Nothing to do." };
+    case "expired_unfunded":
+      if (bitrefill) {
+        return {
+          ...base,
+          type: "request_new_invoice",
+          message: "Nothing was funded. Create a fresh Bitrefill invoice and pay that one."
+        };
+      }
+      return {
+        ...base,
+        type: "choose_method",
+        canCreateOrder: true,
+        message: "Nothing arrived for this order. If your own wallet shows no send to the old deposit address and no pending Lightning payment, run pay again on the same link: it creates a new order, and you may pick a different coin. Never fund the old deposit address."
+      };
+    case "needs_attention":
+      if (result?.state === "deadline_unknown" && !locked) {
+        return {
+          ...base,
+          type: "request_new_invoice",
+          message: "The invoice deadline is unknown here, so the order is not payable. Re-run pay with the invoice details, or create a fresh invoice."
+        };
+      }
+      return {
+        ...base,
+        type: "contact_support",
+        message: "Do NOT pay again and do NOT create a new order. Keep linkId, rozoPaymentId and every tx hash, and contact Rozo support."
+      };
+    default:
+      return {
+        ...base,
+        type: "check_status",
+        message: "The order state could not be established. This is not evidence that nothing was paid. Retry with the rozoPaymentId before doing anything else."
+      };
+  }
+}
+
 // scripts/src/status.mjs
 var POLL_INTERVAL_MS = 1e4;
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -600,6 +911,42 @@ function resolveProvider(explicit, rozoPaymentId) {
   }
   return null;
 }
+function localSendFor(id, read = readState) {
+  if (!id || !isRozoPaymentId(id)) return null;
+  let state;
+  try {
+    state = read(id);
+  } catch (err) {
+    return { status: "unreadable", txHash: null, claimedAt: null, error: err?.code ?? "STATE_UNREADABLE" };
+  }
+  const send = state?.send;
+  if (!send || !send.status) return null;
+  return { status: send.status, txHash: publicHash(send.txHash ?? null), claimedAt: send.claimedAt ?? null };
+}
+function sendWindowFor({ provider, chainId, payment, status, bitrefillExpiry, now = Date.now() }) {
+  if (provider === "bitrefill") {
+    const deadline = bitrefillExpiry ?? null;
+    const expiry2 = checkExpiry({
+      now,
+      chainId,
+      intentExpiresAt: payment?.expiresAt ?? deadline,
+      coinbaseExpiry: deadline
+    });
+    return expiry2.ok ? { ok: true, code: null, minutesOfSlack: Math.floor(expiry2.msOfSlack / 6e4), deadlineMs: expiry2.effectiveDeadlineMs } : { ok: false, code: expiry2.code, reason: expiry2.reason };
+  }
+  if (!status) {
+    return { ok: false, code: "LINK_PAYABILITY_UNKNOWN", reason: "The Coinbase link state could not be read." };
+  }
+  const payable = checkPayable(status, now);
+  if (!payable.ok) return { ok: false, code: payable.code, reason: payable.reason };
+  const expiry = checkExpiry({
+    now,
+    chainId,
+    intentExpiresAt: payment?.expiresAt ?? status?.rozoPayment?.expiresAt,
+    coinbaseExpiry: status?.coinbase?.preApprovalExpiry
+  });
+  return expiry.ok ? { ok: true, code: null, minutesOfSlack: Math.floor(expiry.msOfSlack / 6e4), deadlineMs: expiry.effectiveDeadlineMs } : { ok: false, code: expiry.code, reason: expiry.reason };
+}
 async function snapshot({ rozoPaymentId, linkId, provider: explicitProvider }) {
   let provider = resolveProvider(explicitProvider, rozoPaymentId);
   let prefetched = null;
@@ -697,7 +1044,7 @@ async function snapshot({ rozoPaymentId, linkId, provider: explicitProvider }) {
       expected: source.amount ? formatAmount(source) : null,
       received: source.amountReceived ?? null,
       receipt: verdict.receipt,
-      txHash: source.txHash ?? null,
+      txHash: publicHash(source.txHash ?? null),
       confirmedAt: source.confirmedAt ?? null,
       senderAddressMasked: source.senderAddress ? maskAddress(source.senderAddress) : null,
       chain: source.chainId ? chainName(source.chainId) : null
@@ -716,9 +1063,11 @@ async function snapshot({ rozoPaymentId, linkId, provider: explicitProvider }) {
       };
     })(),
     payout: {
-      txHash: payment?.destination?.txHash ?? status?.rozoPayment?.destination?.txHash ?? null,
+      txHash: publicHash(payment?.destination?.txHash ?? status?.rozoPayment?.destination?.txHash ?? null),
       confirmedAt: payment?.destination?.confirmedAt ?? status?.rozoPayment?.destination?.confirmedAt ?? null
     },
+    localSend: localSendFor(id),
+    sendWindow: state === "awaiting_deposit" ? sendWindowFor({ provider, chainId: source.chainId, payment, status, bitrefillExpiry }) : null,
     errors: [statusError, paymentError].filter(Boolean)
   };
 }
@@ -767,9 +1116,16 @@ async function main(argv) {
   const guidance = statusGuidance(result);
   const unresolved = watch && !result.terminal && !result.escalate && !result.unknown;
   const failed = result.escalate || result.unknown || !result.authoritativeView;
+  const paymentOutcome = paymentOutcomeFor(result);
   emit(
     {
+      // `success` keeps its historical meaning (the query produced a clean
+      // answer). It is NOT "the invoice is paid": read paymentOutcome.
       success: !failed,
+      schemaVersion: SCHEMA_VERSION,
+      operationOk: !result.unknown,
+      paymentOutcome,
+      nextAction: nextActionFor(result, paymentOutcome),
       step: "status",
       ...result,
       history,