@pagosrd/azul 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+import { Dispatcher } from 'undici';
+
+type AzulEnvironment = "pruebas" | "produccion";
+/**
+ * URLs de AZUL según los documentos técnicos oficiales 2026 (Página de Pago e
+ * Integración vía API). La URL alterna de producción viene de `pyazul` (MIT):
+ * PENDIENTE DE VERIFICAR, el manual menciona un sitio secundario sin dar la URL.
+ */
+declare const AZUL_URLS: {
+    readonly pruebas: {
+        readonly webservices: "https://pruebas.azul.com.do/webservices/JSON/Default.aspx";
+        readonly paymentPage: "https://pruebas.azul.com.do/PaymentPage/";
+    };
+    readonly produccion: {
+        readonly webservices: "https://pagos.azul.com.do/webservices/JSON/Default.aspx";
+        readonly webservicesAlterna: "https://contpagos.azul.com.do/Webservices/JSON/default.aspx";
+        readonly paymentPage: "https://pagos.azul.com.do/PaymentPage/Default.aspx";
+    };
+};
+interface AzulPaymentPageConfig {
+    /** Llave privada de la Página de Pagos ("AuthKey"), entregada por AZUL. */
+    authKey: string;
+    /** Nombre del comercio que se muestra en la Página de Pagos. */
+    merchantName: string;
+    /** Tipo de comercio, según lo asigna AZUL. */
+    merchantType: string;
+    /** Reemplaza el cálculo del AuthHash (por defecto, el del manual oficial: `defaultPaymentPageHash`). */
+    hashFn?: (fields: Record<string, string>, authKey: string) => string;
+}
+/** Datos de una solicitud o respuesta, ya sin datos de tarjeta, para logs. */
+interface AzulRedactedEvent {
+    operation: string;
+    url: string;
+    payload: Record<string, unknown>;
+}
+interface AzulClientConfig {
+    /** Merchant ID (MID) del comercio, se envía como "Store". */
+    merchantId: string;
+    /** Credencial "Auth1" del comercio. */
+    auth1: string;
+    /** Credencial "Auth2" del comercio. */
+    auth2: string;
+    /** Certificado de cliente en formato PEM (contenido, no ruta). */
+    certificate: string | Buffer;
+    /** Llave privada del certificado en formato PEM (contenido, no ruta). */
+    privateKey: string | Buffer;
+    environment: AzulEnvironment;
+    /** Canal de la transacción. Por defecto "EC" (e-commerce). */
+    channel?: string;
+    /** Tiempo máximo por solicitud en milisegundos. Por defecto 30000. */
+    timeoutMs?: number;
+    /** Reemplaza las URLs de los webservices (útil para pruebas o un proxy propio). */
+    urls?: {
+        webservices?: string;
+        webservicesAlterna?: string;
+    };
+    /** Requerido solo si vas a usar la Página de Pagos. */
+    paymentPage?: AzulPaymentPageConfig;
+    /**
+     * Dispatcher de undici a usar. Si lo pasas, el SDK NO configura el
+     * certificado de cliente por ti. Pensado para pruebas (MockAgent) o proxies.
+     */
+    dispatcher?: Dispatcher;
+    /** Se llama antes de cada solicitud con el payload ya censurado. Útil para logs. */
+    onRequest?: (event: AzulRedactedEvent) => void;
+    /** Se llama con cada respuesta de AZUL, censurada. */
+    onResponse?: (event: AzulRedactedEvent) => void;
+}
+
+interface PaymentPageInput {
+    /** Monto TOTAL en centavos, ITBIS incluido. */
+    amount: number;
+    /** ITBIS en centavos. 0 u omitido si está exento. */
+    itbis?: number;
+    /** Número de orden único del comercio (máx. 15). */
+    orderNumber: string;
+    /** URL https a la que AZUL devuelve al cliente si el pago se aprueba. */
+    approvedUrl: string;
+    /** URL https si el pago se declina (se envía como "DeclinedUrl"). */
+    declineUrl: string;
+    /** URL https si el cliente cancela. */
+    cancelUrl: string;
+    /** Idioma de la página. Por defecto "ES". */
+    locale?: "ES" | "EN";
+    /** Mostrar el resultado en la página de AZUL antes de volver. Por defecto true. */
+    showTransactionResult?: boolean;
+    /** Hasta dos campos personalizados que se muestran al cliente. */
+    customFields?: [CustomField?, CustomField?];
+    /** Nombre alterno en el estado de cuenta (máx. 25; letras, números, espacios, punto y coma). */
+    altMerchantName?: string;
+    /** Guardar la tarjeta en DataVault. */
+    saveToDataVault?: boolean;
+}
+interface CustomField {
+    label: string;
+    value: string;
+}
+interface PaymentPageRequest {
+    /** URL a la que se envía el formulario por POST. */
+    url: string;
+    /** Campos del formulario, ya con el AuthHash calculado. */
+    fields: Record<string, string>;
+    /** HTML listo para devolver al navegador; se envía solo al cargar. */
+    html: string;
+}
+/**
+ * Campos del requerimiento que entran en el AuthHash, en el orden exacto del
+ * "Documento técnico - Página de Pago AZUL 2026" (sección "Manejo de
+ * autenticación"), confirmado con el ejemplo de cálculo que AZUL nos envió.
+ */
+declare const PAYMENT_PAGE_HASH_FIELDS: readonly ["MerchantId", "MerchantName", "MerchantType", "CurrencyCode", "OrderNumber", "Amount", "ITBIS", "ApprovedUrl", "DeclinedUrl", "CancelUrl", "UseCustomField1", "CustomField1Label", "CustomField1Value", "UseCustomField2", "CustomField2Label", "CustomField2Value"];
+/** Campos del retorno a ApprovedUrl/DeclinedUrl que entran en su AuthHash, en orden. */
+declare const PAYMENT_PAGE_RESPONSE_HASH_FIELDS: readonly ["OrderNumber", "Amount", "AuthorizationCode", "DateTime", "ResponseCode", "IsoCode", "ResponseMessage", "ErrorDescription", "RRN"];
+/**
+ * AuthHash del requerimiento: HMAC-SHA512 con la AuthKey como llave sobre los
+ * campos concatenados más la AuthKey al final, en hexadecimal. AZUL acepta la
+ * cadena en UTF-8 o en UTF-16LE; usamos UTF-8, que es lo que reproduce el
+ * ejemplo oficial.
+ */
+declare function defaultPaymentPageHash(fields: Record<string, string>, authKey: string): string;
+/**
+ * AuthHash que AZUL manda en el retorno: HMAC-SHA512 con la AuthKey como llave
+ * sobre OrderNumber + Amount + AuthorizationCode + DateTime + ResponseCode +
+ * IsoCode + ResponseMessage + ErrorDescription + RRN + AuthKey, con la cadena
+ * en UTF-16LE ("Unicode"), según el manual.
+ */
+declare function paymentPageResponseHash(params: Record<string, string | undefined>, authKey: string): string;
+/**
+ * Verifica que un retorno de la Página de Pagos lo generó AZUL. Devuelve false
+ * si falta el AuthHash o no coincide. Compara en tiempo constante.
+ * OJO: el hash no cubre AzulOrderId, CardNumber ni ITBIS; esos valores vienen
+ * del navegador y no deben usarse para mover dinero sin otra confirmación.
+ */
+declare function verifyPaymentPageResponse(params: Record<string, string | undefined>, authKey: string): boolean;
+/** Escapa texto para HTML. pyazul NO escapa los valores; aquí sí, para evitar inyección de HTML. */
+declare function escapeHtml(value: string): string;
+
+type AzulStatus = "approved" | "declined" | "requires_3ds";
+/** Respuesta normalizada de una operación con AZUL. */
+interface AzulResult {
+    /** approved = aprobada, declined = declinada por el banco o por reglas, requires_3ds = falta autenticación 3D Secure. */
+    status: AzulStatus;
+    /** "ISO8583" en transacciones procesadas. */
+    responseCode: string | undefined;
+    /** "00" = aprobada. Cualquier otro código es una declinación. */
+    isoCode: string | undefined;
+    /** Mensaje de AZUL, por ejemplo "APROBADA". */
+    message: string | undefined;
+    /** Detalle del error o de la declinación, si lo hay. */
+    errorDescription: string | undefined;
+    authorizationCode: string | undefined;
+    /** Identificador de AZUL. Lo necesitas para capturar, anular o reembolsar. */
+    azulOrderId: string | undefined;
+    /** Número de referencia de la red (RRN), útil para conciliación. */
+    rrn: string | undefined;
+    /** Token de DataVault, si se pidió guardar la tarjeta. */
+    dataVaultToken: string | undefined;
+    /** Identificador propio con el que puedes consultar la transacción con verifyPayment. */
+    customOrderId: string | undefined;
+    /** Respuesta original de AZUL (sin datos de tarjeta completos). */
+    raw: Record<string, unknown>;
+}
+
+/** Resultado de verifyPayment: la transacción encontrada o `found: false`. */
+type VerifyPaymentResult = ({
+    found: true;
+} & AzulResult) | {
+    found: false;
+    customOrderId: string;
+    raw: Record<string, unknown>;
+};
+/** Datos comunes de las operaciones que mueven dinero. */
+interface OrderFields {
+    /** Monto TOTAL en centavos, ITBIS incluido. 150050 = RD$1,500.50. */
+    amount: number;
+    /** ITBIS en centavos. Omítelo o usa 0 si está exento. */
+    itbis?: number;
+    /** Número de orden del comercio (máx. 15 caracteres). */
+    orderNumber: string;
+    /**
+     * Identificador único tuyo (máx. 75). Si no lo pasas, el SDK genera uno.
+     * Guárdalo: es lo que permite consultar el resultado con verifyPayment si
+     * la conexión se cae a mitad de la operación.
+     */
+    customOrderId?: string;
+    /** Nombre alterno que aparece en el estado de cuenta del cliente (máx. 25). */
+    altMerchantName?: string;
+    /** "1" para forzar sin 3D Secure. Úsalo solo si AZUL lo autorizó para tu comercio. */
+    forceNo3DS?: boolean;
+}
+interface CardSaleInput extends OrderFields {
+    cardNumber: string;
+    /** "YYYYMM", "MM/YY" o "MM/YYYY". */
+    expiration: string;
+    cvc: string;
+    /** Guarda la tarjeta en DataVault y devuelve un token reutilizable. */
+    saveToDataVault?: boolean;
+}
+interface TokenSaleInput extends OrderFields {
+    dataVaultToken: string;
+    cvc?: string;
+}
+interface CaptureInput {
+    /** AzulOrderId de la pre-autorización (hold). */
+    azulOrderId: string;
+    /** Monto a capturar en centavos (puede ser menor que el retenido). */
+    amount: number;
+    itbis?: number;
+}
+interface RefundInput {
+    /** AzulOrderId de la venta original. */
+    azulOrderId: string;
+    amount: number;
+    itbis?: number;
+    orderNumber: string;
+    customOrderId?: string;
+}
+interface DataVaultCreateInput {
+    cardNumber: string;
+    expiration: string;
+    cvc: string;
+}
+interface DataVaultResult {
+    status: "approved" | "declined";
+    dataVaultToken: string | undefined;
+    /** Número enmascarado que devuelve AZUL, por ejemplo "411111******1111". */
+    maskedCardNumber: string | undefined;
+    brand: string | undefined;
+    /** Vencimiento del token, "YYYYMM". */
+    expiration: string | undefined;
+    hasCvv: boolean;
+    isoCode: string | undefined;
+    message: string | undefined;
+    errorDescription: string | undefined;
+    raw: Record<string, unknown>;
+}
+/**
+ * Cliente para los webservices de AZUL.
+ *
+ * ```ts
+ * const azul = new AzulClient({
+ *   environment: "pruebas",
+ *   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!,
+ * });
+ * ```
+ */
+declare class AzulClient {
+    private readonly config;
+    private readonly transport;
+    constructor(config: AzulClientConfig);
+    /** Cierra las conexiones abiertas. Llámalo al apagar tu servidor. */
+    close(): Promise<void>;
+    /**
+     * Venta directa con datos de tarjeta.
+     *
+     * OJO: recibir el número de tarjeta en tu servidor te pone dentro del
+     * alcance de PCI DSS. Si puedes, usa la Página de Pagos (paymentPage) o
+     * cobra con un token de DataVault (tokenSale).
+     */
+    sale(input: CardSaleInput): Promise<AzulResult>;
+    /** Pre-autorización: retiene el monto sin cobrarlo. Captúralo luego con capture(). */
+    hold(input: CardSaleInput): Promise<AzulResult>;
+    /** Venta con una tarjeta guardada en DataVault. */
+    tokenSale(input: TokenSaleInput): Promise<AzulResult>;
+    /** Captura (total o parcial) una pre-autorización hecha con hold(). */
+    capture(input: CaptureInput): Promise<AzulResult>;
+    /** Anula una transacción del mismo día (antes del cierre de lote). */
+    void(input: {
+        azulOrderId: string;
+    }): Promise<AzulResult>;
+    /** Reembolsa (total o parcialmente) una venta ya liquidada. */
+    refund(input: RefundInput): Promise<AzulResult>;
+    /**
+     * Consulta el estado de una transacción hecha por la API (ProcessPayment) por
+     * su customOrderId. Es la forma correcta de salir de la duda después de un
+     * AzulAmbiguousError. Si hay varias con el mismo id, AZUL devuelve la última.
+     * Si no existe, AZUL responde Found=false y aquí se devuelve `{ found: false }`.
+     */
+    verifyPayment(input: {
+        customOrderId: string;
+    }): Promise<VerifyPaymentResult>;
+    readonly dataVault: {
+        /** Guarda una tarjeta y devuelve un token reutilizable. */
+        create: (input: DataVaultCreateInput) => Promise<DataVaultResult>;
+        /** Elimina un token de DataVault. */
+        delete: (input: {
+            dataVaultToken: string;
+        }) => Promise<DataVaultResult>;
+    };
+    /**
+     * Prepara el formulario para redirigir al cliente a la Página de Pagos de
+     * AZUL. Con esta vía tu servidor nunca ve el número de tarjeta.
+     */
+    paymentPage(input: PaymentPageInput): PaymentPageRequest;
+    private base;
+    private customOrderId;
+    private orderFields;
+    private cardTransaction;
+}
+
+/**
+ * Errores del SDK.
+ *
+ * Regla de diseño: un pago DECLINADO no es una excepción. Una declinación es una
+ * respuesta normal del banco y se devuelve como `status: "declined"`.
+ * Las excepciones se reservan para cosas que el código que llama debe manejar
+ * de forma distinta: configuración inválida, datos inválidos, fallas del
+ * sistema de AZUL y, sobre todo, resultados AMBIGUOS (no sabemos si se cobró).
+ */
+declare class AzulError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** La configuración del cliente es inválida (credenciales, certificado, ambiente). */
+declare class AzulConfigError extends AzulError {
+    readonly name = "AzulConfigError";
+}
+/** Los datos de la operación son inválidos. No se envió nada a AZUL. */
+declare class AzulValidationError extends AzulError {
+    readonly name = "AzulValidationError";
+    readonly issues: string[];
+    constructor(message: string, issues?: string[]);
+}
+/**
+ * AZUL respondió, pero con un error de sistema (ResponseCode "Error",
+ * errores SGS de gateway o ErrorMessage). La operación NO fue aprobada.
+ */
+declare class AzulResponseError extends AzulError {
+    readonly name = "AzulResponseError";
+    readonly response: Record<string, unknown>;
+    constructor(message: string, response: Record<string, unknown>);
+}
+/** AZUL respondió con un código HTTP de error y la operación es segura de tratar como no ejecutada. */
+declare class AzulHttpError extends AzulError {
+    readonly name = "AzulHttpError";
+    readonly statusCode: number;
+    readonly body: string;
+    constructor(message: string, statusCode: number, body: string);
+}
+/**
+ * La solicitud pudo haber llegado a AZUL, pero no recibimos una respuesta
+ * confiable (timeout de lectura, conexión cortada, HTTP 5xx, JSON inválido).
+ *
+ * NO reintentes a ciegas una operación que mueve dinero: podrías cobrar dos
+ * veces. Consulta el estado con `verifyPayment({ customOrderId })` y decide.
+ */
+declare class AzulAmbiguousError extends AzulError {
+    readonly name = "AzulAmbiguousError";
+    readonly customOrderId: string | undefined;
+    constructor(message: string, customOrderId: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * Convierte un monto escrito en pesos a centavos SIN pasar por punto flotante.
+ *
+ * toCents("1,500.50") === 150050
+ * toCents("1500")     === 150000
+ * toCents(1500.5)     === 150050
+ */
+declare function toCents(amount: string | number): number;
+
+/**
+ * Censura de datos sensibles para logs. Nunca registres un número de tarjeta
+ * completo ni un CVC: eso te mete de lleno en el alcance de PCI DSS.
+ */
+declare function maskPan(pan: string): string;
+declare function redact(payload: Record<string, unknown>): Record<string, unknown>;
+
+/** Algoritmo de Luhn: detecta errores de digitación en números de tarjeta. */
+declare function passesLuhn(digits: string): boolean;
+
+export { AZUL_URLS, AzulAmbiguousError, AzulClient, type AzulClientConfig, AzulConfigError, type AzulEnvironment, AzulError, AzulHttpError, type AzulPaymentPageConfig, type AzulRedactedEvent, AzulResponseError, type AzulResult, type AzulStatus, AzulValidationError, type CaptureInput, type CardSaleInput, type CustomField, type DataVaultCreateInput, type DataVaultResult, PAYMENT_PAGE_HASH_FIELDS, PAYMENT_PAGE_RESPONSE_HASH_FIELDS, type PaymentPageInput, type PaymentPageRequest, type RefundInput, type TokenSaleInput, type VerifyPaymentResult, defaultPaymentPageHash, escapeHtml, maskPan, passesLuhn, paymentPageResponseHash, redact, toCents, verifyPaymentPageResponse };