@olympio/payment-gateway 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+import Stripe from 'stripe';
+
+/**
+ * Recursos que um gateway pode ou não suportar. Cada adapter declara seu
+ * conjunto; o consumidor checa antes de chamar, evitando erros crus do gateway.
+ */
+declare const Capability: {
+    readonly PIX: "pix";
+    readonly BOLETO: "boleto";
+    readonly CARD: "card";
+    readonly REFUND: "refund";
+    readonly SUBSCRIPTIONS: "subscriptions";
+};
+type Capability = (typeof Capability)[keyof typeof Capability];
+declare function hasCapability(caps: ReadonlySet<Capability>, capability: Capability): boolean;
+
+/**
+ * Value object monetário em unidades mínimas (centavos), evitando erros de
+ * ponto flutuante. Stripe trabalha em centavos; Asaas em decimal — os mappers
+ * de cada adapter convertem para/desta representação única.
+ */
+declare class Money {
+    readonly cents: number;
+    readonly currency: string;
+    private constructor();
+    static fromCents(cents: number, currency: string): Money;
+    static fromDecimal(amount: number, currency: string): Money;
+    toDecimal(): number;
+    equals(other: Money): boolean;
+}
+
+/** Meio de pagamento normalizado entre gateways. */
+type PaymentMethod = 'pix' | 'boleto' | 'card';
+
+type ChargeStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'canceled';
+/** Dados extras de PIX, presentes quando o meio é 'pix'. */
+interface PixDetails {
+    qrCode?: string;
+    copyPaste?: string;
+    expiresAt?: Date;
+}
+/** Dados extras de boleto, presentes quando o meio é 'boleto'. */
+interface BoletoDetails {
+    url?: string;
+    barcode?: string;
+    dueDate?: Date;
+}
+/** Cobrança avulsa normalizada. */
+interface Charge {
+    id: string;
+    status: ChargeStatus;
+    amount: Money;
+    paymentMethod: PaymentMethod;
+    customerId?: string;
+    description?: string;
+    pix?: PixDetails;
+    boleto?: BoletoDetails;
+    createdAt: Date;
+    metadata?: Record<string, string>;
+}
+interface CreateChargeInput {
+    amount: Money;
+    paymentMethod: PaymentMethod;
+    customerId: string;
+    description?: string;
+    /** Token de cartão (quando paymentMethod === 'card'). */
+    cardToken?: string;
+    /** Vencimento (boleto). */
+    dueDate?: Date;
+    /** IP do pagador. Exigido pelo Asaas em cobranças de cartão (anti-fraude). */
+    remoteIp?: string;
+    /** Chave de idempotência para evitar cobranças duplicadas. */
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+interface RefundChargeInput {
+    chargeId: string;
+    /** Estorno parcial; ausente = estorno total. */
+    amount?: Money;
+    idempotencyKey?: string;
+}
+
+/** Cliente normalizado, como representado dentro do gateway. */
+interface Customer {
+    /** Identificador do cliente no gateway. */
+    id: string;
+    name: string;
+    email?: string;
+    /** CPF/CNPJ. Obrigatório em alguns gateways (ex.: Asaas). */
+    taxId?: string;
+    phone?: string;
+    metadata?: Record<string, string>;
+}
+interface CreateCustomerInput {
+    name: string;
+    email?: string;
+    taxId?: string;
+    phone?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+interface UpdateCustomerInput {
+    name?: string;
+    email?: string;
+    taxId?: string;
+    phone?: string;
+    metadata?: Record<string, string>;
+}
+
+/** Gateways suportados. Adicionar um novo gateway começa por aqui. */
+type Provider = "asaas" | "stripe" | "dom";
+
+type SubscriptionStatus = 'active' | 'canceled' | 'past_due';
+type BillingInterval = 'weekly' | 'monthly' | 'yearly';
+/** Assinatura recorrente normalizada. */
+interface Subscription {
+    id: string;
+    status: SubscriptionStatus;
+    customerId: string;
+    amount: Money;
+    interval: BillingInterval;
+    createdAt: Date;
+    metadata?: Record<string, string>;
+}
+interface CreateSubscriptionInput {
+    customerId: string;
+    amount: Money;
+    interval: BillingInterval;
+    paymentMethod: PaymentMethod;
+    /** Token de cartão (quando paymentMethod === 'card'). */
+    cardToken?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, string>;
+}
+
+/**
+ * Evento de webhook normalizado entre gateways. O campo `raw` sempre preserva
+ * o payload original; eventos não reconhecidos viram `type: 'unknown'` em vez
+ * de serem engolidos ou de quebrarem o processamento.
+ */
+type WebhookEvent = {
+    type: 'charge.paid';
+    data: Charge;
+    raw: unknown;
+} | {
+    type: 'charge.failed';
+    data: Charge;
+    raw: unknown;
+} | {
+    type: 'charge.refunded';
+    data: Charge;
+    raw: unknown;
+} | {
+    type: 'subscription.renewed';
+    data: Subscription;
+    raw: unknown;
+} | {
+    type: 'subscription.canceled';
+    data: Subscription;
+    raw: unknown;
+} | {
+    type: 'unknown';
+    data: null;
+    raw: unknown;
+};
+type WebhookEventType = WebhookEvent['type'];
+/** Entrada para verificação + parsing de um webhook recebido. */
+interface WebhookInput {
+    /** Corpo bruto da requisição (string ou Buffer), necessário p/ verificar assinatura. */
+    payload: string | Buffer;
+    headers: Record<string, string>;
+    /** Segredo de verificação (signing secret do Stripe, token do Asaas). */
+    secret: string;
+}
+
+interface CustomerPort {
+    create(input: CreateCustomerInput): Promise<Customer>;
+    get(id: string): Promise<Customer | null>;
+    update(id: string, input: UpdateCustomerInput): Promise<Customer>;
+    delete(id: string): Promise<void>;
+}
+interface ChargePort {
+    create(input: CreateChargeInput): Promise<Charge>;
+    get(id: string): Promise<Charge | null>;
+    cancel(id: string): Promise<Charge>;
+    refund(input: RefundChargeInput): Promise<Charge>;
+}
+interface SubscriptionPort {
+    create(input: CreateSubscriptionInput): Promise<Subscription>;
+    get(id: string): Promise<Subscription | null>;
+    cancel(id: string): Promise<Subscription>;
+}
+interface WebhookPort {
+    /** Verifica a assinatura e normaliza o evento recebido. */
+    verifyAndParse(input: WebhookInput): WebhookEvent;
+}
+/**
+ * Porta principal: contrato comum implementado por todos os adapters.
+ *
+ * `TRaw` é o tipo do client nativo do gateway, exposto pelo escape hatch
+ * `raw()` para recursos exclusivos que o contrato comum não cobre.
+ */
+interface PaymentGateway<TRaw = unknown> {
+    readonly provider: Provider;
+    readonly capabilities: ReadonlySet<Capability>;
+    supports(capability: Capability): boolean;
+    readonly customers: CustomerPort;
+    readonly charges: ChargePort;
+    readonly subscriptions: SubscriptionPort;
+    readonly webhooks: WebhookPort;
+    /** Escape hatch: client nativo do gateway, tipado por adapter. */
+    raw(): TRaw;
+}
+
+interface StripeGatewayConfig {
+    apiKey: string;
+    /** Signing secret para verificar webhooks. */
+    webhookSecret?: string;
+}
+declare class StripeGateway implements PaymentGateway<Stripe> {
+    private readonly config;
+    readonly provider: "stripe";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly client;
+    readonly customers: CustomerPort;
+    readonly charges: ChargePort;
+    readonly subscriptions: SubscriptionPort;
+    readonly webhooks: WebhookPort;
+    constructor(config: StripeGatewayConfig, client?: Stripe);
+    supports(capability: Capability): boolean;
+    raw(): Stripe;
+    private requireMethod;
+    private buildCustomerPort;
+    private buildChargePort;
+    private buildSubscriptionPort;
+    private buildWebhookPort;
+}
+
+/** Erro bruto de uma resposta não-2xx do Asaas, normalizado depois pelo adapter. */
+declare class AsaasApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/**
+ * Transporte HTTP do Asaas. É a dependência injetável do adapter (também o que
+ * `raw()` devolve), o que torna o gateway testável com um fake in-memory.
+ */
+interface AsaasHttpClient {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+interface AsaasHttpConfig {
+    apiKey: string;
+    /** Base da API. Padrão: produção. Use a URL de sandbox em testes/homologação. */
+    baseUrl?: string;
+}
+/** Implementação padrão baseada em `fetch` (Node 18+). */
+declare function createAsaasHttpClient(config: AsaasHttpConfig): AsaasHttpClient;
+
+interface AsaasGatewayConfig extends AsaasHttpConfig {
+    /** Token configurado no Asaas para autenticar webhooks recebidos. */
+    webhookToken?: string;
+}
+declare class AsaasGateway implements PaymentGateway<AsaasHttpClient> {
+    private readonly config;
+    readonly provider: "asaas";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly http;
+    readonly customers: CustomerPort;
+    readonly charges: ChargePort;
+    readonly subscriptions: SubscriptionPort;
+    readonly webhooks: WebhookPort;
+    constructor(config: AsaasGatewayConfig, http?: AsaasHttpClient);
+    supports(capability: Capability): boolean;
+    raw(): AsaasHttpClient;
+    private buildCustomerPort;
+    private buildChargePort;
+    private buildSubscriptionPort;
+    private buildWebhookPort;
+}
+
+interface DomGatewayConfig {
+    apiKey: string;
+    webhookToken?: string;
+    baseUrl?: string;
+}
+
+/**
+ * Configuração discriminada por `provider`. Adicionar um novo gateway começa
+ * por estender esta união e o `switch` em `createGateway`.
+ */
+type GatewayConfig = ({
+    provider: 'stripe';
+} & StripeGatewayConfig) | ({
+    provider: 'asaas';
+} & AsaasGatewayConfig) | ({
+    provider: 'dom';
+} & DomGatewayConfig);
+/** Ponto de entrada: instancia o adapter correto a partir da config. */
+declare function createGateway(config: GatewayConfig): PaymentGateway;
+
+interface GatewayErrorOptions {
+    /** Erro original do gateway/SDK, preservado para diagnóstico. */
+    cause?: unknown;
+    /** Payload/objeto bruto retornado pelo gateway. */
+    raw?: unknown;
+}
+/** Código normalizado de erro, estável entre gateways. */
+type GatewayErrorCode = 'card_declined' | 'authentication' | 'rate_limit' | 'validation' | 'unsupported_capability' | 'gateway_unavailable' | 'unknown';
+/** Base de todos os erros normalizados da lib. */
+declare abstract class GatewayError extends Error {
+    readonly provider: Provider;
+    abstract readonly code: GatewayErrorCode;
+    readonly raw?: unknown;
+    constructor(provider: Provider, message: string, options?: GatewayErrorOptions);
+}
+declare class CardDeclinedError extends GatewayError {
+    readonly code = "card_declined";
+    constructor(provider: Provider, options?: GatewayErrorOptions);
+}
+declare class AuthenticationError extends GatewayError {
+    readonly code = "authentication";
+    constructor(provider: Provider, options?: GatewayErrorOptions);
+}
+declare class RateLimitError extends GatewayError {
+    readonly code = "rate_limit";
+    constructor(provider: Provider, options?: GatewayErrorOptions);
+}
+declare class ValidationError extends GatewayError {
+    readonly code = "validation";
+    constructor(provider: Provider, message: string, options?: GatewayErrorOptions);
+}
+declare class GatewayUnavailableError extends GatewayError {
+    readonly code = "gateway_unavailable";
+    constructor(provider: Provider, options?: GatewayErrorOptions);
+}
+/** Erro genérico para casos não mapeados, preservando o erro original. */
+declare class UnknownGatewayError extends GatewayError {
+    readonly code = "unknown";
+    constructor(provider: Provider, message: string, options?: GatewayErrorOptions);
+}
+/** Lançado ao chamar uma operação que o gateway não suporta. */
+declare class UnsupportedCapabilityError extends GatewayError {
+    readonly capability: Capability;
+    readonly code = "unsupported_capability";
+    constructor(provider: Provider, capability: Capability, options?: GatewayErrorOptions);
+}
+
+export { AsaasApiError, AsaasGateway, type AsaasGatewayConfig, type AsaasHttpClient, type AsaasHttpConfig, AuthenticationError, type BillingInterval, type BoletoDetails, Capability, CardDeclinedError, type Charge, type ChargePort, type ChargeStatus, type CreateChargeInput, type CreateCustomerInput, type CreateSubscriptionInput, type Customer, type CustomerPort, type GatewayConfig, GatewayError, type GatewayErrorCode, type GatewayErrorOptions, GatewayUnavailableError, Money, type PaymentGateway, type PaymentMethod, type PixDetails, type Provider, RateLimitError, type RefundChargeInput, StripeGateway, type StripeGatewayConfig, type Subscription, type SubscriptionPort, type SubscriptionStatus, UnknownGatewayError, UnsupportedCapabilityError, type UpdateCustomerInput, ValidationError, type WebhookEvent, type WebhookEventType, type WebhookInput, type WebhookPort, createAsaasHttpClient, createGateway, hasCapability };