@rozoai/checkout 0.1.0 → 0.1.2

package/QUICKSTART.zh.md

@@ -1,178 +0,0 @@
-# 快速开始
-
-[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

@@ -1,287 +0,0 @@
-# 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.