@rozoai/checkout 0.1.0

package/QUICKSTART.zh.md

@@ -0,0 +1,178 @@
+# 快速开始
+
+[English](QUICKSTART.md) | **简体中文** | [日本語](QUICKSTART.ja.md) | [Español](QUICKSTART.es.md)
+
+用 Solana、BNB Chain、Ethereum、Polygon、Base 或 Stellar 上的 USDT/USDC，或者用走
+Lightning 的 BTC，去支付一个 OpenRouter Coinbase 收款链接 (Payment Link)。五分钟搞定。
+工作原理与设计理由见 [README.md](README.md)。
+
+## 一行命令搞定
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID --with usdt-solana
+```
+
+这一条命令会替你跑完下面的每一步：报价、创建订单、核对、确认、充值指令，然后一直轮询到结清。`--with` 可选的币种有：`usdt-solana`、`usdc-solana`、`usdt-bnb`、`usdc-bnb`、`usdt-ethereum`、`usdc-ethereum`、`usdt-polygon`、`usdc-polygon`、`usdc-base`、`usdc-stellar`、`btc-lightning`。
+
+加 `--send` 就用热钱包付款而不是用你自己的钱包，加 `--json` 输出机器可读格式。
+
+本页剩下的内容就是同一套流程，只不过一步一步来 —— 如果出了问题，或者你想自己写脚本，那才需要看它们。
+
+## 开始之前
+
+- **Node 18 或更高版本**（`node -v`）。别的什么都不用装 —— `npx` 会去拉取 CLI，而克隆下来的
+  `scripts/dist/*.js` 都是自包含的打包产物。
+- **一个钱包**，在你选的链上持有你想用来付款的币种。
+- **那个 Coinbase 链接**，例如
+  `https://payments.coinbase.com/payment-links/pl_01YOURLINKID`。
+- 不需要账号，也不需要 API key。这里用到的每个端点都是公开的。
+
+先设一次：
+
+```bash
+LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
+```
+
+链 id：`1` Ethereum · `56` BNB Chain · `137` Polygon · `8453` Base ·
+`900` Solana · `1500` Stellar · `lightning` Bitcoin Lightning。
+
+## 1. 报价（只读，免费）
+
+```bash
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "5.00", "fiat": { "amount": "5.00", "currency": "USD" } },
+  "callerPays": "5.00",
+  "coinbaseExpiryIso": "2026-08-09T10:00:00.000Z"
+}
+```
+
+`"success": false` 且带 `LINK_NO_LONGER_PAYABLE`，说明这个链接已被付过或已过期 ——
+去要一个新的，然后停止。
+
+## 2. 创建订单
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+```
+
+这一步不动任何资金，未付款的订单会自然过期。完整充值地址 (deposit address) 在此阶段
+会被**扣留** —— 你只拿到打码后的摘要，先用它核对。
+
+```json
+{
+  "success": true,
+  "rozoPaymentId": "11111111-2222-4333-8444-555555555555",
+  "invoice": { "amount": "5.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "5.021000 USDT",
+    "payToMasked": "9WzDXw...AWWM",
+    "memoRequirement": "This deposit REQUIRES the memo/tag below. ..."
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+**继续之前务必核对 `display.amount`。** 它通常大于账单金额 —— 因为它包含了跨桥费用和
+网络费用。记下 `rozoPaymentId`；后面每一条命令都要用它。
+
+## 3. 确认
+
+只有在你已经决定付款之后，才带上 `--confirm` 重新执行同一条命令：
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+```
+
+这会释放完整的充值详情，并记录下发送脚本所需的那条确认。
+
+```json
+{
+  "success": true,
+  "confirmed": true,
+  "deposit": {
+    "chain": "Solana",
+    "tokenSymbol": "USDT",
+    "receiverAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+    "receiverMemo": "rozo-901",
+    "amount": "5.021000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+对于 Lightning，`deposit.lnInvoice` 里是供扫码的 BOLT11 字符串，`deposit.amount`
+的单位是聪 (satoshis)。
+
+## 4. 付款
+
+二选一。**模式 A** —— 用你自己的钱包付：在 `deposit.chain` 上，把恰好
+`deposit.amount` 数量的 `deposit.tokenSymbol` 发送到 `deposit.receiverAddress`，
+如果有 `deposit.receiverMemo` 就带上它。地址直接从 JSON 里复制；绝不要手打重输。
+
+**模式 B** —— 让脚本从热钱包付款（仅限 EVM 与 Solana）：
+
+```bash
+# 预览将要签名的确切内容 —— 不会签任何名
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --dry-run
+
+# 真正发送。--send 是必需的。
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Ethereum、BNB Chain、Polygon 和 Base 用 `send-evm.js` 配合 `ROZO_CHECKOUT_EVM_KEY`。
+额度上限：单笔 $100，单会话 $200。
+
+```json
+{
+  "success": true,
+  "submitted": true,
+  "confirmed": true,
+  "txHash": "3Bxs4h24hBjHziQ8UJqSjqjbjWQq2sQ3yV9Fq4HrVh5c"
+}
+```
+
+## 5. 观察结清
+
+```bash
+node scripts/dist/status.js --rozo-payment-id <rozoPaymentId> --watch --timeout 600
+```
+
+```json
+{
+  "success": true,
+  "state": "settled",
+  "terminal": true,
+  "payin": { "txHash": "3Bxs4h24...", "confirmedAt": "2026-08-08T10:05:00.000Z" }
+}
+```
+
+状态流转依次为 `awaiting_deposit` → `payin_detected` → `payin_confirmed` →
+`bridging` → `paying_coinbase` → `settled`。你的链上交易被确认**并不**代表结束：
+要一直轮询到 `settled` 为止。
+
+## 出问题时
+
+读 `error.code`。最可能遇到的三个：
+
+| `error.code` | 发生了什么 | 该怎么办 |
+|---|---|---|
+| `LINK_NO_LONGER_PAYABLE` | 这个链接已经被别人付过，或者已过期 | 找商家要一个新链接；不要付任何钱 |
+| `EXPIRY_MARGIN` | 剩余时间太短，不足以安全完成充值、跨桥和结清 | 让订单过期，然后从第 1 步重新开始 |
+| `ALREADY_SENT` | 这个订单已经记录过一次发送 | **不要**再发一次；先跑 `status.js` 并去链上核对 |
+
+**只要已经有钱离开了你的钱包，就绝不要再付一次。** 保留好 `linkId`、
+`rozoPaymentId` 和每一个交易 hash，找人来做对账。向一个一次性充值地址付第二笔款，
+并不保证会被入账。
+
+完整的错误码表在 [README.md](README.md)，面向 agent 的指令在 [SKILL.md](SKILL.md)。

package/README.es.md

@@ -0,0 +1,287 @@
+# rozo-checkout
+
+[English](README.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | **Español**
+
+**[Inicio rápido →](QUICKSTART.es.md)** — pagar un enlace en cinco minutos, sin leer todo esto.
+
+```bash
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+Pagar un **enlace de pago de Coinbase (Coinbase Payment Link) de OpenRouter** con
+una moneda que ese enlace no puede aceptar directamente: BTC por Lightning, o
+USDT/USDC en Solana, BNB Chain, Ethereum, Polygon, Base o Stellar.
+
+Un enlace de pago de Coinbase solo acepta USDC en Base. Este repositorio es una
+habilidad de agente (agent skill) —más los scripts de Node que la respaldan— que
+enruta cualquiera de las monedas anteriores a través de un puente (bridge): se
+obtiene una dirección de depósito (deposit address) de un solo uso para la moneda
+que realmente se posee y, una vez que el depósito llega, una billetera fondeadora
+(funder wallet) liquida la factura de Coinbase en nombre del usuario.
+
+En la factura en sí **no hay descuento**: `callerPays` es igual al importe de la
+factura. El **depósito** que se envía es una cifra distinta y normalmente es
+mayor: incluye las comisiones del puente y de la cadena de origen necesarias para
+entregar el importe de la factura en USDC sobre Base. Enviar siempre exactamente
+el `deposit.amount` que devuelve el backend; nunca suponer que es igual a la
+factura.
+
+- `SKILL.md` — las instrucciones dirigidas al agente (formato de skill de Claude Code).
+- `llms.txt` — un resumen compacto para agentes que leen un solo archivo.
+- `scripts/` — la implementación en Node; `src/` es el código fuente y `dist/`
+  contiene paquetes autocontenidos que se pueden ejecutar con `node` a secas.
+- `test/` — pruebas unitarias offline de la lógica de manejo de dinero y de seguridad.
+- `PLAN.md` — el documento de diseño que sigue la implementación.
+
+**No** hace falta una cuenta, una clave de API ni ninguna relación con el
+operador para usar esto. Todos los endpoints que invoca son públicos y sin clave.
+
+## Cómo funciona
+
+```mermaid
+flowchart TD
+    A["Coinbase Payment Link<br/>payments.coinbase.com/payment-links/pl_*"] --> B
+    B["quote-invoice<br/>(public POST)"] --> C["create-invoice<br/>(public POST)"]
+    C --> D["Bridge order<br/>one-time deposit address<br/>+ exact amount + expiry"]
+    D --> E["You send USDT/USDC/BTC<br/>on your chosen chain"]
+    E --> F["Bridge converts the pay-in"]
+    F --> G["Funder wallet settles<br/>the Coinbase invoice"]
+    G --> H["Merchant is paid<br/>(e.g. OpenRouter credit)"]
+```
+
+Lo mismo en ASCII, para terminales sin mermaid:
+
+```
+  Coinbase Payment Link (pl_* / paymentSession_*)
+            |
+            v
+  [ quote-invoice ]  ->  merchant, amount, expiry, short-lived quote receipt
+            |
+            v
+  [ create-invoice ] ->  bridge order:  rozoPaymentId + deposit address
+            |                            + exact amount + order expiry
+            v
+  you send USDT / USDC / BTC on your chain  ------> deposit address
+            |
+            v
+  bridge converts the pay-in  ------>  funder wallet pays the Coinbase invoice
+            |
+            v
+  merchant credited; poll until the state is `settled`
+```
+
+Aparecen tres identificadores a lo largo del documento y nunca son intercambiables:
+
+| Identificador | Qué es |
+|---|---|
+| `linkId` | el id de Coinbase: `pl_*` (enlace de pago) o `paymentSession_*` (sesión v3) |
+| `rozoPaymentId` | el UUID de la orden del puente: se usa para el detalle del depósito y el estado |
+| `paymentLink` | una URL de página de pago alojada para la orden del puente (alternativa para humanos) |
+
+## Orígenes admitidos
+
+| Cadena | Id de cadena | Tokens | Notas |
+|---|---|---|---|
+| Ethereum | `1` | USDC, USDT | 6 decimales |
+| BNB Chain | `56` | USDC, USDT | **18 decimales**: la causa habitual de errores por un factor de 10^12 |
+| Polygon | `137` | USDC, USDT | 6 decimales |
+| Base | `8453` | USDC | 6 decimales |
+| Solana | `900` | USDC, USDT | 6 decimales; SPL, puede requerir un memo. SOL nativo **no** está admitido |
+| Stellar | `1500` | USDC | 7 decimales; requiere el memo |
+| Bitcoin Lightning | `lightning` | BTC | los importes son **satoshis** enteros, pagados mediante una factura BOLT11 (BOLT11) |
+
+Las monedas de gas nativas (SOL, BNB, ETH, MATIC) y el BTC on-chain no se aceptan.
+
+## Inicio rápido
+
+### 1. Probar los endpoints públicos con curl
+
+Reemplazar `pl_01YOURLINKID` por un enlace de pago de Coinbase real. No se
+necesita ninguna cabecera de autenticación en nada de lo que sigue.
+
+```bash
+MPP="https://apiserver.mpprouter.dev/v1/services/rozo-agent-api"
+INTENTS="https://intentapiv4.rozo.ai/functions/v1/payment-api"
+LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
+
+# Cotizarlo: comercio, importe, expiración y un quoteReceipt de ~60 segundos.
+curl -s -X POST "$MPP/quote-invoice" \
+  -H 'content-type: application/json' \
+  -d "{\"url\":\"$LINK\"}"
+
+# Crear una orden de puente para, por ejemplo, USDT en Solana.
+# Esto crea una orden pero no mueve dinero; una orden sin fondear simplemente expira.
+curl -s -X POST "$MPP/create-invoice" \
+  -H 'content-type: application/json' \
+  -d "{\"url\":\"$LINK\",\"source\":{\"chainId\":\"900\",\"tokenSymbol\":\"USDT\"}}"
+
+# Instrucciones de depósito (autoritativas), usando el rozoPaymentId de arriba.
+curl -s "$INTENTS/payments/<rozoPaymentId>"
+
+# Estado del cumplimiento, usando el linkId de Coinbase.
+curl -s "$MPP/invoice-status?payment_id=pl_01YOURLINKID"
+```
+
+`create-invoice` tiene límite de tasa por IP (unas 30/hora); los endpoints de
+lectura no.
+
+### 2. Usar la CLI
+
+No hay nada que instalar: `npx` la descarga y la ejecuta:
+
+```bash
+npx @rozoai/checkout quote <coinbase-link>
+npx @rozoai/checkout pay   <coinbase-link> --with usdt-solana
+npx @rozoai/checkout status <rozoPaymentId>
+```
+
+`pay` recorre todo el flujo: cotizar, crear la orden, mostrar una revisión
+enmascarada, pedir un sí, y luego imprimir las instrucciones de depósito y
+consultar hasta la liquidación. Añadir `--send` para pagar desde una billetera
+caliente en lugar de la propia, `--json` para salida de máquina y `--help` para
+todo lo demás.
+
+### 3. O ejecutar los scripts directamente
+
+Clonar el repositorio da los mismos flujos como scripts individuales: es lo que
+usa la habilidad de agente, y lo que la CLI invoca por debajo.
+
+Cada script imprime exactamente un objeto JSON en stdout. Código de salida `0`
+éxito, `1` rechazado/fallido (leer `error.code`), `2` uso incorrecto, `3` enviado
+pero sin confirmar.
+
+```bash
+# Paso 1 — cotización de solo lectura, no cuesta nada
+node scripts/dist/quote.js --url "$LINK"
+
+# Paso 2 — crear la orden (no se mueve dinero; las órdenes sin fondear expiran).
+#          La dirección de depósito completa se RETIENE en esta etapa: se obtiene
+#          el resumen enmascarado para revisar, y `depositWithheld: true`.
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+
+# Paso 3 — revisar el importe, la cadena, la dirección enmascarada, el requisito
+#          de memo y la expiración. Solo cuando se haya decidido pagar, volver a
+#          ejecutar el mismo comando con --confirm. Esto libera el bloque de
+#          depósito completo y registra la confirmación que exigen los scripts de envío.
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+
+# Paso 4a — Modo A: pagar el bloque de depósito desde la propia billetera,
+#           y luego observar la liquidación
+node scripts/dist/status.js --rozo-payment-id <uuid> --watch --timeout 600
+
+# Paso 4b — Modo B: dejar que el script pague desde una billetera caliente.
+#           --dry-run no firma nada; un envío real requiere además --send.
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <uuid> --dry-run
+```
+
+Los `scripts/dist/*.js` son paquetes autocontenidos: no hace falta `npm install`
+en el lugar de la llamada. La CLI anterior es el mismo código con una superficie
+más amable: importa estos flujos en lugar de reimplementarlos, así que todas las
+comprobaciones de abajo aplican igual sea cual sea el punto de entrada que se
+use.
+
+## Compilación y pruebas
+
+```bash
+npm install     # solo hace falta para recompilar o para ejecutar las pruebas
+npm run build   # esbuild -> scripts/dist/*.js (objetivo node18) + blacklist.json
+npm test        # node:test, totalmente offline
+npm run check   # build + test
+```
+
+Las pruebas **no hacen llamadas de red**; cada respuesta del backend es un
+fixture en `test/fixtures/`. Cubren la conversión a importes atómicos (6/18
+decimales y satoshis de Lightning), la aritmética del margen de expiración, la
+normalización de direcciones comprometidas y el comportamiento de fallo cerrado
+(fail-closed), la decisión de reutilización de órdenes, el comparador de
+verificación posterior a la creación y las reglas de completitud del depósito.
+
+Dos grupos lanzan procesos hijos reales en lugar de llamar a funciones, porque
+prueban cosas que una prueba de un solo proceso no puede: la suite de
+concurrencia hace competir a varios procesos por reclamar una misma orden
+(exactamente uno puede ganar) y por agotar el tope de la sesión, y la suite de
+puntos de entrada ejecuta los scripts de envío compilados para demostrar que
+rechazan sin `--send`, sin una confirmación y después de una reclamación previa.
+
+## Diseño de seguridad
+
+Lo más interesante de este repositorio es aquello que se niega a hacer.
+
+- **Confirmación en dos fases, obligatoria.** `create-order.js` retiene la
+  dirección de depósito completa, el memo y la factura BOLT11 hasta que se
+  vuelve a ejecutar con `--confirm`, lo cual registra una confirmación ligada a
+  un sha256 de esas instrucciones exactas. Los scripts de envío rechazan la
+  operación si no están presentes tanto `--send` como una confirmación cuyo
+  digest siga coincidiendo con los datos en vivo, de modo que ni una invocación
+  accidental ni una dirección de depósito sustituida pueden mover fondos.
+- **Factura completa, siempre.** `callerPays` debe ser igual al importe de la
+  factura y `discount` debe ser `"0"`; cualquier otra cosa aborta con
+  `NO_DISCOUNT_VIOLATION`. Los campos críticos para la seguridad (`linkId`,
+  `merchant`, `original`, `callerPays`, el origen reflejado) deben estar
+  presentes además de ser iguales: un campo ausente es una desviación (drift).
+- **Protección contra reutilización.** Crear una orden para un enlace que ya
+  tiene una orden no expirada devuelve esa orden existente, incluso si ya ha
+  sido fondeada. Por eso, en cada ejecución se exige que la orden en vivo esté
+  sin pagar (`payment_unpaid`, sin hash de transacción, sin importe recibido,
+  sin confirmación) y que coincida con la cadena y el token elegidos por quien
+  llama. En caso contrario: `ORDER_ALREADY_FUNDED` o `REUSED_SOURCE_MISMATCH`.
+- **Regla de dinero detectado, con fallo cerrado.** Una vez que existe cualquier
+  ingreso, la herramienta nunca informa de un simple fallo, nunca aconseja pagar
+  de nuevo y nunca reintenta con una orden nueva. Un `amountReceived` que no es
+  nulo pero resulta ilegible cuenta como dinero, no como ausencia de dinero. Un
+  backend ilegible se reporta como `unknown`, nunca como `awaiting_deposit`.
+- **Instrucciones de depósito completas.** Un importe cero, negativo o no
+  interpretable aborta la operación. Lightning requiere la BOLT11 (que llega en
+  `source.lnInvoice` con una dirección vacía). Stellar requiere su memo: un memo
+  ausente es un aborto duro, nunca se representa como "no se requiere memo".
+- **Márgenes de expiración.** El pago se rechaza salvo que la más temprana entre
+  la expiración de la orden y la de Coinbase esté a más de un margen por cadena
+  (10 min en EVM y Stellar, 5 min en Solana). Lightning exige además al menos 10
+  minutos de validez de la BOLT11. Una fecha límite ausente o no interpretable
+  aborta la operación.
+- **Revalidación de la pagabilidad.** Un recibo de cotización hace que la
+  creación de la orden omita la comprobación en vivo contra Coinbase, y el
+  enlace puede ser consumido por otra persona en cualquier momento; por eso la
+  pagabilidad se vuelve a comprobar inmediatamente antes de mostrar la dirección
+  de depósito, y otra vez como último paso antes de la difusión (broadcast),
+  después de toda la preparación de RPC. Un estado incompleto de Coinbase se
+  trata como "no se puede demostrar que sea pagable", no como pagable.
+- **Lista de direcciones comprometidas, con fallo cerrado.**
+  `scripts/src/lib/blacklist.json` incluye una lista incorporada con una
+  cabecera de procedencia y un sha256 sobre las direcciones. El digest solo
+  demuestra que esta copia incorporada no ha sido editada desde su fecha de
+  sincronización; no es una firma de la fuente original. Se comprueban tanto la
+  dirección de depósito como la billetera emisora. Si el archivo falta, está mal
+  formado, está vacío o su digest no coincide, se rechaza todo envío en lugar de
+  continuar sin comprobación.
+- **Envío único, entre procesos.** El estado de la orden vive en
+  `$HOME/.rozo-checkout/state/<uuid>.json`, escrito de forma atómica (archivo
+  temporal, fsync, renombrado). Cada ciclo de lectura-modificación-escritura de
+  un archivo de estado —la reclamación, los topes de gasto, el registro de la
+  orden y la confirmación— se ejecuta dentro de un único archivo de bloqueo
+  exclusivo, de modo que dos invocaciones concurrentes no pueden ni decidir
+  ambas que son la primera ni sobrescribir el registro de envío de la otra. Un
+  envío se reclama *antes* de difundirse, así que un error ambiguo de RPC nunca
+  puede convertirse en una segunda transferencia. Las transacciones se firman
+  antes de la difusión para que el hash se conozca de antemano; ante un
+  resultado ambiguo, los scripts consultan esa transacción exacta en lugar de
+  volver a difundirla.
+- **Controles de la billetera caliente.** Las claves provienen únicamente del
+  entorno (`ROZO_CHECKOUT_EVM_KEY`, `ROZO_CHECKOUT_SOL_KEY`), nunca se imprimen
+  y nunca se aceptan por línea de comandos; los errores de bibliotecas y de RPC
+  se redactan antes de mostrarse, incluidas las URL de proveedor que llevan
+  credenciales, los tokens bearer y las cadenas con forma de clave. Los scripts
+  se niegan a ejecutarse cuando cualquier `.env`/`.env.*` del directorio de
+  trabajo está bajo seguimiento de git, y se niegan con igual firmeza cuando git
+  no puede demostrar que no lo está. El id de cadena del RPC (o el hash génesis
+  de Solana) y los decimales on-chain del token se verifican antes de firmar.
+  Topes: $100 por transacción, $200 acumulados por sesión.
+- **Enmascaramiento de direcciones.** El texto muestra `first6...last4`. La
+  dirección de depósito completa, el memo y la cadena BOLT11 aparecen solo
+  dentro del objeto `deposit` legible por máquina, de modo que siguen siendo
+  copiables sin quedar dispersos por los registros.
+
+## Licencia
+
+MIT.