@rozoai/checkout 0.1.14 → 0.1.16

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") {
@@ -352,6 +365,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 +472,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 +479,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",
@@ -433,7 +512,7 @@ function classifyStatus({
       }
       const exp = payment?.expiresAt ? Date.parse(payment.expiresAt) : NaN;
       if (Number.isFinite(exp) && exp < now) {
-        return mk("expired_unfunded", "The order expired before any funds arrived. Safe to retry.", {
+        return mk("expired_unfunded", "The order expired before any funds arrived. This order can no longer be paid.", {
           terminal: true
         });
       }
@@ -459,7 +538,7 @@ function classifyStatus({
     case "payment_expired":
       return moneyDetected ? mk("stuck_after_payment", "Order expired AFTER funds arrived \u2014 escalate immediately.", {
         escalate: true
-      }) : mk("expired_unfunded", "Order expired unfunded. Safe to retry.", { terminal: true });
+      }) : mk("expired_unfunded", "Order expired unfunded. This order can no longer be paid.", { terminal: true });
     case "payment_bounced":
     case "payment_refunded":
       return mk("stuck_after_payment", `Order ended as ${payment.status} \u2014 escalate.`, {
@@ -500,6 +579,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,6 +596,87 @@ function parseDeadline(value) {
   const t = Date.parse(s);
   return Number.isFinite(t) ? t : null;
 }
+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."
+    };
+  }
+  if (coinbaseMs === null) {
+    return {
+      ...base,
+      ok: false,
+      code: "EXPIRY_UNPARSABLE",
+      reason: "Coinbase preApprovalExpiry is missing or unparsable."
+    };
+  }
+  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."
+    };
+  }
+  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.`
+    };
+  }
+  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 { ...withDeadline, ok: true, code: null, reason: null };
+}
 
 // scripts/src/lib/state.mjs
 import fs from "node:fs";
@@ -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) } : { 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) } : { 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,12 +1063,31 @@ 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)
   };
 }
+var EXPIRED_UNFUNDED_GUIDANCE = "This order expired before any funds arrived. First check your own wallet: if anything was sent to the old deposit address, or a Lightning payment is still pending, do not pay again; contact support with the linkId and rozoPaymentId (the router cannot see a pending Lightning payment). If nothing was sent, re-run the same pay on the same link with the same --with: it creates a new order for this link. If pay answers PAYMENT_EXPIRED with retryable: true, the old order cannot be verified yet; wait a few minutes and retry. If it answers LINK_USED_OR_EXPIRED, or PAYMENT_EXPIRED with confirmed: true, this link cannot be paid any more; get a new payment link from the merchant (OpenRouter). If it answers ORDER_ALREADY_ACTIVE, a payment was found: do not pay again; contact support.";
+function statusGuidance(result) {
+  if (result.escalate) {
+    return "MONEY DETECTED and the order is not on a healthy path. Do NOT pay again and do NOT create a new order for this link. Preserve linkId, rozoPaymentId and every tx hash, then escalate to the operator for manual reconciliation.";
+  }
+  if (result.unknown) {
+    return "The order state could not be established. This is NOT evidence that nothing was paid \u2014 do not create a new order and do not send again on the strength of it. Retry, or pass --rozo-payment-id so the authoritative pay-in view can be read.";
+  }
+  if (!result.authoritativeView) {
+    return "Only the fulfilment view was readable; the pay-in view is unavailable, so the money-detected rule cannot be enforced. Pass --rozo-payment-id for a complete answer.";
+  }
+  if ((result.state === "expired_unfunded" || result.state === "invoice_expired") && result.provider === "bitrefill") {
+    return "Nothing was funded, so nothing was lost. Create a fresh Bitrefill invoice and run rozo-checkout pay --bitrefill-invoice <id> --to <0x\u2026> --amount <USDC> --with <coin>";
+  }
+  if (result.state === "expired_unfunded") return EXPIRED_UNFUNDED_GUIDANCE;
+  return result.terminal ? "Done." : "Still in flight. Poll again in ~10s.";
+}
 async function main(argv) {
   const args = parseArgs(argv);
   const rozoPaymentId = args["rozo-payment-id"] || (isRozoPaymentId(args._[0]) ? args._[0] : null);
@@ -747,12 +1113,19 @@ async function main(argv) {
     if (next.state !== result.state) history.push({ at: (/* @__PURE__ */ new Date()).toISOString(), state: next.state });
     result = next;
   }
-  const guidance = result.escalate ? "MONEY DETECTED and the order is not on a healthy path. Do NOT pay again and do NOT create a new order for this link. Preserve linkId, rozoPaymentId and every tx hash, then escalate to the operator for manual reconciliation." : result.unknown ? "The order state could not be established. This is NOT evidence that nothing was paid \u2014 do not create a new order and do not send again on the strength of it. Retry, or pass --rozo-payment-id so the authoritative pay-in view can be read." : !result.authoritativeView ? "Only the fulfilment view was readable; the pay-in view is unavailable, so the money-detected rule cannot be enforced. Pass --rozo-payment-id for a complete answer." : (result.state === "expired_unfunded" || result.state === "invoice_expired") && result.provider === "bitrefill" ? "Nothing was funded, so nothing was lost. Create a fresh Bitrefill invoice and run rozo-checkout pay --bitrefill-invoice <id> --to <0x\u2026> --amount <USDC> --with <coin>" : result.state === "expired_unfunded" ? "Nothing was funded, so nothing was lost. Start a fresh order with: rozo-checkout pay <coinbase-link> --with <coin>  (or create-order.js --url <link> --chain <id> --token <SYMBOL>)" : result.terminal ? "Done." : "Still in flight. Poll again in ~10s.";
+  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,