@bepago/sdk 0.0.0-stage → 1.0.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,99 @@
-# 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. Verificá la firma antes de procesar el evento:
+
+```js
+import BePago from 'bepago';
+
+const bp = BePago('sk_live_…');
+
+// En tu handler HTTP (body como string crudo, sin re-serializar):
+const timestamp = req.headers['x-timestamp'];
+const signature = req.headers['x-signature'];
+const rawBody = req.rawBody; // el cuerpo tal cual llegó
+
+const ok = bp.webhooks.verify(
+  'whsec_tu_secreto_de_webhook',
+  timestamp,
+  rawBody,
+  signature,
+);
+
+if (!ok) {
+  return res.status(400).send('firma inválida');
+}
+
+const evento = JSON.parse(rawBody);
+// procesar evento.type …
+```
+
+## Documentación
+
+Referencia completa de la API, tipos de eventos y ejemplos:
+**https://bepago.com/docs**
+
+## Licencia
+
+MIT

package/index.mjs

@@ -0,0 +1,79 @@
+/**
+ * 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: {
+      verify: (webhookSecret, timestamp, body, signature) => {
+        const expected = createHmac('sha256', webhookSecret).update(timestamp + body, 'utf8').digest('hex');
+        return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
+      },
+    },
+  };
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@bepago/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.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"
+}