@rozoai/checkout 0.1.12 → 0.1.15

package/README.md

@@ -116,6 +116,12 @@ the optional `--send` flag signs locally: on Solana it uses the
 encrypted JSON keystore whose passphrase is prompted. A raw key in the
 environment (or a gitignored `.env`) still works for unattended automation.
 
+Distributing this CLI? `--utm-source <label>` (or `ROZO_CHECKOUT_UTM_SOURCE`) is an optional channel label for reporting; no identity, no privilege.
+
+Want ROZO to be able to reach you if a payment needs attention? Add the optional `--email you@example.com` to `pay`.
+
+Need help? Email hi@rozo.ai, or reach us on [X](https://x.com/ROZOai) or [Discord](https://discord.gg/EfWejgTbuU).
+
 <details>
 <summary><b>Set up a local wallet for <code>--send</code></b> — .env template and per-wallet export steps</summary>
 
@@ -366,6 +372,104 @@ keypair or an encrypted keystore, and supports EVM chains and Solana only —
 Stellar and Lightning are Mode A only.
 </details>
 
+## Paying many invoices (batch / resellers)
+
+Each OpenRouter top-up is its own Coinbase link, so paying many is a loop: one
+`pay` per link, one logged result per link. Install once
+(`npm i -g @rozoai/checkout`) so each run skips the npx download, run the links
+one at a time, and pay each deposit right after it is created.
+
+```bash
+#!/usr/bin/env bash
+# links.txt: one Coinbase link per line (payment-links/pl_* or payment-sessions/paymentSession_*)
+mkdir -p runs
+while IFS= read -r link; do
+  link="${link%$'\r'}"; link="${link%%\?*}"
+  [ -n "$link" ] || continue
+  id="${link##*/}"
+  rozo-checkout pay "$link" --with btc-lightning --yes --json --no-watch \
+    --email you@example.com </dev/null > "runs/$id.json"
+  code=$?
+  row=$(jq -r --arg id "$id" --arg code "$code" '[$id, $code,
+      (.order.rozoPaymentId // .error.details.body.rozoPaymentId // "-"),
+      (if .success then "pending: pay before " + (.order.expiry.effectiveDeadlineIso // "?")
+       else (.error.code // .send.error.code // "FAILED") end)] | @tsv' \
+    "runs/$id.json" 2>/dev/null) || row="$id	$code	-	NO_OUTPUT"
+  printf '%s\n' "$row" >> runs/batch.tsv
+done < links.txt
+```
+
+- `--yes` is required when stdin is not a terminal, `--json` prints exactly one
+  JSON object, and `--no-watch` returns as soon as the deposit details exist.
+  Without `--no-watch`, `pay --json` first waits for settlement (up to
+  `--timeout`, default 900 s) and prints nothing until then, invoice included.
+- Without `--send` (the loop above), a successful `pay --no-watch` means the
+  order and its deposit details exist. **No money has moved yet**, which is
+  why the log says `pending`. With `--send`, the CLI may already have
+  broadcast your payment, so never pay that deposit by hand as well. A link is
+  paid only when `status` later reports `settled`.
+- `order.rozoPaymentId` names the order and `order.deposit` says what to pay.
+  Lightning: `deposit.lnInvoice` (the BOLT11) for `deposit.amount` sats. Other
+  coins: `deposit.receiverAddress` and `deposit.amount`, plus
+  `deposit.receiverMemo` on Stellar. `--send` cannot pay Lightning or Stellar.
+- The deadline to watch is `order.expiry.effectiveDeadlineIso`, not
+  `deposit.expiresAt`: it is the earlier of our order expiry and the Coinbase
+  link expiry. Stop paying at least `order.expiry.marginMinutes` before it,
+  since settlement needs that much time.
+- If time has passed since you created the order, do not pay saved deposit
+  details blindly. Re-run the same `pay` command (same `--with`): while the
+  order is still payable it re-checks the link and the deadline and hands back
+  the same order. Pay only if that succeeds.
+
+Check settlement by `rozoPaymentId` (a link alone is only resolved from this
+machine's own records in `~/.rozo-checkout/state`):
+
+```bash
+rozo-checkout status <rozoPaymentId> --json | jq -r '.state, .escalate'
+rozo-checkout status <rozoPaymentId> --watch --timeout 900 --json   # poll every 10 s
+```
+
+Exit 0 means the check itself ran cleanly, not that the invoice settled:
+`expired_unfunded` also exits 0. Always read `state`.
+
+**Retrying without paying twice.** Running `pay` again on the same link does
+not create a second order while its order is open: you get the same order
+back, and once money has arrived `pay` refuses with `ORDER_ALREADY_ACTIVE` or
+`ORDER_ALREADY_FUNDED`. Only after an order expired with nothing received does
+`pay` on the same link create a new order. The risk is paying a deposit twice, so before acting on
+a link again, run `status` on its `rozoPaymentId`:
+
+| `status` result | What to do |
+| --- | --- |
+| `escalate: true` (includes `underpaid`, `stuck_after_payment`; exit 1) | Do not pay again. Contact support with the link, `rozoPaymentId` and any tx hash or payment preimage. |
+| `state: settled` | Done. Skip this link. |
+| `state: awaiting_deposit` | Still open, but a payment you just sent may not be detected yet. First check your wallet: if a send or Lightning payment to this deposit exists or is pending, wait and poll. Only if nothing was sent, re-run the same `pay` to re-check it, then pay the deposit once. |
+| `state: payin_detected`, `payin_confirmed`, `bridging`, `paying_coinbase` | Money is in flight. Wait and poll; do not pay again. |
+| `state: expired_unfunded` | Nothing has arrived and this order is dead. **First check your own wallet**: if you sent anything to the old deposit, or a Lightning payment is still pending, do not pay again; contact support with the link and `rozoPaymentId` (we 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. If that answers `PAYMENT_EXPIRED`, see below. |
+| `state: unknown` (exit 1) | The backend could not be read. Not proof that nothing was paid: retry `status`, not `pay`. |
+
+- Exit codes: `0` ok, `1` refused or failed (read `error.code`), `2` usage
+  error (nothing was created), `3` the watch window ended before a final
+  state. Exit 3 means money may still be in flight: keep polling, do not pay
+  again.
+- Use the same `--with` coin on every run for a link. A different coin can be
+  refused with `REUSED_SOURCE_MISMATCH` or change the open order's deposit.
+- `LINK_USED_OR_EXPIRED` or `LINK_NO_LONGER_PAYABLE`: the Coinbase link itself
+  is already paid or expired. Check your OpenRouter balance and get a new link
+  if it was not credited.
+- `PAYMENT_EXPIRED`: an earlier order for this link expired. Read
+  `error.details.body`: with `retryable: true` (`confirmed: false`) the old
+  order cannot be proved unfunded yet, so wait a few minutes and retry the same
+  `pay`; with `confirmed: true` the link has used all its re-orders, so get a
+  new link from OpenRouter.
+- `RATE_LIMITED`: order creation is capped per IP per hour (currently 30
+  requests, and each `pay` makes two), so plan on about 15 links per hour from
+  one IP. Wait for the next hour and resume with the links not yet `settled`.
+  Need more? Email us.
+
+Questions about a batch? Email hi@rozo.ai, or reach us on
+[X](https://x.com/ROZOai) or [Discord](https://discord.gg/EfWejgTbuU).
+
 ## Three rules worth knowing
 
 - **The deposit address is one-time.** Never reuse one from an older order, a
@@ -394,6 +498,22 @@ The full list of what this refuses to do, and why, is in
 
 ## Changelog
 
+- **0.1.15**: corrected guidance after an order expires unpaid. First check
+  your own wallet that nothing was sent to the old deposit and no Lightning
+  payment is pending; if nothing was sent, re-run the same `pay` on the same
+  link (the router opens a new order once it has verified the old one is
+  unfunded). `PAYMENT_EXPIRED` with `retryable: true` means try again in a few
+  minutes; `LINK_USED_OR_EXPIRED` or `PAYMENT_EXPIRED` with `confirmed: true`
+  means get a new link from the merchant. New README section on paying many
+  invoices (batch / resellers).
+- **0.1.14**: optional `--email <addr>` on `pay` (and on the create-order
+  scripts) stores a contact email with the order so ROZO can reach you if the
+  payment needs attention. Never required; an invalid address is rejected
+  before any order is created. Support channels (hi@rozo.ai, X, Discord) are
+  shown at order creation and whenever an order is not clean.
+- **0.1.13**: optional `--utm-source <label>` / `ROZO_CHECKOUT_UTM_SOURCE`
+  adds `attribution.utm_source` to created orders so distribution channels can
+  be measured. Invalid values are dropped, never failing an order.
 - **0.1.12**: pay Bitrefill invoices. `pay --bitrefill-invoice <id> --to <0x…>
   --amount <USDC> --expires-at <ISO>` creates a Rozo exactOut order through
   mpprouter that delivers the exact USDC on Base straight to the Bitrefill

package/docs/QUICKSTART.es.md

@@ -330,7 +330,7 @@ Leer `error.code`. Los tres con los que es más probable toparse:
 | `error.code` | Qué ocurrió | Qué hacer |
 |---|---|---|
 | `LINK_NO_LONGER_PAYABLE` | alguien ya pagó el enlace, o expiró | pedir al comercio un enlace nuevo; no pagar nada |
-| `EXPIRY_MARGIN` | queda muy poco tiempo para fondear, puentear y liquidar de forma segura | dejar que la orden expire y volver a empezar desde el paso 1 |
+| `EXPIRY_MARGIN` | queda muy poco tiempo para fondear, puentear y liquidar de forma segura | no fondear esta orden; dejar que expire y volver a empezar desde el paso 1 con el mismo enlace (se crea una orden nueva cuando se comprueba que la anterior no recibió fondos). Si responde `LINK_USED_OR_EXPIRED`, o `PAYMENT_EXPIRED` con `confirmed: true`, pedir al comercio un enlace nuevo |
 | `ALREADY_SENT` | ya hay un envío registrado para esta orden | **no** enviar de nuevo; ejecutar `status.js` y revisar primero la cadena |
 
 **Si algo de dinero ya salió de la billetera, nunca pagar de nuevo.** Conservar

package/docs/QUICKSTART.ja.md

@@ -306,7 +306,7 @@ node scripts/dist/status.js --rozo-payment-id <rozoPaymentId> --watch --timeout
 | `error.code` | 何が起きたか | どうするか |
 |---|---|---|
 | `LINK_NO_LONGER_PAYABLE` | そのリンクは既に誰かが支払ったか、期限切れです | 加盟店に新しいリンクを依頼してください。何も支払わないこと |
-| `EXPIRY_MARGIN` | 入金・ブリッジ・決済完了を安全に行うには残り時間が足りません | その注文は期限切れにさせ、ステップ 1 からやり直してください |
+| `EXPIRY_MARGIN` | 入金・ブリッジ・決済完了を安全に行うには残り時間が足りません | この注文には入金しないでください。期限切れになるのを待ち、同じリンクでステップ 1 からやり直してください（旧注文が未入金と確認されると新しい注文が作られます）。`LINK_USED_OR_EXPIRED`、または `confirmed: true` の `PAYMENT_EXPIRED` が返った場合は、加盟店に新しいリンクを依頼してください |
 | `ALREADY_SENT` | この注文に対する送金が既に記録されています | 再送信しては**いけません**。まず `status.js` を実行し、チェーンを確認してください |
 
 **ウォレットから既に資金が出ている場合は、決して二重に支払わないでください。**

package/docs/QUICKSTART.md

@@ -322,7 +322,7 @@ Read `error.code`. The three you are most likely to hit:
 | `error.code` | What happened | What to do |
 |---|---|---|
 | `LINK_NO_LONGER_PAYABLE` | someone already paid the link, or it expired | ask the merchant for a fresh link; do not pay anything |
-| `EXPIRY_MARGIN` | too little time left to fund, bridge and settle safely | let the order expire, then start again from step 1 |
+| `EXPIRY_MARGIN` | too little time left to fund, bridge and settle safely | do not fund this order; let it expire, then re-run from step 1 on the same link (a new order is created once the old one is proved unfunded). If that answers `LINK_USED_OR_EXPIRED` or `PAYMENT_EXPIRED` with `confirmed: true`, ask the merchant for a fresh link |
 | `ALREADY_SENT` | a send is already recorded for this order | do **not** send again; run `status.js` and check the chain first |
 
 **If any money has already left your wallet, never pay again.** Keep the

package/docs/QUICKSTART.zh.md

@@ -281,7 +281,7 @@ node scripts/dist/status.js --rozo-payment-id <rozoPaymentId> --watch --timeout
 | `error.code` | 发生了什么 | 该怎么办 |
 |---|---|---|
 | `LINK_NO_LONGER_PAYABLE` | 这个链接已经被别人付过，或者已过期 | 找商家要一个新链接；不要付任何钱 |
-| `EXPIRY_MARGIN` | 剩余时间太短，不足以安全完成充值、跨桥和结清 | 让订单过期，然后从第 1 步重新开始 |
+| `EXPIRY_MARGIN` | 剩余时间太短，不足以安全完成充值、跨桥和结清 | 不要给这个订单充值；等它过期后，用同一个链接从第 1 步重新开始（确认旧订单未收到付款后会生成新订单）。如果返回 `LINK_USED_OR_EXPIRED`，或 `PAYMENT_EXPIRED` 且 `confirmed: true`，就找商家要一个新链接 |
 | `ALREADY_SENT` | 这个订单已经记录过一次发送 | **不要**再发一次；先跑 `status.js` 并去链上核对 |
 
 **只要已经有钱离开了你的钱包，就绝不要再付一次。** 保留好 `linkId`、

package/llms.txt

@@ -25,6 +25,10 @@ calls with every safety rule already enforced:
 usdc-ethereum, usdt-polygon, usdc-polygon, usdc-base, usdc-stellar, btc-lightning
 (or raw: --chain 900 --token USDT).
 
+Optional: --email <addr> stores a contact email with the order so ROZO can reach
+the user if the payment needs attention. Ask the user once if they are present;
+never required, proceed without it if they decline or no one is there.
+
 DEFAULT PATH NEEDS NO KEY: `pay` prints a deposit address for the user to pay from
 any wallet. No private key, no environment variable, no configuration. Only the
 optional --send flag signs locally. Its key comes from the first source that
@@ -117,6 +121,8 @@ private key (EVM and Solana only); every other path is keyless.
      -d '{"url":"https://payments.coinbase.com/payment-links/pl_XXXX",
           "source":{"chainId":"900","tokenSymbol":"USDT"}}'
    -> { ok, reused, linkId, rozoPaymentId, paymentLink, expiresAt, source, ... }
+   Optional "email":"you@example.com" in the body stores a contact email with a
+   newly created order (a malformed value returns 400 INVALID_EMAIL).
    WARNING: if an unexpired order already exists for this link it is REUSED as-is,
    even with a different chain/token than you asked for. Always verify the returned
    source matches your request; abort on mismatch.
@@ -157,9 +163,24 @@ private key (EVM and Solana only); every other path is keyless.
 - After any on-chain payment is detected, never retry into a new order and never
   label the payment a normal failure — keep the tx hash and rozoPaymentId, keep
   polling, and escalate if it stays stuck.
+- An order that expired unfunded does not spend its link. First check your wallet: if
+  anything was sent to the old deposit, or a Lightning payment is still pending, do not
+  pay again; contact support with linkId + rozoPaymentId (the router cannot see a
+  pending Lightning payment). If nothing was sent, create-invoice on the SAME link again:
+  the router makes a new order once every earlier order is proved unfunded.
+  409 PAYMENT_EXPIRED retryable:true (confirmed:false) = not verifiable yet, wait a few
+  minutes and retry. 409 PAYMENT_EXPIRED confirmed:true or LINK_USED_OR_EXPIRED = ask
+  the merchant for a new link. 409 ORDER_ALREADY_ACTIVE = funds seen, do not pay again.
 
 ## Errors
 
 409 = link already used · 410 = link expired · UNSUPPORTED_SOURCE = the response's
 "supported" object lists valid (chainId, tokenSymbol) pairs (Lightning is supported
-but omitted from that list) · RATE_LIMITED = per-IP creation cap, retry later.
+but omitted from that list) · RATE_LIMITED = per-IP creation cap, retry later ·
+INVALID_EMAIL = the optional email is malformed; fix it or omit it.
+
+## Support
+
+If an order is stuck or anything goes wrong: email hi@rozo.ai, X
+https://x.com/ROZOai, Discord https://discord.gg/EfWejgTbuU. Include linkId,
+rozoPaymentId and any tx hash.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "type": "module",
   "description": "Pay OpenRouter, or any Coinbase invoice, with the crypto you already hold: USDT/USDC on Solana, BNB Chain, Ethereum or Polygon, USDC on Base or Stellar, or BTC over Lightning. No Coinbase account.",
   "license": "MIT",

package/scripts/dist/cli.js

@@ -41445,7 +41445,47 @@ process.on("warning", (warning) => {
 import readline2 from "node:readline";
 import { createRequire as createRequire2 } from "node:module";
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+var CONTACT_EMAIL_MAX_LENGTH = 254;
+var EMAIL_RE = /^[a-z0-9][^\s@]*@[^\s@.]+(\.[^\s@.]+)+$/;
+function normalizeContactEmail(raw) {
+  if (raw === void 0 || raw === null) return null;
+  if (typeof raw !== "string") return void 0;
+  const email = raw.trim().toLowerCase();
+  if (email.length === 0) return null;
+  if (email.length > CONTACT_EMAIL_MAX_LENGTH) return void 0;
+  if (/[\x00-\x1f\x7f]/.test(email) || !EMAIL_RE.test(email)) return void 0;
+  return email;
+}
+function contactEmailAttached(email, reused) {
+  return Boolean(email) && !reused;
+}
+function maskEmail(email) {
+  const at = String(email).lastIndexOf("@");
+  if (at <= 0) return "***";
+  return `${email[0]}***${email.slice(at)}`;
+}
+function contactEmailFromArgs(args) {
+  if (args.email === void 0) return null;
+  const email = args.email === true ? void 0 : normalizeContactEmail(String(args.email));
+  if (email === void 0) {
+    const err = new Error(
+      "--email must be a valid email address, for example name@example.com. It is optional: leave it out to continue without one."
+    );
+    err.code = "INVALID_EMAIL";
+    throw err;
+  }
+  return email;
+}
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
@@ -41457,7 +41497,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;
@@ -41704,6 +41745,14 @@ function isSupportedSource(chainId, tokenSymbol) {
   return SUPPORTED_SOURCES.some((s) => s.chainId === cid && s.tokens.includes(sym));
 }
 
+// scripts/src/lib/utm.mjs
+function normalizeUtmSource(value) {
+  if (typeof value !== "string") return null;
+  const s = value.trim().toLowerCase();
+  if (!s || s.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(s)) return null;
+  return s;
+}
+
 // scripts/src/lib/cli-args.mjs
 var COMMANDS = ["pay", "quote", "status", "help", "version"];
 var CHAIN_ALIASES = {
@@ -41834,7 +41883,11 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "to",
   "amount",
   "expires-at",
-  "provider"
+  "provider",
+  // Optional channel label for reporting (pay, quote)
+  "utm-source",
+  // Optional contact email so ROZO can reach the payer (pay)
+  "email"
 ]);
 function resolveFromPreset(value) {
   try {
@@ -41903,9 +41956,19 @@ function parseCliArgs(argv) {
   }
   const target = positional[1];
   const json = Boolean(flags.json);
+  let utmSource;
+  if (flags["utm-source"] !== void 0 && (command === "pay" || command === "quote")) {
+    utmSource = normalizeUtmSource(String(flags["utm-source"]));
+    if (!utmSource) {
+      throw new CliError(
+        "BAD_VALUE",
+        '--utm-source must be 1-100 characters of a-z, 0-9, ".", "_" or "-", starting with a letter or digit.'
+      );
+    }
+  }
   if (command === "quote") {
     if (!target) throw new CliError("MISSING_TARGET", "Usage: rozo-checkout quote <coinbase-link>");
-    return { command, target, json };
+    return { command, target, json, ...utmSource ? { utmSource } : {} };
   }
   if (command === "status") {
     if (!target) {
@@ -41981,6 +42044,16 @@ function parseCliArgs(argv) {
   } else {
     source = null;
   }
+  let email = null;
+  if (flags.email !== void 0) {
+    email = normalizeContactEmail(String(flags.email));
+    if (email === void 0) {
+      throw new CliError(
+        "INVALID_EMAIL",
+        "--email must be a valid email address, for example name@example.com. It is optional: leave it out to continue without one."
+      );
+    }
+  }
   const timeout = flags.timeout === void 0 ? 900 : Number(flags.timeout);
   if (!Number.isFinite(timeout) || timeout < 0) {
     throw new CliError("BAD_VALUE", "--timeout must be a non-negative number of seconds.");
@@ -42000,7 +42073,9 @@ function parseCliArgs(argv) {
     payer: flags.payer,
     fresh: flags.fresh === true,
     keyfile: flags.keyfile,
-    envFile: flags["env-file"]
+    envFile: flags["env-file"],
+    ...utmSource ? { utmSource } : {},
+    ...email ? { email } : {}
   };
 }
 var HELP = `rozo-checkout \u2014 pay a Coinbase Payment Link or a Bitrefill invoice
@@ -42050,6 +42125,10 @@ OPTIONS
                   gets signed.
   --fresh         ignore the remembered wallet address and coin for this run
   --rpc <url>     override the RPC endpoint for --send
+  --utm-source <s>  optional channel label for reporting; no identity, no
+                  privilege. Overrides ROZO_CHECKOUT_UTM_SOURCE.
+  --email <addr>  optional. A contact email stored with the order so ROZO can
+                  reach you if the payment needs attention. Never required.
   --help, -h      this text
   --version, -v   print the version
 
@@ -42057,11 +42136,15 @@ EXAMPLES
   npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01...
   npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01... --with usdt-solana
   npx @rozoai/checkout pay pl_01... --with btc-lightning
+  npx @rozoai/checkout pay pl_01... --with usdt-solana --email you@example.com
   npx @rozoai/checkout pay --bitrefill-invoice 8f3k2 --to 0xAbC\u2026123 --amount 7.90 --expires-at 2026-10-01T12:00:00Z --with usdc-stellar
   npx @rozoai/checkout status 11111111-2222-4333-8444-555555555555
 
 Creating an order moves no money; an unfunded order simply expires. Nothing is
-paid until you confirm, and --send is required before anything is signed.`;
+paid until you confirm, and --send is required before anything is signed.
+
+SUPPORT
+  Email hi@rozo.ai, X https://x.com/ROZOai, Discord https://discord.gg/EfWejgTbuU`;
 
 // scripts/src/lib/wallet-check.mjs
 var INTENT_API_BASE = process.env.ROZO_CHECKOUT_INTENT_API || "https://intentapi.rozo.ai";
@@ -54489,22 +54572,30 @@ var PKG_VERSION = (() => {
 var MPP_BASE = process.env.ROZO_CHECKOUT_MPP_BASE || "https://apiserver.mpprouter.dev/v1/services/rozo-agent-api";
 var CLIENT_LABEL = `rozo-checkout-cli/${PKG_VERSION}`;
 var ATTRIBUTION_CLIENT = `rozo-checkout-skill/${PKG_VERSION}`;
+function buildAttribution({ utmSource } = {}) {
+  const raw = utmSource !== void 0 ? utmSource : process.env.ROZO_CHECKOUT_UTM_SOURCE;
+  const utm_source = normalizeUtmSource(raw);
+  return { client: ATTRIBUTION_CLIENT, ...utm_source ? { utm_source } : {} };
+}
 var INTENTS_BASE = process.env.ROZO_CHECKOUT_INTENTS_BASE || "https://intentapiv4.rozo.ai/functions/v1/payment-api";
 async function quoteInvoice({ url, linkId }) {
   const body = url ? { url } : { payment_id: linkId };
   return postJson(`${MPP_BASE}/quote-invoice`, body);
 }
-async function createInvoice({ url, linkId, source, quoteReceipt }) {
+async function createInvoice({ url, linkId, source, quoteReceipt, utmSource, email }) {
   const body = {
     ...url ? { url } : { payment_id: linkId },
     source: { chainId: String(source.chainId), tokenSymbol: source.tokenSymbol },
     ...quoteReceipt ? { quoteReceipt } : {},
     client: CLIENT_LABEL,
-    attribution: { client: ATTRIBUTION_CLIENT }
+    attribution: buildAttribution({ utmSource }),
+    // Optional payer contact email (validated by the caller). Omitted, never
+    // sent empty, when the user gave none.
+    ...email ? { email } : {}
   };
   return postJson(`${MPP_BASE}/create-invoice`, body);
 }
-async function createBitrefillInvoice({ invoice, source }) {
+async function createBitrefillInvoice({ invoice, source, utmSource, email }) {
   const body = {
     provider: "bitrefill",
     bitrefill: {
@@ -54515,7 +54606,8 @@ async function createBitrefillInvoice({ invoice, source }) {
     },
     source: { chainId: String(source.chainId), tokenSymbol: source.tokenSymbol },
     client: CLIENT_LABEL,
-    attribution: { client: ATTRIBUTION_CLIENT }
+    attribution: buildAttribution({ utmSource }),
+    ...email ? { email } : {}
   };
   return postJson(`${MPP_BASE}/create-invoice`, body);
 }
@@ -54909,7 +55001,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
         });
       }
@@ -54935,7 +55027,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.`, {
@@ -55085,6 +55177,7 @@ async function main2(argv) {
   }
   const requested = { chainId, tokenSymbol };
   const confirmed = Boolean(args.confirm);
+  const email = contactEmailFromArgs(args);
   let blacklist;
   try {
     blacklist = loadBlacklist();
@@ -55101,7 +55194,9 @@ async function main2(argv) {
   const created = await createInvoice({
     url: String(url),
     source: requested,
-    quoteReceipt
+    quoteReceipt,
+    utmSource: typeof args["utm-source"] === "string" ? args["utm-source"] : void 0,
+    email
   });
   if (!created?.rozoPaymentId) {
     throw new SkillError("CREATE_FAILED", "create-invoice returned no rozoPaymentId.", {
@@ -55258,6 +55353,13 @@ async function main2(argv) {
     success: true,
     step: "create-order",
     confirmed,
+    // True only when an email went out with a NEW order. A reused order keeps
+    // whatever email it was first created with (the router never rebinds), so
+    // reporting true there would be a false promise. The address itself is
+    // never echoed. Note the --confirm run always sees the order as reused;
+    // the CLI carries the first run's value forward.
+    contactEmailProvided: contactEmailAttached(email, created.reused),
+    support: SUPPORT,
     reused: Boolean(created.reused),
     reusedNote: created.reused ? `An existing unpaid order for this link was reused (${rozoPaymentId}), valid for another ${formatRemaining(expiry.msRemaining)}. Nothing new was created.` : null,
     orderCost: "Creating an order moves no money. An order you never fund simply expires and costs nothing.",
@@ -55532,6 +55634,7 @@ async function main3(argv) {
   }
   const requested = { chainId, tokenSymbol };
   const confirmed = Boolean(args.confirm);
+  const email = contactEmailFromArgs(args);
   const rawInvoice = {
     invoiceId: args["invoice-id"],
     address: args.to,
@@ -55552,7 +55655,12 @@ async function main3(argv) {
   let rozoPaymentId;
   let resumed = false;
   try {
-    created = await createBitrefillInvoice({ invoice, source: requested });
+    created = await createBitrefillInvoice({
+      invoice,
+      source: requested,
+      utmSource: typeof args["utm-source"] === "string" ? args["utm-source"] : void 0,
+      email
+    });
   } catch (err) {
     const existing = duplicateInvoicePaymentId(err);
     if (!existing) throw explainRouterError(err);
@@ -55655,6 +55763,9 @@ async function main3(argv) {
     step: "create-order",
     provider: PROVIDER_BITREFILL,
     confirmed,
+    // False on a resumed order: the router does not attach an email to it.
+    contactEmailProvided: contactEmailAttached(email, resumed),
+    support: SUPPORT,
     reused: resumed,
     reusedNote: resumed ? `An order for this Bitrefill invoice already existed (${rozoPaymentId}); it was resumed. Nothing new was created.` : null,
     orderCost: "Creating an order moves no money. An order you never fund simply expires and costs nothing.",
@@ -55866,6 +55977,23 @@ async function snapshot({ rozoPaymentId, linkId, provider: explicitProvider }) {
     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 main4(argv) {
   const args = parseArgs(argv);
   const rozoPaymentId = args["rozo-payment-id"] || (isRozoPaymentId(args._[0]) ? args._[0] : null);
@@ -55891,7 +56019,7 @@ async function main4(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;
   emit(
@@ -55901,7 +56029,9 @@ async function main4(argv) {
       ...result,
       history,
       guidance,
-      timedOut: unresolved
+      timedOut: unresolved,
+      // Anything short of a clean answer gets a human contact.
+      ...failed || unresolved ? { support: SUPPORT } : {}
     },
     failed ? EXIT_ERROR : unresolved ? EXIT_UNCONFIRMED : 0
   );
@@ -56971,6 +57101,9 @@ function printError(payload) {
   if (e.message) out(`  ${e.message}`);
   if (payload?.guidance) out(`  ${yellow(payload.guidance)}`);
 }
+function printSupport() {
+  out(`  ${dim(SUPPORT_TEXT)}`);
+}
 function printMoneyWarning(payload) {
   if (!payload?.moneyDetected) return;
   out();
@@ -57119,6 +57252,7 @@ async function cmdStatus(opts) {
   }
   if (payload.error) {
     printError(payload);
+    printSupport();
     return exitCode;
   }
   out();
@@ -57130,6 +57264,7 @@ async function cmdStatus(opts) {
   if (payload.payin?.txHash) out(`  Pay-in  ${payload.payin.txHash}`);
   if (payload.guidance) out(`  ${payload.escalate ? red(payload.guidance) : dim(payload.guidance)}`);
   printMoneyWarning(payload);
+  if (payload.support) printSupport();
   out();
   return exitCode;
 }
@@ -57204,6 +57339,10 @@ async function cmdPay(opts) {
   }
   const { chainId, tokenSymbol } = opts.source;
   const createFlow = opts.bitrefill ? run3 : run2;
+  const utmArgs = [
+    ...opts.utmSource ? ["--utm-source", opts.utmSource] : [],
+    ...opts.email ? ["--email", opts.email] : []
+  ];
   const baseArgs = opts.bitrefill ? [
     "--invoice-id",
     opts.bitrefill.invoiceId,
@@ -57215,8 +57354,9 @@ async function cmdPay(opts) {
     "--chain",
     chainId,
     "--token",
-    tokenSymbol
-  ] : ["--url", opts.target, "--chain", chainId, "--token", tokenSymbol];
+    tokenSymbol,
+    ...utmArgs
+  ] : ["--url", opts.target, "--chain", chainId, "--token", tokenSymbol, ...utmArgs];
   if (opts.send) {
     const family = chainFamily(chainId);
     if (family === "evm" || family === "solana") {
@@ -57235,6 +57375,7 @@ async function cmdPay(opts) {
     else {
       printError(created.payload);
       printMoneyWarning(created.payload);
+      printSupport();
     }
     return created.exitCode;
   }
@@ -57264,6 +57405,12 @@ async function cmdPay(opts) {
       p.reused ? `  ${dim(`Reusing existing unpaid order ${p.rozoPaymentId} \u2014 nothing new was created.`)}` : `  ${dim(`Order created: ${p.rozoPaymentId}`)}`
     );
     out(`  ${dim("An order you never fund simply expires and costs nothing.")}`);
+    if (opts.email) {
+      out(
+        p.reused ? `  ${dim(`Contact   ${maskEmail(opts.email)} was not attached: this order already existed.`)}` : `  ${dim(`Contact   ${maskEmail(opts.email)}, so ROZO can reach you if this payment needs attention.`)}`
+      );
+    }
+    printSupport();
     out();
     out(dim(`  The amount you send includes bridge and network fees, so it is`));
     out(dim(`  normally larger than the invoice.`));
@@ -57294,10 +57441,12 @@ async function cmdPay(opts) {
     else {
       printError(confirmed.payload);
       printMoneyWarning(confirmed.payload);
+      printSupport();
     }
     return confirmed.exitCode;
   }
   const deposit = confirmed.payload.deposit;
+  confirmed.payload.contactEmailProvided = Boolean(p.contactEmailProvided);
   if (!opts.json) {
     out(`  ${dim(`Confirming order ${rozoPaymentId} \u2014 no second order was created.`)}`);
   }
@@ -57333,6 +57482,7 @@ async function cmdPay(opts) {
     } else if (!sent.payload.success) {
       printError(sent.payload);
       printMoneyWarning(sent.payload);
+      printSupport();
       return sent.exitCode;
     } else if (opts.dryRun) {
       if (sent.payload.keySource) out(`  ${dim(`would sign with ${sent.payload.keySource}`)}`);
@@ -57382,6 +57532,7 @@ async function cmdPay(opts) {
     out(`  ${watched.payload.escalate ? red(watched.payload.guidance) : dim(watched.payload.guidance)}`);
   }
   printMoneyWarning(watched.payload);
+  if (watched.payload.state !== "settled") printSupport();
   out();
   return watched.exitCode;
 }
@@ -57465,6 +57616,9 @@ async function main7() {
 main7().then((code) => process.exit(code ?? EXIT_OK)).catch((err) => {
   const payload = formatFailure(err);
   if (process.argv.includes("--json")) printJson(payload);
-  else printError(payload);
+  else {
+    printError(payload);
+    printSupport();
+  }
   process.exit(EXIT_ERROR);
 });

package/scripts/dist/create-order.js

@@ -6,7 +6,42 @@ const require = __rozoCreateRequire(import.meta.url);
 const __filename = __rozoFileURLToPath(import.meta.url);
 const __dirname = __rozoDirname(__filename);
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+var CONTACT_EMAIL_MAX_LENGTH = 254;
+var EMAIL_RE = /^[a-z0-9][^\s@]*@[^\s@.]+(\.[^\s@.]+)+$/;
+function normalizeContactEmail(raw) {
+  if (raw === void 0 || raw === null) return null;
+  if (typeof raw !== "string") return void 0;
+  const email = raw.trim().toLowerCase();
+  if (email.length === 0) return null;
+  if (email.length > CONTACT_EMAIL_MAX_LENGTH) return void 0;
+  if (/[\x00-\x1f\x7f]/.test(email) || !EMAIL_RE.test(email)) return void 0;
+  return email;
+}
+function contactEmailAttached(email, reused) {
+  return Boolean(email) && !reused;
+}
+function contactEmailFromArgs(args) {
+  if (args.email === void 0) return null;
+  const email = args.email === true ? void 0 : normalizeContactEmail(String(args.email));
+  if (email === void 0) {
+    const err = new Error(
+      "--email must be a valid email address, for example name@example.com. It is optional: leave it out to continue without one."
+    );
+    err.code = "INVALID_EMAIL";
+    throw err;
+  }
+  return email;
+}
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
@@ -17,7 +52,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;
@@ -224,6 +260,14 @@ function postJson(url, body, opts) {
   return request("POST", url, { ...opts, body });
 }
 
+// scripts/src/lib/utm.mjs
+function normalizeUtmSource(value) {
+  if (typeof value !== "string") return null;
+  const s = value.trim().toLowerCase();
+  if (!s || s.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(s)) return null;
+  return s;
+}
+
 // scripts/src/lib/api.mjs
 var PKG_VERSION = (() => {
   const requireFrom = createRequire(import.meta.url);
@@ -239,18 +283,26 @@ var PKG_VERSION = (() => {
 var MPP_BASE = process.env.ROZO_CHECKOUT_MPP_BASE || "https://apiserver.mpprouter.dev/v1/services/rozo-agent-api";
 var CLIENT_LABEL = `rozo-checkout-cli/${PKG_VERSION}`;
 var ATTRIBUTION_CLIENT = `rozo-checkout-skill/${PKG_VERSION}`;
+function buildAttribution({ utmSource } = {}) {
+  const raw = utmSource !== void 0 ? utmSource : process.env.ROZO_CHECKOUT_UTM_SOURCE;
+  const utm_source = normalizeUtmSource(raw);
+  return { client: ATTRIBUTION_CLIENT, ...utm_source ? { utm_source } : {} };
+}
 var INTENTS_BASE = process.env.ROZO_CHECKOUT_INTENTS_BASE || "https://intentapiv4.rozo.ai/functions/v1/payment-api";
 async function quoteInvoice({ url, linkId }) {
   const body = url ? { url } : { payment_id: linkId };
   return postJson(`${MPP_BASE}/quote-invoice`, body);
 }
-async function createInvoice({ url, linkId, source, quoteReceipt }) {
+async function createInvoice({ url, linkId, source, quoteReceipt, utmSource, email }) {
   const body = {
     ...url ? { url } : { payment_id: linkId },
     source: { chainId: String(source.chainId), tokenSymbol: source.tokenSymbol },
     ...quoteReceipt ? { quoteReceipt } : {},
     client: CLIENT_LABEL,
-    attribution: { client: ATTRIBUTION_CLIENT }
+    attribution: buildAttribution({ utmSource }),
+    // Optional payer contact email (validated by the caller). Omitted, never
+    // sent empty, when the user gave none.
+    ...email ? { email } : {}
   };
   return postJson(`${MPP_BASE}/create-invoice`, body);
 }
@@ -1153,6 +1205,7 @@ async function main(argv) {
   }
   const requested = { chainId, tokenSymbol };
   const confirmed = Boolean(args.confirm);
+  const email = contactEmailFromArgs(args);
   let blacklist;
   try {
     blacklist = loadBlacklist();
@@ -1169,7 +1222,9 @@ async function main(argv) {
   const created = await createInvoice({
     url: String(url),
     source: requested,
-    quoteReceipt
+    quoteReceipt,
+    utmSource: typeof args["utm-source"] === "string" ? args["utm-source"] : void 0,
+    email
   });
   if (!created?.rozoPaymentId) {
     throw new SkillError("CREATE_FAILED", "create-invoice returned no rozoPaymentId.", {
@@ -1326,6 +1381,13 @@ async function main(argv) {
     success: true,
     step: "create-order",
     confirmed,
+    // True only when an email went out with a NEW order. A reused order keeps
+    // whatever email it was first created with (the router never rebinds), so
+    // reporting true there would be a false promise. The address itself is
+    // never echoed. Note the --confirm run always sees the order as reused;
+    // the CLI carries the first run's value forward.
+    contactEmailProvided: contactEmailAttached(email, created.reused),
+    support: SUPPORT,
     reused: Boolean(created.reused),
     reusedNote: created.reused ? `An existing unpaid order for this link was reused (${rozoPaymentId}), valid for another ${formatRemaining(expiry.msRemaining)}. Nothing new was created.` : null,
     orderCost: "Creating an order moves no money. An order you never fund simply expires and costs nothing.",

package/scripts/dist/quote.js

@@ -6,7 +6,16 @@ const require = __rozoCreateRequire(import.meta.url);
 const __filename = __rozoFileURLToPath(import.meta.url);
 const __dirname = __rozoDirname(__filename);
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
@@ -17,7 +26,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;

package/scripts/dist/send-evm.js

@@ -9972,7 +9972,16 @@ var init_call = __esm({
   }
 });
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_UNCONFIRMED = 3;
@@ -9983,7 +9992,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;

package/scripts/dist/send-sol.js

@@ -32143,7 +32143,16 @@ Message: ${transactionMessage}.
   }
 });
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_UNCONFIRMED = 3;
@@ -32154,7 +32163,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;

package/scripts/dist/status.js

@@ -6,7 +6,16 @@ const require = __rozoCreateRequire(import.meta.url);
 const __filename = __rozoFileURLToPath(import.meta.url);
 const __dirname = __rozoDirname(__filename);
 
+// scripts/src/lib/support.mjs
+var SUPPORT = Object.freeze({
+  email: "hi@rozo.ai",
+  x: "https://x.com/ROZOai",
+  discord: "https://discord.gg/EfWejgTbuU"
+});
+var SUPPORT_TEXT = `Need help? Email ${SUPPORT.email}, or reach ROZO on X ${SUPPORT.x} or Discord ${SUPPORT.discord}.`;
+
 // scripts/src/lib/output.mjs
+var PUBLIC_SUPPORT_URLS = /* @__PURE__ */ new Set([SUPPORT.x, SUPPORT.discord]);
 var EXIT_OK = 0;
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
@@ -18,7 +27,8 @@ function redact(text) {
   s = s.replace(/\b[0-9a-fA-F]{64}\b/g, "<redacted>");
   s = s.replace(/\b[1-9A-HJ-NP-Za-km-z]{80,90}\b/g, "<redacted>");
   s = s.replace(/\[(?:\s*\d{1,3}\s*,){40,}\s*\d{1,3}\s*\]/g, "[<redacted>]");
-  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (_m, scheme, rest) => {
+  s = s.replace(/\b([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^\s"'<>]+)/g, (m, scheme, rest) => {
+    if (PUBLIC_SUPPORT_URLS.has(m.replace(/[.,;:!?)]+$/, ""))) return m;
     const withoutUserinfo = rest.includes("@") ? rest.slice(rest.indexOf("@") + 1) : rest;
     const host = withoutUserinfo.split(/[/?#]/)[0];
     const hadMore = withoutUserinfo.length > host.length;
@@ -423,7 +433,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
         });
       }
@@ -449,7 +459,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.`, {
@@ -712,6 +722,23 @@ async function snapshot({ rozoPaymentId, linkId, provider: explicitProvider }) {
     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);
@@ -737,7 +764,7 @@ 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;
   emit(
@@ -747,7 +774,9 @@ async function main(argv) {
       ...result,
       history,
       guidance,
-      timedOut: unresolved
+      timedOut: unresolved,
+      // Anything short of a clean answer gets a human contact.
+      ...failed || unresolved ? { support: SUPPORT } : {}
     },
     failed ? EXIT_ERROR : unresolved ? EXIT_UNCONFIRMED : 0
   );