@olympio/payment-gateway 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @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
+
+```bash
+npm install @org/payment-gateway
+```
+
+## Uso
+
+```ts
+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: 'maria@exemplo.com',
+  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`.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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
+
+```ts
+// 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
+
+```bash
+npm test        # roda todos os testes unitários e de contrato
+npm run build   # gera os bundles ESM e CJS
+```