@bepago/sdk 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bePago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# bePago — SDK para Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK oficial de [bePago](https://bepago.com) para Node.js 18+. Sin dependencias.
+
+Cobros, pagos masivos (payouts) y verificación de webhooks con firma HMAC v2.
+
+## Instalación
+
+```bash
+npm install bepago
+```
+
+## Uso
+
+```js
+import BePago from 'bepago';
+
+const bp = BePago('sk_live_tu_secreto');
+```
+
+La clave (`sk_…`) la obtenés en tu panel de bePago. El key ID público (`pk_…`)
+se deriva solo; si necesitás pasarlo aparte: `BePago(secret, { keyId: 'pk_…' })`.
+
+### Crear un cobro
+
+```js
+const cobro = await bp.charges.create({
+  reference: 'pedido-001',
+  currency: 'PYG',
+  amount: 150000,
+  description: 'Pedido #001',
+});
+
+console.log(cobro.checkout_url); // link de pago para el cliente
+```
+
+Consultar, reembolsar y ver saldo:
+
+```js
+await bp.charges.get('pedido-001');
+await bp.charges.refund('pedido-001', 'cliente canceló');
+await bp.charges.balance();
+```
+
+### Pago masivo (payout)
+
+```js
+const payout = await bp.payouts.create(
+  {
+    currency: 'PYG',
+    amount: 500000,
+    destination: { alias: 'juan.perez', holder_name: 'Juan Pérez' },
+  },
+  'idem-key-unica', // clave de idempotencia (opcional pero recomendada)
+);
+
+await bp.payouts.get(payout.id);
+await bp.payouts.cancel(payout.id);
+await bp.payouts.balance();
+```
+
+### Verificar un webhook
+
+bePago firma cada webhook con `HMAC-SHA256` sobre `timestamp + body` usando el
+secreto del webhook. `verify` chequea la firma **y la frescura del timestamp**
+(rechaza entregas fuera de ±5 minutos por defecto, configurable) y devuelve el
+evento ya parseado, con su `id`:
+
+```js
+import BePago from 'bepago';
+
+const bp = BePago('sk_live_…');
+
+// En tu handler HTTP (body como string crudo, sin re-serializar):
+let evt;
+try {
+  evt = bp.webhooks.verify('whsec_tu_secreto_de_webhook', {
+    id: req.headers['x-bepago-event-id'],
+    timestamp: req.headers['x-webhook-timestamp'],
+    signature: req.headers['x-webhook-signature'],
+    body: req.rawBody, // el cuerpo tal cual llegó, sin re-serializar
+  });
+} catch (e) {
+  return res.status(400).send('webhook inválido'); // firma o timestamp fuera de ventana
+}
+
+// Anti-replay: cada evento trae un id ESTABLE entre reintentos. Guardá los ids
+// ya procesados y descartá los duplicados (los reintentos reenvían el mismo id
+// con un timestamp nuevo).
+if (await yaProcesado(evt.id)) return res.status(200).end();
+await marcarProcesado(evt.id);
+
+// procesar evt.event / evt.data …
+res.status(200).end();
+```
+
+Tolerancia configurable (ej. ±10 minutos):
+
+```js
+bp.webhooks.verify(secret, { id, timestamp, signature, body }, { toleranceSeconds: 600 });
+```
+
+## Documentación
+
+Referencia completa de la API, tipos de eventos y ejemplos:
+**https://bepago.com/docs**
+
+## Licencia
+
+MIT

package/index.mjs

