@boelabs/billete-sdk 0.3.2 → 0.3.3

package/README.md

@@ -1,28 +1,130 @@
-# @boelabs/billete-sdk
+<div align="center">
 
-SDK oficial de [Billete](https://billete.run): pagos y suscripciones para Venezuela con Pago Móvil,
-precios en bolívares o en divisas a tasa BCV y cuotas por plan. Tipado de punta a punta, sin
-dependencias y compatible con Node, Bun, Deno y runtimes edge.
+# Billete SDK
+
+**SDK oficial de TypeScript para la API de [Billete](https://billete.run).**
+
+Cobros con Pago Móvil, precios en bolívares o en divisas a tasa BCV y suscripciones, desde tu
+servidor y tu frontend.
+
+[![npm](https://img.shields.io/npm/v/@boelabs/billete-sdk?color=000&label=npm)](https://www.npmjs.com/package/@boelabs/billete-sdk)
+[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-000)](./LICENSE)
+![Tipos incluidos](https://img.shields.io/npm/types/@boelabs/billete-sdk?color=000)
+![Sin dependencias](https://img.shields.io/badge/dependencias-0-000)
+
+</div>
+
+---
+
+- **Tipado de punta a punta:** cada recurso, entrada y evento tiene su tipo.
+- **Sin dependencias:** solo `fetch` y Web Crypto; funciona en Node.js 20+, Bun, Deno y
+  runtimes edge (Cloudflare Workers, Vercel).
+- **Seguro ante reintentos:** cada mutación lleva una clave de idempotencia, así un reintento
+  nunca cobra dos veces.
+
+## Contenido
+
+- [Instalación](#instalación)
+- [Inicio rápido](#inicio-rápido)
+- [Configuración](#configuración)
+- [Recursos](#recursos)
+- [Montos](#montos)
+- [Paginación](#paginación)
+- [Errores](#errores)
+- [Idempotencia y reintentos](#idempotencia-y-reintentos)
+- [Navegador](#navegador)
+- [Webhooks](#webhooks)
+- [Licencia](#licencia)
+
+## Instalación
 
 ```bash
 npm install @boelabs/billete-sdk
 ```
 
-## Servidor
+El paquete tiene tres puntos de entrada:
+
+| Import | Dónde se usa | Para qué |
+| --- | --- | --- |
+| `@boelabs/billete-sdk` | Servidor | Toda la API, con tu clave secreta |
+| `@boelabs/billete-sdk/client` | Navegador | Checkout y estado de un cliente, sin clave secreta |
+| `@boelabs/billete-sdk/webhooks` | Servidor | Verificar la firma de los webhooks |
+
+## Inicio rápido
+
+Crea una clave secreta en el dashboard (**Desarrolladores → Claves API**) y guárdala en
+`BILLETE_API_KEY`.
 
 ```ts
 import { createBillete } from "@boelabs/billete-sdk";
 
+const billete = createBillete({ environment: "test" });
+
+const checkout = await billete.checkouts.create({
+  plan: "plan_…",
+  months: 1,
+  customer: { email: "ana@example.com", externalId: "user_123" },
+});
+
+// Redirige a tu cliente a checkout.url para que pague.
+```
+
+Cuando el pago se confirma, Billete te avisa con el webhook `checkout.completed` (ver
+[Webhooks](#webhooks)).
+
+## Configuración
+
+```ts
 const billete = createBillete({
-  environment: "test", // obligatorio: "test" o "production"
-  // apiKey: por defecto lee BILLETE_API_KEY
-  // baseUrl: por defecto lee BILLETE_BASE_URL, o usa https://api.billete.run
+  environment: "production",
+  apiKey: process.env.BILLETE_API_KEY,
+  timeoutMs: 30_000,
+  maxRetries: 2,
 });
 ```
 
-`environment` debe coincidir con la clave (`sk_test_…` o `sk_prod_…`): si no coinciden, el cliente
-falla al crearse, así una clave nunca opera en el entorno equivocado. Las claves se crean en el
-dashboard, en **Desarrolladores → Claves API**. Nunca uses una clave en el navegador.
+| Opción | Por defecto | Descripción |
+| --- | --- | --- |
+| `environment` | — (obligatoria) | `"test"` o `"production"`. Debe coincidir con la clave. |
+| `apiKey` | `BILLETE_API_KEY` | Clave secreta: `sk_test_…` o `sk_prod_…`. |
+| `baseUrl` | `BILLETE_BASE_URL`, o `https://api.billete.run` | URL de la API. |
+| `timeoutMs` | `30000` | Tiempo máximo por intento. |
+| `maxRetries` | `2` | Reintentos ante errores de red, `429` y `5xx`. |
+| `fetch` | `globalThis.fetch` | Implementación de `fetch` propia (proxies, tests). |
+
+Si `environment` no coincide con el prefijo de la clave, `createBillete` lanza un error: una
+clave de prueba nunca opera en producción ni al revés. Por la misma razón, el cliente de servidor
+se niega a crearse en un navegador.
+
+> [!WARNING]
+> La clave secreta da acceso completo a tu negocio. Úsala solo en el servidor y nunca la
+> incluyas en código que llegue al navegador.
+
+## Recursos
+
+Todos los métodos devuelven promesas con el recurso tipado. Los recursos con listado tienen
+`create`, `retrieve`, `update`, `list` e `iterate`, además de sus acciones propias:
+
+| Recurso | Acciones propias |
+| --- | --- |
+| `customers` | — |
+| `customerSessions` | `create` |
+| `products` | `retire`, `retireVariant` |
+| `plans` | — |
+| `features` | `check`, `isEnabled`, `listForCustomer`, `consume`, `release`, `set` |
+| `coupons` | — |
+| `checkouts` | `expire` |
+| `paymentLinks` | `retire` |
+| `subscriptions` | `cancel`, `resume` |
+| `payments` | `refund`, `listRefunds` |
+| `payouts` | — |
+| `balance` | `retrieve` |
+| `webhookEndpoints` | `delete` |
+| `events` | `retrieve`, `list`, `iterate` |
+| `exchangeRates` | `list` |
+| `currencies` | `list` |
+
+### Ejemplo: plan con cuotas
 
 ```ts
 await billete.features.create({
@@ -43,48 +145,125 @@ const plan = await billete.plans.create({
   features: { tokens: 100_000 },
 });
 
-const checkout = await billete.checkouts.create({
-  plan: plan.id,
-  months: 1,
-  customer: { email: "ana@example.com", externalId: "user_123" },
-});
-// Redirige al cliente a checkout.url
-
+// `customer` acepta el ID de Billete (cus_…) o tu propio externalId.
 const { allowed } = await billete.features.consume("user_123", "tokens", 850);
 ```
 
-Los montos son siempre enteros en unidad menor (céntimos): `1_000` son 10,00 USD. Las mutaciones
-llevan una `Idempotency-Key` automática, así los reintentos ante fallos de red nunca duplican un
-cobro. Los errores de la API llegan como `BilleteError`, con `code` estable y `status`.
+`consume` es atómico: si el consumo supera el límite, no se descuenta nada y `allowed` es
+`false`.
+
+## Montos
+
+Los montos son siempre **enteros en unidad menor** (céntimos), nunca decimales: `1_000` en `USD`
+son 10,00 USD y `1_000` en `VES` son 10,00 Bs. Las tasas de cambio llegan como texto decimal para
+no perder precisión.
+
+## Paginación
+
+`list` devuelve una página (`{ data, nextCursor }`); `iterate` recorre todas por ti:
+
+```ts
+const page = await billete.payments.list({ limit: 50 });
+const next = await billete.payments.list({ limit: 50, cursor: page.nextCursor ?? undefined });
+
+for await (const payment of billete.payments.iterate()) {
+  console.log(payment.id, payment.amount);
+}
+```
+
+## Errores
+
+Toda respuesta fallida lanza un `BilleteError`:
+
+```ts
+import { BilleteError } from "@boelabs/billete-sdk";
+
+try {
+  await billete.payments.refund("pay_…");
+} catch (error) {
+  if (error instanceof BilleteError && error.code === "payment_not_refundable") {
+    // …
+  }
+  throw error;
+}
+```
+
+| Propiedad | Descripción |
+| --- | --- |
+| `type` | Categoría: `invalid_request`, `authentication`, `permission`, `not_found`, `conflict`, `validation`, `rate_limit`, `provider`, `internal` o `network`. |
+| `code` | Código estable, apto para decidir en tu código. |
+| `message` | Descripción legible del error. |
+| `status` | Código HTTP (`0` si no hubo respuesta). |
+| `param` | Campo que causó el error, cuando aplica. |
+| `requestId` | Identificador de la petición; inclúyelo al pedir soporte. |
+
+## Idempotencia y reintentos
+
+Cada mutación envía una `Idempotency-Key` generada automáticamente, que se mantiene entre
+reintentos. Si quieres que un reintento tuyo (por ejemplo, de un job) también sea seguro, pasa
+una clave estable:
+
+```ts
+await billete.payments.refund("pay_…", {}, { idempotencyKey: `refund-${orderId}` });
+```
+
+Todos los métodos aceptan como último argumento `{ idempotencyKey?, signal? }`; `signal` permite
+cancelar la petición con un `AbortController`.
 
 ## Navegador
 
-Sin clave: tu servidor crea una sesión de cliente de corta duración
-(`billete.customerSessions.create`) y el navegador la usa para leer el estado de ese cliente.
+El cliente de navegador nunca usa tu clave secreta. Tu servidor crea una **sesión de cliente**
+de corta duración y se la entrega al frontend:
 
 ```ts
+// Servidor
+const session = await billete.customerSessions.create({ customer: "user_123" });
+return { token: session.token };
+```
+
+```ts
+// Navegador
 import { createClient } from "@boelabs/billete-sdk/client";
 
-const billete = createClient({ customerSession: tokenFromYourServer });
-const [subscription] = (await billete.customer.subscriptions()).data;
-// subscription.renewal → { status: "due" | "overdue", daysRemaining, checkoutUrl, … }
+const billete = createClient({ customerSession: token });
+
+const { data: subscriptions } = await billete.customer.subscriptions();
+const tokens = await billete.customer.feature("tokens");
 ```
 
+`customerSession` también acepta una función, útil cuando el token se renueva. Sin sesión, el
+cliente puede leer y pagar checkouts y links de pago, y consultar tasas y monedas.
+
 ## Webhooks
 
-Firma [Standard Webhooks](https://www.standardwebhooks.com). Pasa el cuerpo tal como llegó:
+Billete firma los webhooks con [Standard Webhooks](https://www.standardwebhooks.com). Verifica la
+firma con el cuerpo **exactamente como llegó**, antes de parsearlo:
 
 ```ts
-import { verifyWebhook } from "@boelabs/billete-sdk/webhooks";
+import { verifyWebhook, WebhookVerificationError } from "@boelabs/billete-sdk/webhooks";
 
-const event = await verifyWebhook({
-  payload: rawBody,
-  headers: request.headers,
-  secret: process.env.BILLETE_WEBHOOK_SECRET!,
-});
-if (event.type === "subscription.past_due") notify(event.data.customerId);
+export async function POST(request: Request) {
+  try {
+    const event = await verifyWebhook({
+      payload: await request.text(),
+      headers: request.headers,
+      secret: process.env.BILLETE_WEBHOOK_SECRET!,
+    });
+
+    if (event.type === "checkout.completed") {
+      // event.data es un Checkout
+    }
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
+    throw error;
+  }
+}
 ```
 
+`event` es una unión discriminada por `type`, así que `event.data` tiene el tipo correcto en cada
+rama. Se rechazan las firmas con más de 5 minutos (`toleranceSeconds`).
+
 ## Licencia
 
-MIT. El SDK es el único código público de Billete; el resto del proyecto es propietario.
+[MIT](./LICENSE)

package/dist/client.js

@@ -1,4 +1,4 @@
-import { n as segment, r as BilleteError, t as createTransport } from "./http-kkjWt1D4.js";
+import { n as segment, r as BilleteError, t as createTransport } from "./http-CTnngMSn.js";
 //#region src/create-client.ts
 /**
 * Browser client. It never holds a secret key: checkouts are addressed by their unguessable ID

package/dist/{http-kkjWt1D4.js → http-CTnngMSn.js}

@@ -18,7 +18,7 @@ var BilleteError = class extends Error {
 };
 //#endregion
 //#region src/http.ts
-const SDK_VERSION = "0.3.2";
+const SDK_VERSION = "0.3.3";
 const DEFAULT_BASE_URL = "https://api.billete.run";
 const RETRYABLE_STATUS = /* @__PURE__ */ new Set([
 	429,

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as segment, r as BilleteError, t as createTransport } from "./http-kkjWt1D4.js";
+import { n as segment, r as BilleteError, t as createTransport } from "./http-CTnngMSn.js";
 import { WebhookVerificationError, verifyWebhook } from "./webhooks.js";
 //#region ../contracts/src/environment.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boelabs/billete-sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Billete SDK: server client, browser client and webhook verification",
   "keywords": [
     "billete",