@rozoai/checkout 0.1.10 → 0.1.12

package/README.md

@@ -2,11 +2,34 @@
 
 **English** | [简体中文](docs/README.zh.md) | [日本語](docs/README.ja.md) | [Español](docs/README.es.md)
 
-Pay an **OpenRouter Coinbase Payment Link** with a coin that link cannot take
-directly — BTC over Lightning, or USDT/USDC on Solana, BNB Chain, Ethereum,
-Polygon, Base or Stellar. A Coinbase Payment Link only accepts USDC on Base;
-this routes the coin you actually hold through a bridge, and a funder wallet
-settles the invoice for you. No account, no API key, no browser.
+### When your agent needs to pay OpenRouter (or any Coinbase invoice) with the crypto you already hold
+
+OpenRouter crypto top-ups and other Coinbase-hosted invoices settle in USDC on
+Base. This skill pays them from whatever you hold instead, and it does three
+things the official path cannot:
+
+- **Pay from the chain you are already on.** USDT or USDC on Solana, BNB Chain,
+  Ethereum or Polygon, USDC on Base or Stellar, or BTC over Lightning. Coinbase's
+  own direct pay takes USDC on Base.
+- **No Coinbase account.** Pay the deposit address from any wallet or straight
+  from an exchange withdrawal. No sign-up, no API key, no browser.
+- **Scriptable.** OpenRouter's crypto credits API (`POST /api/v1/credits/coinbase`)
+  now returns `410 Gone`, so top-ups can no longer be automated there. Once you
+  have the payment link, paying it is one command an agent or a cron job can
+  run: without a terminal it stops for confirmation, so an unattended caller
+  reviews the quote and then passes `--yes`.
+
+Merchants we have been paid through so far: **OpenRouter, Venice.ai, Porkbun
+and Alchemy**. Any `payments.coinbase.com` link is quoted the same way.
+
+Before you pay, know two things:
+
+- **The fee is in the live quote.** You pay the full invoice, no discount and no
+  markup on it; the bridge and network fee is added to the deposit amount, which
+  is shown in the order summary before the deposit address is released. Send
+  exactly that amount, nothing more is charged.
+- **Crypto payments to OpenRouter are never refundable.** That is OpenRouter's
+  policy, not ours; check the credit amount before you send.
 
 ```bash
 npx @rozoai/checkout pay <coinbase-link>
@@ -17,6 +40,14 @@ prompt and it will mark which coins you can actually afford — then prints a
 deposit address for you to pay from any wallet — **no private key, no environment variable, no
 configuration** — and waits until the invoice is settled.
 
+Paying a **Bitrefill** invoice instead? Create it on Bitrefill with "USDC on
+Base", then pass its id, address and amount (Coinbase payment links and
+Bitrefill invoices are the two supported targets; Stripe is not):
+
+```bash
+npx @rozoai/checkout pay --bitrefill-invoice <id> --to <0x…> --amount 7.90 --expires-at <ISO> --with usdc-stellar
+```
+
 Know your coin already? Skip the question:
 
 ```bash
@@ -62,6 +93,21 @@ already hold and pay from wherever it already lives.
 
 ## Use it from your agent
 
+Install it as a skill, or just run the CLI:
+
+```text
+# Claude Code
+/plugin marketplace add RozoAI/rozo-checkout-skill
+/plugin install rozo-checkout@rozo
+
+# OpenClaw / ClawHub
+clawhub install rozo-checkout
+
+# Any agent that can run a shell: review the quote, then pay unattended
+npx @rozoai/checkout quote <coinbase-link>
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana --yes
+```
+
 The payload is the same everywhere: the one-liner above, or point the agent at
 [llms.txt](llms.txt). Agents and scripts should always pass `--with` — the
 picker only appears on a terminal, and there is deliberately no default coin. **Paying from your own wallet never needs a key.** Only
@@ -274,7 +320,7 @@ Stellar and Lightning are Mode A only.
 <summary><b>Terminal — no agent at all</b> — run the scripts step by step</summary>
 
 Drive each step yourself. The bundles are self-contained; nothing to install
