@pagosrd/azul 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Encarnación
+
+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,157 @@
-# Temporary Holding Version
+# @pagosrd/azul
 
-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 **no oficial** en TypeScript para la pasarela de pagos **AZUL** (República Dominicana).
+
+> AZUL es una marca de Servicios Digitales Popular. Este paquete no está afiliado ni respaldado por AZUL.
+
+## Qué cubre
+
+| Operación | Método |
+|---|---|
+| Venta con tarjeta | `sale()` |
+| Pre-autorización y captura | `hold()` y `capture()` |
+| Anulación del mismo día | `void()` |
+| Reembolso | `refund()` |
+| Consultar el estado | `verifyPayment()` |
+| Guardar y borrar tarjetas | `dataVault.create()` y `dataVault.delete()` |
+| Cobrar con tarjeta guardada | `tokenSale()` |
+| Página de Pagos alojada | `paymentPage()` |
+
+Además:
+- **Failover seguro:** en producción usa la URL alterna de AZUL solo cuando la solicitud no llegó a salir. Si pudo haberse cobrado, lanza `AzulAmbiguousError` en vez de reintentar.
+- Montos en centavos enteros, con `toCents("1,500.50")` para convertir.
+- Validación previa al envío: Luhn, vencimiento y largo de los campos.
+- Logs censurados con `onRequest` y `onResponse`.
+
+## Instalación
+
+```bash
+pnpm add @pagosrd/azul
+```
+
+Requiere Node 20 o superior.
+
+## Uso
+
+```ts
+import { AzulClient, AzulAmbiguousError, toCents } from "@pagosrd/azul";
+
+const azul = new AzulClient({
+  environment: "pruebas", // o "produccion"
+  merchantId: process.env.AZUL_MERCHANT_ID!,
+  auth1: process.env.AZUL_AUTH1!,
+  auth2: process.env.AZUL_AUTH2!,
+  certificate: process.env.AZUL_CERT_PEM!, // contenido PEM, no la ruta
+  privateKey: process.env.AZUL_KEY_PEM!,
+});
+
+try {
+  const result = await azul.tokenSale({
+    amount: toCents("4,500.00"),
+    orderNumber: "CUOTA-4B-10",
+    customOrderId: "cuota-apto-4b-2026-10", // guárdalo antes de cobrar
+    dataVaultToken: tarjetaGuardada,
+  });
+
+  if (result.status === "approved") {
+    // guarda result.azulOrderId para reembolsos o anulaciones
+  } else if (result.status === "declined") {
+    console.log(result.errorDescription);
+  }
+} catch (err) {
+  if (err instanceof AzulAmbiguousError) {
+    // No reintentes: consulta primero
+    const estado = await azul.verifyPayment({ customOrderId: err.customOrderId! });
+  }
+  throw err;
+}
+```
+
+### Guía: cobrar con la Página de Pago de AZUL en Node
+
+La Página de Pago es la forma recomendada: el cliente escribe la tarjeta en la página de AZUL y tu servidor nunca la ve. Son tres pasos.
+
+**1. Configura el cliente con la AuthKey de la Página de Pago.**
+
+```ts
+import { AzulClient, toCents, verifyPaymentPageResponse } from "@pagosrd/azul";
+
+const azul = new AzulClient({
+  environment: "pruebas", // o "produccion"
+  merchantId: process.env.AZUL_MERCHANT_ID!,
+  auth1: process.env.AZUL_AUTH1!,
+  auth2: process.env.AZUL_AUTH2!,
+  certificate: process.env.AZUL_CERT_PEM!,
+  privateKey: process.env.AZUL_KEY_PEM!,
+  paymentPage: {
+    authKey: process.env.AZUL_AUTH_KEY!,
+    merchantName: "Residencial Las Palmas",
+    merchantType: "ECommerce",
+  },
+});
+```
+
+**2. Arma el formulario y envía al cliente a AZUL.** `paymentPage()` calcula el `AuthHash` (HMAC-SHA512 con la AuthKey, como indica el documento técnico 2026) y devuelve un HTML que redirige solo.
+
+```ts
+// Ejemplo con Hono; con Express es igual: res.type("html").send(page.html)
+app.post("/cuotas/:id/pagar", (c) => {
+  const page = azul.paymentPage({
+    amount: toCents("4,500.00"),       // centavos enteros
+    orderNumber: "CUOTA4B10",          // guárdalo junto a la cuota
+    approvedUrl: "https://tusitio.do/azul/aprobado",
+    declineUrl: "https://tusitio.do/azul/declinado",
+    cancelUrl: "https://tusitio.do/azul/cancelado",
+    customFields: [{ label: "Apartamento", value: "4B" }],
+  });
+  return c.html(page.html);
+});
+```
+
+**3. Verifica la respuesta en tu servidor antes de dar el pago por cobrado.** AZUL devuelve al cliente a `approvedUrl` o `declineUrl` con un `AuthHash` propio (HMAC-SHA512 en UTF-16LE). Llegar a `approvedUrl` no basta: valida la firma y que el número de orden y el monto sean los que enviaste.
+
+```ts
+app.get("/azul/aprobado", (c) => {
+  const params = c.req.query(); // AZUL envía los campos en la URL
+  const cuota = buscarCuota(params.OrderNumber);
+
+  const firmaValida = verifyPaymentPageResponse(params, process.env.AZUL_AUTH_KEY!);
+  const coincide = cuota && params.Amount === String(cuota.montoEnCentavos);
+  const aprobado = params.ResponseCode === "ISO8583" && params.IsoCode === "00";
+
+  if (firmaValida && coincide && aprobado) {
+    marcarPagada(cuota, { autorizacion: params.AuthorizationCode, rrn: params.RRN });
+  } else {
+    marcarParaRevision(params.OrderNumber); // nunca la des por pagada
+  }
+  return c.redirect(`/cuotas/${cuota?.id ?? ""}`);
+});
+```
+
+`AzulOrderId` y `CardNumber` llegan en la respuesta pero no forman parte de la firma: no los uses para decidir.
+
+## Errores
+
+| Error | Significa | Qué hacer |
+|---|---|---|
+| `AzulValidationError` | Datos inválidos, no se envió nada | Corregir la entrada |
+| `AzulConfigError` | Configuración incompleta | Revisar credenciales y certificado |
+| `AzulResponseError` | AZUL respondió con error de sistema | No se aprobó; revisar `response` |
+| `AzulHttpError` | HTTP 4xx | No se procesó |
+| `AzulAmbiguousError` | No sabemos si se cobró | `verifyPayment({ customOrderId })` antes de reintentar |
+
+Un pago **declinado no es una excepción**: llega como `status: "declined"`.
+
+## Estado
+
+Confirmado con los documentos técnicos de AZUL 2026 y con transacciones reales en su ambiente de pruebas:
+
+- El `AuthHash` del requerimiento de la Página de Pago.
+- La firma (`AuthHash`) de la respuesta a `approvedUrl` y `declineUrl`.
+- La respuesta de `VerifyPayment` cuando la transacción no existe (`Found: false`).
+
+Pendiente de verificar: la URL alterna de producción para el failover (viene del SDK de referencia `pyazul`, MIT; el manual menciona un sitio secundario sin dar la URL).
+
+## Licencia
+
+MIT