@rozoai/checkout 0.1.14 → 0.1.16

package/README.md

@@ -372,6 +372,120 @@ 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`, or the simpler
+`paymentOutcome` and `nextAction` fields.
+
+For a yes/no answer, use `receipt`. It exits 0 only when Coinbase itself
+reports the invoice paid (v3 `CAPTURE_SUCCEEDED`), 3 while the payment is in
+flight or unknown, and 1 if the order expired unpaid or needs a human:
+
+```bash
+rozo-checkout receipt <rozoPaymentId> --json | jq '.receipt | .paymentOutcome, .merchantSettlement.status'
+```
+
+It reports your payment, the merchant invoice and service delivery as separate
+layers. Delivery is always `unknown`: Rozo cannot see your OpenRouter credits.
+
+With `--send`, the wallet must also hold the chain's fee coin (ETH, BNB, POL or
+SOL). If it does not, the CLI stops with `INSUFFICIENT_GAS` before signing and
+tells you how much is missing; the order is left untouched.
+
+**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
@@ -400,6 +514,24 @@ The full list of what this refuses to do, and why, is in
 
 ## Changelog
 
+- **0.1.16**: new `receipt` command: one read, exit 0 only when the merchant
+  side itself reports the invoice paid (Coinbase v3 `CAPTURE_SUCCEEDED`, v1 usage
+  count, or the Bitrefill payout), reported as three layers
+  (your payment, merchant invoice, service delivery). `status` adds
+  `paymentOutcome`, `nextAction` and `sendWindow`; `nextAction.canSend` is the
+  only field that permits paying. With `--send`, the wallet's fee coin (ETH,
+  BNB, POL, SOL; on Base including the L1 data fee) is checked before signing:
+  `INSUFFICIENT_GAS` says how much is missing and leaves the order untouched.
+  Transaction hashes this tool reports are no longer masked; anything inside
+  error text still is.
+- **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

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

@@ -163,6 +163,14 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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",