-beyond Node 18+.
+beyond Node 20.18+.
 
 ```bash
 git clone https://github.com/RozoAI/rozo-checkout-skill && cd rozo-checkout-skill
@@ -348,6 +394,16 @@ The full list of what this refuses to do, and why, is in
 
 ## Changelog
 
+- **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
+  invoice address, payable from Stellar USDC or any supported coin.
+- **0.1.11**: each order now carries `attribution.client`
+  (`rozo-checkout-skill/<version>`) so skill-created orders can be told apart
+  from the web checkout. Installable as a Claude Code plugin
+  (`/plugin marketplace add RozoAI/rozo-checkout-skill`). README and skill
+  description rewritten around paying Coinbase invoices from the crypto you
+  already hold.
 - **0.1.3** — fixes found by the first real payment. The built bundles no
   longer crash with `__filename is not defined` on Node 22+ (the esbuild banner
   now shims `__filename`/`__dirname` as well as `require`, and every bundle is
@@ -372,3 +428,7 @@ The full list of what this refuses to do, and why, is in
 ## License
 
 MIT.
+
+## Secret scanning
+
+Enable the local gitleaks pre-commit hook once per clone: `brew install gitleaks pre-commit && pre-commit install` (config in `.pre-commit-config.yaml`). CI also runs a report-only scan in `.github/workflows/secret-scan.yml`.

package/docs/review-history.md

@@ -0,0 +1,77 @@
+# Review history
+
+[← back to the README](../README.md) · [Safety design](safety.md)
+
+This tool moves other people's money. It was reviewed adversarially before it
+was written, again after it was written, and again after the first real payment.
+This page is the record of that.
+
+## Design review — 3 rounds, before any code existed
+
+The design was written as a plan document and reviewed by an independent model
+with a standing instruction to hunt for anything that could lose funds. No code
+was written until the plan passed with no P0 findings.
+
+| Round | Verdict |
+|---|---|
+| 1 | 6 P0, 7 P1, 2 P2 — plan revised |
+| 2 | still had P0s: several round-1 fixes were incomplete, plus one new P0 — plan revised again |
+| 3 | no P0 — implementation began |
+
+The P0s were about the plan being wrong regarding the payment rails, not about
+style. Among them: the reuse rule was mis-stated (an existing order is reused
+whenever it is merely unexpired, not only when it is unpaid); the binding
+confirmation was placed before the deposit details existed, so it could not
+bind them; and the payment link could be consumed by another payer between the
+quote and the signature, which needed a re-check immediately before paying.
+
+## Code review — 2 rounds, after implementation
+
+| Round | Verdict |
+|---|---|
+| 1 | 8 P0, 10 P1, 5 P2 |
+| 2 | 20 of 23 resolved; 3 residual findings, then fixed |
+
+The round-1 P0s were the interesting ones, and each is now a real code path
+with its own error code and tests:
+
+- the confirmation gate and the `--send` opt-in were documented but not
+  actually enforced
+- the send-once claim was a check-then-act race that two concurrent processes
+  could both pass
+- an unreadable `amountReceived` was treated as "no money received" rather than
+  as money
+- the post-create comparison ignored security-critical fields when they were
+  simply absent
+- payability was not re-proved immediately before signing, and incomplete
+  upstream state read as payable
+- deposit instructions were not validated for completeness before being shown
+- provider errors could leak credential-bearing URLs
+- the tracked-secret check failed open when it could not consult git
+
+## First real payment
+
+A live payment then settled in about a minute — and surfaced four more defects,
+all fixed in 0.1.3:
+
+- the built bundles crashed on newer Node because the bundler's CommonJS shim
+  was incomplete; it had never been caught because only `--help` was ever run
+  against a built bundle. The test suite now executes every bundle.
+- the Stellar memo type was not stated anywhere, and sending that memo with the
+  wrong type loses the payment. It is `MEMO_TEXT`, and the deposit block now
+  says so.
+- reusing an existing unpaid order, and asking for a coin that differs from it,
+  both read as errors rather than as the ordinary situations they are
+- nothing showed how long an order had left, and a real payment nearly missed
+  its window
+
+## What this means for a reader
+
+Every finding above is closed, and the behaviours they produced are covered by
+the test suite, which runs entirely offline against recorded fixtures. The full
+list of what this tool refuses to do, and why, is in
+[docs/safety.md](safety.md).
+
+The detailed review transcripts are kept internally; they quote source from
+private repositories and so are not published here. The findings themselves are
+summarised above in full — nothing material is omitted.

package/llms.txt

@@ -1,8 +1,10 @@
 # rozo-checkout
 
-> Pay an OpenRouter Coinbase Payment Link (payments.coinbase.com/payment-links/pl_* or
-> /payment-sessions/paymentSession_*) with BTC over Lightning, or USDT/USDC on Solana,
-> BNB Chain, Ethereum, Polygon, Base, or Stellar. Public HTTP endpoints, no API key.
+> When your agent needs to pay OpenRouter (or any Coinbase invoice) with the crypto you
+> already hold. Pays a Coinbase Payment Link (payments.coinbase.com/payment-links/pl_* or
+> /payment-sessions/paymentSession_*) with BTC over Lightning, USDT/USDC on Solana,
+> BNB Chain, Ethereum or Polygon, or USDC on Base or Stellar. No Coinbase account, public HTTP
+> endpoints, no API key. Crypto payments to OpenRouter are never refundable.
 > The payer funds a one-time deposit address; a bridge and a funder wallet settle the
 > Coinbase link automatically. No discount: you pay the invoice amount, plus the
 > deposit normally carries a small bridge/source-chain fee on top.
@@ -35,6 +37,22 @@ directory (or --env-file <path>): only ROZO_CHECKOUT_* keys are read from it, it
 is parsed as text and never shell-evaluated, and the real environment wins.
 Key files and .env must be chmod 600 and untracked by git.
 
+## Bitrefill invoices
+
+Also supported: a Bitrefill invoice created with "USDC on Base" (Stripe is not supported).
+No quote step; mpprouter creates an exactOut order paying exactly that amount to the
+Bitrefill address:
+
+  npx @rozoai/checkout pay --bitrefill-invoice <id> --to <0x…> --amount 7.90 --expires-at <ISO> --with usdc-stellar
+
+Router call: POST {MPP}/create-invoice {"provider":"bitrefill","bitrefill":{"invoiceId","address",
+"amount","expiresAt" (required, ≤30 min out)},"source":{"chainId","tokenSymbol"}}. Verify the response echoes the same
+invoiceId/address/amount, and that GET payments/<rozoPaymentId> destination has the same
+chain/token/address/amount (missing = mismatch), before showing the deposit or sending.
+Expiry = the invoice expiry only; refuse to show/send under 2 min. 409 DUPLICATE_INVOICE returns
+the existing rozoPaymentId: resume it. Settled = payment_payout_completed (or completed with a
+payout tx hash). 503 BITREFILL_NOT_CONFIGURED / RETRY_LATER: nothing created, retry later.
+
 ## Local wallet setup for --send (not needed for the default keyless path)
 
 .env keys (only ROZO_CHECKOUT_* are read; real env wins; chmod 600; gitignore):

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
-  "description": "Pay an OpenRouter Coinbase Payment Link with BTC Lightning, or USDT/USDC on Solana, BNB Chain, Ethereum, Polygon, Base or Stellar.",
+  "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",
   "author": "Rozo AI",
   "homepage": "https://github.com/RozoAI/rozo-checkout-skill#readme",
@@ -15,13 +15,29 @@
   },
   "keywords": [
     "openrouter",
+    "openrouter-credits",
     "coinbase",
-    "x402",
-    "lightning",
-    "solana",
-    "usdt",
+    "coinbase-payment-link",
     "usdc",
-    "crypto-payments"
+    "usdt",
+    "solana",
+    "bnb-chain",
+    "ethereum",
+    "polygon",
+    "base",
+    "stellar",
+    "lightning",
+    "bitcoin",
+    "crypto-payments",
+    "agent",
+    "ai-agent",
+    "agent-skill",
+    "claude-skill",
+    "claude-code",
+    "payments",
+    "cli",
+    "mcp-free",
+    "x402"
   ],
   "bin": {
     "rozo-checkout": "scripts/dist/cli.js"
@@ -35,7 +51,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "access": "public"
@@ -47,9 +63,13 @@
     "prepack": "npm run build"
   },
   "devDependencies": {
-    "@solana/spl-token": "^0.4.9",
     "@solana/web3.js": "^1.95.0",
     "esbuild": "^0.28.2",
     "viem": "^2.21.0"
+  },
+  "overrides": {
+    "jayson": {
+      "uuid": "^11.1.1"
+    }
   }
 }