@@ -0,0 +1,107 @@
+/**
+ * bePago SDK — Node.js (18+, zero dependencies).
+ *
+ * Usage:
+ *   import BePago from 'bepago';
+ *   const bp = BePago('sk_test_…');
+ *   const charge = await bp.charges.create({ reference: 'order-1', currency: 'PYG', amount: 150000, description: 'Test' });
+ */
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Firma canónica v2 de un request (misma que valida la API).
+ * `body` es el cuerpo YA serializado (string); cadena vacía si no hay body.
+ */
+export function computeSignatureV2({ secret, timestamp, nonce, method, path, idempotencyKey = '', body = '' }) {
+  const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');
+  const canonical = ['v2', timestamp, nonce, method.toUpperCase(), path, idempotencyKey ?? '', bodyHash].join('\n');
+  return createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');
+}
+
+export default function BePago(secret, opts = {}) {
+  const base = opts.baseUrl ?? 'https://bepago.com/api';
+  // The key ID is the part before the first underscore pair: pk_test_xxx or sk_test_xxx
+  // But for the API, X-Api-Key is the full key ID (pk_test_…), and the secret is sk_test_…
+  // Convention: the user passes the secret (sk_), and the key ID (pk_) is derived or passed separately.
+  const keyId = opts.keyId ?? secret.replace(/^sk_/, 'pk_');
+
+  function sign(method, path, body, idempotencyKey) {
+    const timestamp = String(Date.now());
+    const nonce = randomUUID().replaceAll('-', '');
+    const bodyStr = body != null ? JSON.stringify(body) : '';
+    const signature = computeSignatureV2({ secret, timestamp, nonce, method, path, idempotencyKey, body: bodyStr });
+    return { timestamp, nonce, signature, bodyStr };
+  }
+
+  async function request(method, path, body, extra = {}) {
+    const { timestamp, nonce, signature, bodyStr } = sign(method, path, body, extra.idempotencyKey);
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-Api-Key': keyId,
+      'X-Timestamp': timestamp,
+      'X-Nonce': nonce,
+      'X-Signature-Version': '2',
+      'X-Signature': signature,
+    };
+    if (extra.idempotencyKey) headers['X-Idempotency-Key'] = extra.idempotencyKey;
+    const res = await fetch(base + path, { method, headers, body: bodyStr || undefined });
+    const data = await res.json();
+    if (!res.ok) {
+      const err = new Error(data?.error?.message ?? `HTTP ${res.status}`);
+      err.code = data?.error?.code;
+      err.status = res.status;
+      err.response = data;
+      throw err;
+    }
+    return data;
+  }
+
+  return {
+    charges: {
+      create: (params) => request('POST', '/v1/charges', params),
+      get: (ref) => request('GET', `/v1/charges/${encodeURIComponent(ref)}`),
+      refund: (ref, reason) => request('POST', `/v1/charges/${encodeURIComponent(ref)}/refund`, { reason }),
+      balance: () => request('GET', '/v1/charges/balance'),
+    },
+    payouts: {
+      create: (params, idempotencyKey) => request('POST', '/v1/payouts', params, { idempotencyKey }),
+      get: (id) => request('GET', `/v1/payouts/${encodeURIComponent(id)}`),
+      cancel: (id) => request('POST', `/v1/payouts/${encodeURIComponent(id)}/cancel`),
+      balance: () => request('GET', '/v1/balance'),
+    },
+    webhooks: {
+      /**
+       * Verifica un webhook de bePago y devuelve el evento parseado.
+       *
+       * Chequea la firma HMAC y la FRESCURA del timestamp: por defecto rechaza
+       * entregas fuera de ±5 minutos (configurable con `toleranceSeconds`). Lanza
+       * si la firma no valida o el timestamp está fuera de la ventana.
+       *
+       * Expone `id` (header X-BePago-Event-Id, estable entre reintentos): guardá
+       * los ids ya procesados para descartar duplicados de forma idempotente.
+       *
+       *   const evt = bp.webhooks.verify(secret, {
+       *     id: req.headers['x-bepago-event-id'],
+       *     timestamp: req.headers['x-webhook-timestamp'],
+       *     signature: req.headers['x-webhook-signature'],
+       *     body: rawBody, // el cuerpo EXACTO recibido, sin reserializar
+       *   });
+       *   if (seen.has(evt.id)) return; // duplicado
+       *   seen.add(evt.id);
+       *
+       * @returns {{ id: string, event: string, livemode: boolean, data: object }}
+       */
+      verify(webhookSecret, { id, timestamp, body, signature }, opts = {}) {
+        const toleranceMs = (opts.toleranceSeconds ?? 300) * 1000;
+        const expected = createHmac('sha256', webhookSecret).update(String(timestamp) + body, 'utf8').digest('hex');
+        const a = Buffer.from(expected, 'hex');
+        const b = Buffer.from(String(signature ?? ''), 'hex');
+        if (a.length !== b.length || !timingSafeEqual(a, b)) throw new Error('bePago webhook: firma inválida');
+        const age = Math.abs(Date.now() - Number(timestamp));
+        if (!Number.isFinite(age) || age > toleranceMs) throw new Error('bePago webhook: timestamp fuera de la ventana permitida');
+        const payload = JSON.parse(body);
+        return { id: id ?? payload.id, event: payload.event, livemode: payload.livemode, data: payload.data };
+      },
+    },
+  };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@bepago/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "SDK oficial de bePago para Node.js (18+, sin dependencias)",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "bepago",
+    "pagos",
+    "payments",
+    "paraguay",
+    "cobros",
+    "payouts",
+    "webhooks"
+  ],
+  "homepage": "https://bepago.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bepago/sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bepago/sdk-node/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "bePago",
+  "license": "MIT"
+}