@pagosrd/node 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+export { SIGNATURE_HEADER, WebhookSignatureError, formatMoney, toCents } from '@pagosrd/core';
+
+/** Tipos de los objetos de la API de PagosRD. Montos en centavos. */
+type Livemode = boolean;
+interface List<T> {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+}
+/** Lo que el tarjetahabiente ve antes de pagar (requisito de Visa y Mastercard). */
+interface CustomerInfo {
+    support_email: string | null;
+    support_phone: string | null;
+    address_line: string | null;
+    address_city: string | null;
+    /** País, ISO 3166-1 alfa-2 (por ejemplo "DO"). */
+    address_country: string;
+    refund_policy: string | null;
+    delivery_policy: string | null;
+}
+/** Campos omitidos no cambian; null o "" los borra. En live son obligatorios todos. */
+type CustomerInfoParams = Partial<Omit<CustomerInfo, "address_country">> & {
+    address_country?: string;
+};
+interface Merchant {
+    id: string;
+    object: "merchant";
+    livemode: Livemode;
+    name: string;
+    rnc: string | null;
+    external_id: string | null;
+    processor: "simulador" | "azul" | "cardnet";
+    processor_configured: boolean;
+    processor_summary: Record<string, string>;
+    status: "active" | "disabled";
+    metadata: Record<string, string>;
+    customer_info: CustomerInfo;
+    /** true si ya tiene contacto, dirección y políticas: lo necesario para cobrar en vivo. */
+    customer_info_complete: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface AzulConfig {
+    environment: "pruebas" | "produccion";
+    merchant_id: string;
+    auth1: string;
+    auth2: string;
+    certificate_pem: string;
+    private_key_pem: string;
+    payment_page: {
+        auth_key: string;
+        merchant_name: string;
+        merchant_type: string;
+    };
+}
+interface CardnetConfig {
+    environment: "certificacion" | "produccion";
+    merchant_number: string;
+    merchant_terminal: string;
+    merchant_terminal_amex?: string;
+    merchant_type: string;
+    merchant_name: string;
+    acquiring_institution_code?: string;
+}
+interface PaymentLink {
+    id: string;
+    object: "payment_link";
+    livemode: Livemode;
+    url: string;
+    merchant_id: string;
+    amount: number;
+    itbis: number;
+    currency: "DOP" | "USD";
+    description: string;
+    reference: string | null;
+    customer: {
+        name: string | null;
+        email: string | null;
+        phone: string | null;
+        reference: string | null;
+    };
+    /** true si la tarjeta con la que se pague queda guardada. */
+    save_payment_method: boolean;
+    locale: "es" | "en";
+    success_url: string | null;
+    status: "open" | "paid" | "expired" | "canceled";
+    expires_at: string | null;
+    paid_at: string | null;
+    payment_id: string | null;
+    metadata: Record<string, string>;
+    created_at: string;
+}
+type PaymentStatus = "pending" | "processing" | "succeeded" | "failed" | "canceled";
+interface Payment {
+    id: string;
+    object: "payment";
+    livemode: Livemode;
+    merchant_id: string;
+    payment_link_id: string | null;
+    /** Tarjeta guardada con la que se cobró (cobros por API). */
+    payment_method_id: string | null;
+    /** Concepto del cobro por API; en los pagos de un link está en el link. */
+    description: string | null;
+    reference: string | null;
+    /** Serie recurrente del cobro con tarjeta guardada; null en links y compras puntuales. */
+    recurring: RecurringType | null;
+    /** customer = lo inició el cliente (CIT); merchant = lo inició el comercio sobre una serie ya autorizada (MIT). */
+    initiated_by: "customer" | "merchant" | null;
+    /** Suscripción que generó este cobro. */
+    subscription_id: string | null;
+    /** Periodo de la suscripción que cobra (1 = el primero). */
+    subscription_period: number | null;
+    amount: number;
+    itbis: number;
+    amount_refunded: number;
+    itbis_refunded: number;
+    currency: "DOP" | "USD";
+    status: PaymentStatus;
+    requires_review: boolean;
+    processor: "simulador" | "azul" | "cardnet";
+    order_number: string;
+    processor_order_id: string | null;
+    authorization_code: string | null;
+    card: {
+        brand: string | null;
+        last4: string;
+    } | null;
+    failure_code: string | null;
+    failure_message: string | null;
+    metadata: Record<string, string>;
+    paid_at: string | null;
+    created_at: string;
+}
+/** Tarjeta guardada (DataVault de AZUL o el simulador). El token nunca sale de PagosRD. */
+interface PaymentMethod {
+    id: string;
+    object: "payment_method";
+    livemode: Livemode;
+    merchant_id: string;
+    /** Id del cliente en tu sistema. */
+    customer_reference: string;
+    processor: "simulador" | "azul" | "cardnet";
+    card: {
+        brand: string | null;
+        last4: string | null;
+        exp_month: number | null;
+        exp_year: number | null;
+    };
+    status: "active" | "deleted";
+    source_payment_id: string | null;
+    created_at: string;
+    deleted_at: string | null;
+}
+type SubscriptionStatus = "active" | "past_due" | "unpaid" | "canceled" | "completed";
+/**
+ * Cobro automático y periódico con una tarjeta guardada. PagosRD crea cada cobro en
+ * su fecha; cada uno llega como `payment.succeeded` o `payment.failed` con `subscription_id`.
+ */
+interface Subscription {
+    id: string;
+    object: "subscription";
+    livemode: Livemode;
+    merchant_id: string;
+    payment_method_id: string;
+    customer_reference: string;
+    kind: RecurringType;
+    description: string;
+    reference: string | null;
+    metadata: Record<string, string>;
+    amount: number;
+    itbis: number;
+    currency: "DOP" | "USD";
+    interval: "week" | "month";
+    interval_count: number;
+    start_at: string;
+    total_charges: number | null;
+    charges_count: number;
+    /** active al día; past_due reintentando; unpaid sin más reintentos (reactívala con retry o cambiando la tarjeta); canceled; completed. */
+    status: SubscriptionStatus;
+    next_charge_at: string | null;
+    failed_attempts: number;
+    /** Periodo que se está cobrando o el próximo (1 = el primero). */
+    current_period: number;
+    /** Cobro en curso esperando la confirmación del procesador. */
+    pending_payment_id: string | null;
+    last_payment_id: string | null;
+    last_failure: {
+        code: string;
+        message: string | null;
+    } | null;
+    canceled_at: string | null;
+    created_at: string;
+}
+interface CreateSubscriptionParams {
+    payment_method_id: string;
+    /** Monto de cada cobro en centavos, ITBIS incluido. */
+    amount: number;
+    itbis?: number;
+    description: string;
+    reference?: string | null;
+    metadata?: Record<string, string>;
+    interval: "week" | "month";
+    /** Cada cuántos intervalos (por defecto 1). */
+    interval_count?: number;
+    /** Por defecto subscription (monto fijo). installment exige total_charges. */
+    kind?: RecurringType;
+    total_charges?: number | null;
+    /** ISO 8601. Fecha del primer cobro; por defecto, ahora. */
+    start_at?: string | null;
+}
+interface UpdateSubscriptionParams {
+    /** Otra tarjeta del mismo cliente. Reactiva una suscripción past_due o unpaid. */
+    payment_method_id?: string;
+    amount?: number;
+    itbis?: number;
+    description?: string;
+    reference?: string | null;
+    metadata?: Record<string, string>;
+}
+interface Refund {
+    id: string;
+    object: "refund";
+    livemode: Livemode;
+    payment_id: string;
+    amount: number;
+    itbis: number;
+    reason: string | null;
+    status: "pending" | "succeeded" | "failed";
+    failure_message: string | null;
+    created_at: string;
+}
+type EventType = "payment.succeeded" | "payment.failed" | "payment.requires_review" | "payment_link.paid" | "payment_link.expired" | "payment_link.canceled" | "refund.succeeded" | "refund.failed" | "payment_method.created" | "payment_method.deleted" | "subscription.created" | "subscription.updated" | "subscription.past_due" | "subscription.period_unpaid" | "subscription.unpaid" | "subscription.canceled" | "subscription.completed";
+interface EventBase<T extends EventType, D> {
+    id: string;
+    object: "event";
+    livemode: Livemode;
+    type: T;
+    data: D;
+    created_at: string;
+}
+/** Evento de webhook. `type` discrimina el contenido de `data`. */
+type Event = EventBase<"payment.succeeded", {
+    object: Payment;
+    payment_link_reference: string | null;
+    saved_payment_method: PaymentMethod | null;
+}> | EventBase<"payment.failed" | "payment.requires_review", {
+    object: Payment;
+}> | EventBase<"payment_link.paid" | "payment_link.expired" | "payment_link.canceled", {
+    object: PaymentLink;
+}> | EventBase<"refund.succeeded", {
+    object: Refund;
+    payment: Payment;
+}> | EventBase<"refund.failed", {
+    object: Refund;
+}> | EventBase<"payment_method.created", {
+    object: PaymentMethod;
+    payment_id: string;
+}> | EventBase<"payment_method.deleted", {
+    object: PaymentMethod;
+}> | EventBase<"subscription.created" | "subscription.updated" | "subscription.past_due" | "subscription.unpaid" | "subscription.canceled" | "subscription.completed", {
+    object: Subscription;
+}>
+/** Un periodo venció sin cobrarse (se agotó su tiempo o sus reintentos). Cóbralo por otra vía si corresponde. */
+ | EventBase<"subscription.period_unpaid", {
+    object: Subscription;
+    periods: Array<{
+        period: number;
+        due_at: string;
+        amount: number;
+    }>;
+}>;
+interface WebhookEndpoint {
+    id: string;
+    object: "webhook_endpoint";
+    livemode: Livemode;
+    url: string;
+    description: string | null;
+    events: string[];
+    enabled: boolean;
+    created_at: string;
+}
+interface WebhookDelivery {
+    id: string;
+    object: "webhook_delivery";
+    event_id: string;
+    event_type: string | null;
+    endpoint_id: string;
+    status: "pending" | "succeeded" | "failed";
+    attempts: number;
+    last_response_status: number | null;
+    last_response_body: string | null;
+    last_error: string | null;
+    next_attempt_at: string | null;
+    delivered_at: string | null;
+    created_at: string;
+}
+interface Summary {
+    object: "summary";
+    from: string;
+    to: string;
+    succeeded_count: number;
+    succeeded_amount: number;
+    refunded_amount: number;
+    failed_count: number;
+    review_count: number;
+    daily: {
+        day: string;
+        amount: number;
+        count: number;
+    }[];
+}
+interface PageParams {
+    limit?: number;
+    starting_after?: string;
+}
+interface CreatePaymentLinkParams {
+    merchant_id: string;
+    /** Total en centavos, ITBIS incluido. 450000 = RD$4,500.00 */
+    amount: number;
+    itbis?: number;
+    description: string;
+    reference?: string | null;
+    /** `reference` = id del cliente en tu sistema; obligatorio con save_payment_method. */
+    customer?: {
+        name?: string | null;
+        email?: string | null;
+        phone?: string | null;
+        reference?: string | null;
+    };
+    /** Guardar la tarjeta con la que se pague para cobrar después con payments.create. */
+    save_payment_method?: boolean;
+    locale?: "es" | "en";
+    success_url?: string | null;
+    expires_at?: string | null;
+    metadata?: Record<string, string>;
+}
+interface CreateMerchantParams {
+    name: string;
+    rnc?: string | null;
+    external_id?: string | null;
+    processor: "simulador" | "azul" | "cardnet";
+    processor_config?: AzulConfig | CardnetConfig;
+    customer_info?: CustomerInfoParams;
+    metadata?: Record<string, string>;
+}
+interface CreatePaymentParams {
+    payment_method_id: string;
+    /** Total en centavos, ITBIS incluido. */
+    amount: number;
+    itbis?: number;
+    description: string;
+    reference?: string | null;
+    metadata?: Record<string, string>;
+    /**
+     * Serie recurrente del cobro. Sin él es una compra puntual con el cliente presente,
+     * que con AZUL todavía no está disponible (necesita 3D Secure).
+     */
+    recurring?: RecurringType;
+}
+/** subscription = monto y frecuencia fijos; standing_order = monto variable, frecuencia fija; installment = cuotas. */
+type RecurringType = "subscription" | "standing_order" | "installment";
+interface CreateRefundParams {
+    amount?: number;
+    itbis?: number;
+    reason?: string | null;
+}
+interface RequestOptions {
+    /** Llave de idempotencia propia. Si no la pasas, el SDK genera una por solicitud. */
+    idempotencyKey?: string;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.pagosrd.com";
+/** Error devuelto por la API (Problem Details). */
+declare class PagosRDError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly field: string | undefined;
+    readonly requestId: string | undefined;
+    readonly raw: unknown;
+    readonly name = "PagosRDError";
+    constructor(message: string, status: number, code: string, field: string | undefined, requestId: string | undefined, raw: unknown);
+}
+/** No se pudo hablar con la API (red caída, timeout). */
+declare class PagosRDConnectionError extends Error {
+    readonly name = "PagosRDConnectionError";
+}
+interface PagosRDOptions {
+    /** Por defecto https://api.pagosrd.com */
+    baseUrl?: string;
+    /** Reintentos ante fallas de red, 429 y 5xx. Por defecto 2. Los POST llevan llave de idempotencia, así que reintentar es seguro. */
+    maxRetries?: number;
+    /** Tiempo máximo por solicitud en ms. Por defecto 30000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+declare class PagosRD {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(apiKey: string, options?: PagosRDOptions);
+    /** true si la llave es de modo de prueba. */
+    get testMode(): boolean;
+    readonly paymentLinks: {
+        create: (params: CreatePaymentLinkParams, opts?: RequestOptions) => Promise<PaymentLink>;
+        retrieve: (id: string) => Promise<PaymentLink>;
+        list: (params?: PageParams & {
+            status?: PaymentLink["status"];
+            merchant_id?: string;
+            reference?: string;
+        }) => Promise<List<PaymentLink>>;
+        cancel: (id: string) => Promise<PaymentLink>;
+    };
+    readonly payments: {
+        /**
+         * Cobra con una tarjeta guardada, sin que el cliente vea ninguna página. La llave de
+         * idempotencia es obligatoria: usa algo propio de la operación (el id del pedido) para
+         * que reintentar nunca cobre dos veces. El pago vuelve succeeded, failed o processing.
+         */
+        create: (params: CreatePaymentParams, opts: RequestOptions & {
+            idempotencyKey: string;
+        }) => Promise<Payment>;
+        retrieve: (id: string) => Promise<Payment>;
+        list: (params?: PageParams & {
+            status?: PaymentStatus;
+            merchant_id?: string;
+            payment_link_id?: string;
+            payment_method_id?: string;
+            subscription_id?: string;
+            created_gte?: string;
+            created_lte?: string;
+        }) => Promise<List<Payment>>;
+    };
+    readonly paymentMethods: {
+        retrieve: (id: string) => Promise<PaymentMethod>;
+        list: (params?: PageParams & {
+            merchant_id?: string;
+            customer_reference?: string;
+            status?: PaymentMethod["status"];
+        }) => Promise<List<PaymentMethod>>;
+        /** Deja de poder usarse de inmediato y se borra el token en el procesador. */
+        del: (id: string) => Promise<PaymentMethod>;
+    };
+    readonly subscriptions: {
+        /**
+         * PagosRD cobra solo en cada fecha con la tarjeta guardada; reintenta los rechazos a 1, 3 y 5 días.
+         * La llave de idempotencia es obligatoria: usa el id del contrato para que reintentar no cree otra.
+         */
+        create: (params: CreateSubscriptionParams, opts: RequestOptions & {
+            idempotencyKey: string;
+        }) => Promise<Subscription>;
+        retrieve: (id: string) => Promise<Subscription>;
+        list: (params?: PageParams & {
+            status?: SubscriptionStatus;
+            merchant_id?: string;
+            customer_reference?: string;
+            payment_method_id?: string;
+        }) => Promise<List<Subscription>>;
+        update: (id: string, params: UpdateSubscriptionParams) => Promise<Subscription>;
+        /** Reintenta ya el cobro de una suscripción past_due o unpaid con la misma tarjeta. */
+        retry: (id: string) => Promise<Subscription>;
+        cancel: (id: string) => Promise<Subscription>;
+    };
+    readonly refunds: {
+        create: (paymentId: string, params?: CreateRefundParams, opts?: RequestOptions) => Promise<Refund>;
+        list: (params?: PageParams & {
+            payment_id?: string;
+        }) => Promise<List<Refund>>;
+    };
+    readonly merchants: {
+        create: (params: CreateMerchantParams) => Promise<Merchant>;
+        retrieve: (id: string) => Promise<Merchant>;
+        list: (params?: PageParams) => Promise<List<Merchant>>;
+        update: (id: string, params: {
+            name?: string;
+            rnc?: string | null;
+            status?: "active" | "disabled";
+            metadata?: Record<string, string>;
+            customer_info?: CustomerInfoParams;
+        }) => Promise<Merchant>;
+        setProcessorConfig: (id: string, config: AzulConfig | CardnetConfig) => Promise<Merchant>;
+        balance: (id: string) => Promise<{
+            object: "balance";
+            merchant_id: string;
+            processor_receivable: number;
+        }>;
+    };
+    readonly webhookEndpoints: {
+        create: (params: {
+            url: string;
+            events?: string[];
+            description?: string | null;
+        }) => Promise<WebhookEndpoint & {
+            secret: string;
+        }>;
+        list: () => Promise<List<WebhookEndpoint>>;
+        retrieve: (id: string) => Promise<WebhookEndpoint>;
+        update: (id: string, params: {
+            url?: string;
+            events?: string[];
+            description?: string | null;
+            enabled?: boolean;
+        }) => Promise<WebhookEndpoint>;
+        del: (id: string) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+        rollSecret: (id: string) => Promise<{
+            secret: string;
+        }>;
+        deliveries: (params?: PageParams & {
+            endpoint_id?: string;
+            event_id?: string;
+            status?: WebhookDelivery["status"];
+        }) => Promise<List<WebhookDelivery>>;
+    };
+    readonly events: {
+        retrieve: (id: string) => Promise<Event>;
+        list: (params?: PageParams & {
+            type?: string;
+        }) => Promise<List<Event>>;
+        resend: (id: string, endpointId?: string) => Promise<List<WebhookDelivery>>;
+    };
+    summary(params?: {
+        from?: string;
+        to?: string;
+    }): Promise<Summary>;
+    /**
+     * Recorre todas las páginas de una lista.
+     *
+     * for await (const pago of client.autoPaginate((p) => client.payments.list({ ...p, status: "succeeded" }))) { … }
+     */
+    autoPaginate<T extends {
+        id: string;
+    }>(fetchPage: (page: PageParams) => Promise<List<T>>, pageSize?: number): AsyncGenerator<T>;
+    private get;
+    private post;
+    private request;
+}
+
+/**
+ * Verifica la firma de un webhook y devuelve el evento tipado.
+ *
+ * IMPORTANTE: pasa el cuerpo CRUDO (string o Buffer), tal como llegó. Si tu
+ * framework ya lo convirtió a JSON, la firma no va a coincidir.
+ *
+ * ```ts
+ * app.post("/webhooks/pagosrd", express.raw({ type: "application/json" }), (req, res) => {
+ *   const event = constructEvent(req.body, req.header("PagosRD-Signature"), process.env.PAGOSRD_WEBHOOK_SECRET!);
+ *   if (event.type === "payment.succeeded") marcarCuotaPagada(event.data.payment_link_reference);
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+declare function constructEvent(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, toleranceSeconds?: number): Event;
+
+export { type AzulConfig, type CardnetConfig, type CreateMerchantParams, type CreatePaymentLinkParams, type CreatePaymentParams, type CreateRefundParams, type CreateSubscriptionParams, type CustomerInfo, type CustomerInfoParams, DEFAULT_BASE_URL, type Event, type EventType, type List, type Livemode, type Merchant, type PageParams, PagosRD, PagosRDConnectionError, PagosRDError, type PagosRDOptions, type Payment, type PaymentLink, type PaymentMethod, type PaymentStatus, type RecurringType, type Refund, type RequestOptions, type Subscription, type SubscriptionStatus, type Summary, type UpdateSubscriptionParams, type WebhookDelivery, type WebhookEndpoint, constructEvent };