@org/payment-gateway

Camada de infraestrutura para gateways de pagamento (Asaas, Stripe e DOM Pagamentos), com contrato comum, capabilities declaradas, escape hatch tipado, webhooks e erros normalizados.

A lib não contém regra de negócio — ela só fala com o gateway e normaliza dados/eventos/erros. A orquestração e as regras de cada cliente ficam na sua aplicação. Em termos hexagonais: a lib é a porta + os adapters de saída; o core de aplicação é seu.

Instalação

npm install @org/payment-gateway

Uso

import { createGateway, Capability, Money } from '@org/payment-gateway';

const gateway = createGateway({ provider: 'dom', apiKey: process.env.DOM_KEY! });
// ou: createGateway({ provider: 'asaas', apiKey: process.env.ASAAS_KEY! });
// ou: createGateway({ provider: 'stripe', apiKey: process.env.STRIPE_KEY! });

const customer = await gateway.customers.create({
  name: 'Maria Silva',
  email: '[email protected]',
  taxId: '12345678900', // CPF/CNPJ
});

const charge = await gateway.charges.create({
  amount: Money.fromDecimal(199.9, 'BRL'),
  paymentMethod: 'pix',
  customerId: customer.id,
  idempotencyKey: 'pedido-42',
});

console.log(charge.status, charge.amount.cents); // 'pending' 19990

Money é sempre em unidades mínimas (centavos). Use Money.fromDecimal / Money.fromCents e toDecimal() — os adapters cuidam da conversão automática para o formato esperado por cada API (ex: DOM e Asaas em Reais, Stripe em centavos).

Capabilities

Cada gateway declara o que suporta. Cheque antes de chamar; chamar algo não suportado lança UnsupportedCapabilityError.

if (gateway.supports(Capability.PIX)) {
  // ...
}

| Capability | Asaas | Stripe | DOM | | --------------- | :---: | :----: | :-: | | CARD | ✅ | ✅ | ✅ | | PIX | ✅ | ❌ | ✅ | | BOLETO | ✅ | ❌ | ✅ | | REFUND | ✅ | ✅ | ✅ | | SUBSCRIPTIONS | ✅ | ✅ | ❌ |

Escape hatch

Para recursos exclusivos que o contrato comum não cobre, raw() devolve o client nativo, tipado por adapter.

import { StripeGateway } from '@org/payment-gateway';

const stripe = new StripeGateway({ apiKey: process.env.STRIPE_KEY! });
const balance = await stripe.raw().balance.retrieve(); // client `Stripe` nativo

Webhooks

verifyAndParse verifica a assinatura e devolve um WebhookEvent normalizado.

const event = gateway.webhooks.verifyAndParse({
  payload: rawRequestBody,
  headers: req.headers,
  secret: process.env.WEBHOOK_SECRET!,
});

switch (event.type) {
  case 'charge.paid':
    // event.data é um Charge normalizado
    break;
}

Configuração por gateway

// DOM Pagamentos
createGateway({ 
  provider: 'dom', 
  apiKey, 
  baseUrl, // Opcional: use URL de homologação em dev
  webhookToken 
});

// Stripe
createGateway({ provider: 'stripe', apiKey, webhookSecret });

// Asaas
createGateway({ provider: 'asaas', apiKey, baseUrl, webhookToken });

Desenvolvimento

npm test        # roda todos os testes unitários e de contrato
npm run build   # gera os bundles ESM e CJS