@baruk/core 0.3.0 → 0.4.2

package/dist/billing/provider/asaas.js

@@ -8,6 +8,10 @@ import { AppError } from '@baruk/shared';
  * IMPORTANTE: nenhum outro arquivo do Core importa este adapter diretamente — o
  * acesso é sempre via `resolveBillingProvider('asaas', config)`. Assim, trocar
  * Asaas por Stripe é trocar a string registrada, sem tocar em regra de negócio.
+ *
+ * A credencial define a CONTA que recebe o dinheiro. Quem escolhe a credencial
+ * é `provider-account.ts`, a partir do tenant — este adapter não sabe, e não
+ * deve saber, de quem é a conta que está usando.
  */
 const BILLING_TYPE = {
     pix: 'PIX',
@@ -24,12 +28,14 @@ export class AsaasProvider {
     key = 'asaas';
     apiKey;
     baseUrl;
+    webhookSecret;
     fetchImpl;
     constructor(config) {
         if (!config.apiKey)
             throw new AsaasError('apiKey ausente (configure no Vault).', 500);
         this.apiKey = config.apiKey;
         this.baseUrl = (config.baseUrl ?? 'https://api.asaas.com/v3').replace(/\/$/, '');
+        this.webhookSecret = config.webhookSecret;
         this.fetchImpl = config.fetchImpl ?? fetch;
     }
     async call(path, method, body) {
@@ -44,29 +50,123 @@ export class AsaasProvider {
         }
         return (await res.json());
     }
+    /**
+     * Provisiona (ou reencontra) o pagador na conta do escritório.
+     *
+     * `externalReference` é o id interno do cliente, e a busca por ele vem ANTES
+     * do POST: sem isso, cada emissão criaria um cadastro novo na conta do
+     * escritório, e o histórico do cliente lá dentro viraria uma lista de
+     * homônimos. O mapa local (`payment_customer`) evita a maioria das chamadas;
+     * esta busca é a rede de segurança para quando o mapa e o gateway divergirem.
+     */
+    async ensureCustomer(req) {
+        const found = await this.call(`/customers?externalReference=${encodeURIComponent(req.referenceId)}&limit=1`, 'GET');
+        const existing = found.data?.[0]?.id;
+        if (existing) {
+            // ENCONTRAR NÃO BASTA. Este era o coração da dívida R: o pagador existia
+            // com dados velhos — tipicamente sem CPF/CNPJ — e devolvê-lo calado fazia a
+            // emissão ser recusada para sempre, mesmo depois de o escritório corrigir
+            // a ficha no Office.
+            //
+            // Importa que a correção esteja AQUI, e não só no cache: a transação da
+            // emissão faz rollback quando o gateway recusa, então o mapa local não
+            // persiste e a próxima tentativa cai justamente neste caminho. Se ele
+            // devolvesse sem reconciliar, o sistema gravaria uma impressão digital
+            // afirmando uma sincronização que nunca houve.
+            await this.updateCustomer(existing, req);
+            return { externalId: existing, action: 'reconciled' };
+        }
+        const created = await this.call('/customers', 'POST', customerPayload(req));
+        return { externalId: created.id, action: 'created' };
+    }
+    /**
+     * Atualiza o pagador existente. Mesmo payload da criação, mesmo endpoint com
+     * id — no Asaas, `POST /customers/{id}` é a atualização.
+     *
+     * Sem `externalReference` no corpo: ele é a âncora que liga o pagador ao
+     * cliente do Office, e reescrevê-lo a cada sincronização abriria a chance de
+     * apontar para outro cliente por um erro de chamada.
+     */
+    async updateCustomer(externalId, req) {
+        const { externalReference: _ignored, ...payload } = customerPayload(req);
+        await this.call(`/customers/${encodeURIComponent(externalId)}`, 'POST', payload);
+    }
+    async describeAccount() {
+        const me = await this.call('/myAccount', 'GET');
+        const documentNumber = onlyDigits(me.cpfCnpj) || null;
+        return {
+            // Sem `walletId`/`id`, cai no documento — é o que identifica o TITULAR do
+            // dinheiro, que é o que o guard cross-tenant precisa comparar. Sem este
+            // fallback a referência fica nula, o índice parcial não pega nada, e duas
+            // organizações conseguiriam conectar a mesma conta.
+            reference: me.walletId ?? me.id ?? (documentNumber ? `doc:${documentNumber}` : null),
+            name: me.companyName ?? me.name ?? null,
+            documentNumber,
+        };
+    }
     async createCharge(req) {
-        // Asaas exige um customer; aqui assumimos que o id do cliente Asaas veio no
-        // metadata (provisionamento fora do escopo). O mapeamento demonstra o contrato.
-        const payload = {
-            billingType: BILLING_TYPE[req.method] ?? 'UNDEFINED',
+        if (!req.customerExternalId) {
+            throw new AsaasError('customer não provisionado — chame ensureCustomer antes.', 500);
+        }
+        const method = req.method;
+        const res = await this.call('/payments', 'POST', {
+            customer: req.customerExternalId,
+            billingType: BILLING_TYPE[method] ?? 'UNDEFINED',
             value: req.amount,
             dueDate: req.dueDate,
             description: req.description ?? undefined,
             externalReference: req.referenceId,
-        };
-        const res = await this.call('/payments', 'POST', payload);
+        });
         return {
             externalId: res.id,
             status: mapAsaasStatus(res.status),
-            payment: { boletoUrl: res.bankSlipUrl, invoiceUrl: res.invoiceUrl },
+            payment: await this.instructionsFor(res, method),
             raw: res,
         };
     }
+    async fetchPaymentInstructions(externalId, method) {
+        const res = await this.call(`/payments/${externalId}`, 'GET');
+        return this.instructionsFor(res, method);
+    }
+    /**
+     * O QR Code e a linha digitável vivem em endpoints próprios.
+     *
+     * Eles são buscados no provider, nunca gerados aqui: um BR Code montado por
+     * nós apontaria para uma chave PIX que o gateway não conhece, e o pagamento
+     * cairia fora da cobrança — dinheiro que entra sem baixar nada.
+     *
+     * A falha é tolerada de propósito. Se o QR não vier, o cliente ainda tem a
+     * página de pagamento; derrubar a emissão inteira por causa de um extra seria
+     * trocar uma cobrança incompleta por nenhuma cobrança.
+     */
+    async instructionsFor(res, method) {
+        const out = {
+            invoiceUrl: res.invoiceUrl,
+            boletoUrl: res.bankSlipUrl,
+        };
+        if (method === 'pix') {
+            const qr = await this.call(`/payments/${res.id}/pixQrCode`, 'GET').catch(() => null);
+            if (qr?.payload)
+                out.pixPayload = qr.payload;
+            if (qr?.encodedImage)
+                out.pixQrCodeImage = `data:image/png;base64,${qr.encodedImage}`;
+        }
+        if (method === 'boleto') {
+            const slip = await this.call(`/payments/${res.id}/identificationField`, 'GET').catch(() => null);
+            if (slip?.identificationField)
+                out.identificationField = slip.identificationField;
+        }
+        return out;
+    }
     async cancelCharge(externalId) {
         await this.call(`/payments/${externalId}`, 'DELETE');
     }
     async createSubscription(req) {
-        const cycle = { monthly: 'MONTHLY', quarterly: 'QUARTERLY', yearly: 'YEARLY' };
+        const cycle = {
+            monthly: 'MONTHLY',
+            quarterly: 'QUARTERLY',
+            yearly: 'YEARLY',
+        };
         const res = await this.call('/subscriptions', 'POST', {
             billingType: BILLING_TYPE[req.method] ?? 'UNDEFINED',
             value: req.amount,
@@ -85,24 +185,104 @@ export class AsaasProvider {
     async cancelSubscription(externalId) {
         await this.call(`/subscriptions/${externalId}`, 'DELETE');
     }
+    /**
+     * Autenticação do webhook.
+     *
+     * O Asaas envia o token configurado na fila em `asaas-access-token`. A
+     * comparação é de tempo constante — um `===` sobre segredo vaza, byte a byte,
+     * quanto do prefixo está correto para quem consegue medir o tempo da resposta.
+     *
+     * Sem segredo configurado, reprova. Fail-closed é o único default aceitável
+     * numa rota pública que dá baixa em dinheiro.
+     */
+    verifyWebhook(_payload, headers = {}) {
+        if (!this.webhookSecret)
+            return false;
+        const sent = headers['asaas-access-token'] ?? headers['Asaas-Access-Token'] ?? '';
+        return timingSafeEqual(sent, this.webhookSecret);
+    }
     parseWebhook(payload) {
         const p = payload;
-        const externalId = p.payment?.id ?? null;
+        const base = {
+            eventId: p.id ?? null,
+            externalId: p.payment?.id ?? null,
+            raw: payload,
+        };
         switch (p.event) {
+            // RECEIVED = dinheiro creditado. CONFIRMED = autorizado, ainda não
+            // liquidado (cartão). Os dois viram baixa: para o escritório, a dívida
+            // deixou de ser dele nos dois casos, e esperar a liquidação faria a régua
+            // seguir cobrando alguém que já pagou.
+            // RECEIVED_IN_CASH é a baixa que o escritório dá à mão no painel quando o
+            // cliente pagou fora do gateway. Sem este caso o evento caía em `unknown`
+            // e a régua seguia cobrando quem já tinha pagado — dinheiro que entrou e
+            // que o sistema não enxergava.
             case 'PAYMENT_RECEIVED':
             case 'PAYMENT_CONFIRMED':
-                return { type: 'charge.paid', externalId, paidAt: p.payment?.paymentDate ?? null, raw: payload };
+            case 'PAYMENT_RECEIVED_IN_CASH':
+                return {
+                    ...base,
+                    type: 'charge.paid',
+                    paidAt: p.payment?.paymentDate ?? null,
+                    paidAmount: p.payment?.value ?? null,
+                };
+            // O par do anterior. Reconhecer a baixa manual sem reconhecer o desfazer
+            // trocaria um defeito por outro: a cobrança ficaria paga para sempre por
+            // causa de um clique que o próprio escritório revogou.
+            case 'PAYMENT_RECEIVED_IN_CASH_UNDONE':
+                return { ...base, type: 'charge.settlement_undone' };
+            case 'PAYMENT_CREATED':
+                return { ...base, type: 'charge.created' };
             case 'PAYMENT_OVERDUE':
-                return { type: 'charge.overdue', externalId, raw: payload };
+                return { ...base, type: 'charge.overdue' };
             case 'PAYMENT_DELETED':
-                return { type: 'charge.canceled', externalId, raw: payload };
+                return { ...base, type: 'charge.canceled' };
             case 'PAYMENT_REFUNDED':
-                return { type: 'charge.refunded', externalId, raw: payload };
+            case 'PAYMENT_REVERSED':
+                return { ...base, type: 'charge.refunded' };
+            case 'PAYMENT_CHARGEBACK_REQUESTED':
+            case 'PAYMENT_CHARGEBACK_DISPUTE':
+                return { ...base, type: 'charge.chargeback' };
             default:
-                return { type: 'unknown', externalId, raw: payload };
+                return { ...base, type: 'unknown' };
         }
     }
 }
+/**
+ * Campos cadastrais que o Asaas precisa do pagador.
+ *
+ * Uma função só, usada na criação E na atualização: se as duas montassem o
+ * payload por conta própria, um campo adicionado numa delas passaria a existir
+ * só nos clientes novos — e a diferença apareceria meses depois, como "esse
+ * cliente antigo não recebe e-mail do boleto".
+ *
+ * `notificationDisabled` é reafirmado em toda sincronização de propósito: quem
+ * fala com o cliente é o Office. Se alguém ligar a notificação pelo painel do
+ * gateway, o cliente passaria a receber DUAS cobranças pelo mesmo valor.
+ */
+function customerPayload(req) {
+    return {
+        name: req.name,
+        cpfCnpj: onlyDigits(req.documentNumber),
+        email: req.email ?? undefined,
+        mobilePhone: onlyDigits(req.phone) || undefined,
+        externalReference: req.referenceId,
+        notificationDisabled: true,
+    };
+}
+function onlyDigits(v) {
+    return (v ?? '').replace(/\D/g, '');
+}
+/** Comparação de tempo constante, sem depender de `node:crypto` no Core. */
+function timingSafeEqual(a, b) {
+    // O XOR roda sobre o comprimento do segredo para que a duração não revele o
+    // tamanho do que foi enviado; a diferença de comprimento entra no acumulador.
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < b.length; i++) {
+        diff |= (a.charCodeAt(i) || 0) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
 function mapAsaasStatus(status) {
     switch (status) {
         case 'RECEIVED':

package/dist/billing/provider/asaas.js.map

@@ -1 +1 @@
-{"version":3,"file":"asaas.js","sourceRoot":"","sources":["../../../src/billing/provider/asaas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"asaas.js","sourceRoot":"","sources":["../../../src/billing/provider/asaas.ts"],"names":[],"mappings":"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"}

package/dist/billing/provider/manual.js

@@ -18,7 +18,7 @@ export class ManualProvider {
         // No-op — cancelamento é apenas mudança de status interno.
     }
     parseWebhook() {
-        return { type: 'unknown', externalId: null };
+        return { type: 'unknown', eventId: null, externalId: null };
     }
 }
 //# sourceMappingURL=manual.js.map

package/dist/billing/provider/manual.js.map

@@ -1 +1 @@
-{"version":3,"file":"manual.js","sourceRoot":"","sources":["../../../src/billing/provider/manual.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAChB,GAAG,GAAG,QAAQ,CAAC;IAExB,KAAK,CAAC,YAAY,CAAC,GAAkB;QACnC,6EAA6E;QAC7E,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS;SACtE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,2DAA2D;IAC7D,CAAC;IAED,YAAY;QACV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/C,CAAC;CACF"}
+{"version":3,"file":"manual.js","sourceRoot":"","sources":["../../../src/billing/provider/manual.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAChB,GAAG,GAAG,QAAQ,CAAC;IAExB,KAAK,CAAC,YAAY,CAAC,GAAkB;QACnC,6EAA6E;QAC7E,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS;SACtE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,2DAA2D;IAC7D,CAAC;IAED,YAAY;QACV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC9D,CAAC;CACF"}

package/dist/billing/provider/types.d.ts

@@ -19,20 +19,56 @@ export interface ChargeRequest {
         email?: string | null;
         phone?: string | null;
     };
+    /** Id do customer JÁ provisionado no gateway (ver `ensureCustomer`). */
+    customerExternalId?: string | null;
+}
+/**
+ * O que o cliente precisa para pagar.
+ *
+ * Nada aqui é segredo — é justamente o material que vai no e-mail. Mas nada
+ * aqui é opcional por acaso: cada gateway entrega um subconjunto diferente, e o
+ * template tem de saber renderizar o que veio, não o que gostaríamos que viesse.
+ */
+export interface PaymentInstructions {
+    /** Página de pagamento hospedada pelo gateway — o destino do CTA. */
+    invoiceUrl?: string;
+    /** PIX copia-e-cola (BR Code). */
+    pixPayload?: string;
+    /** QR Code do PIX em base64, já como data URI ou payload cru do gateway. */
+    pixQrCodeImage?: string;
+    boletoUrl?: string;
+    /** Linha digitável do boleto. */
+    identificationField?: string;
 }
 export interface ChargeResult {
     /** Id da cobrança no gateway (nulo para provider 'manual'). */
     externalId: string | null;
-    status: 'pending' | 'sent' | 'paid' | 'overdue' | 'canceled' | 'refunded';
+    status: 'pending' | 'sent' | 'paid' | 'overdue' | 'canceled' | 'refunded' | 'reversed';
     /** Dados não sensíveis para o cliente pagar (PIX copia-e-cola, url do boleto…). */
-    payment?: {
-        pixPayload?: string;
-        pixQrCodeImage?: string;
-        boletoUrl?: string;
-        invoiceUrl?: string;
-    };
+    payment?: PaymentInstructions;
     raw?: unknown;
 }
+/** Dados do pagador, para provisionar/reaproveitar o customer do gateway. */
+/**
+ * O que aconteceu com o pagador no gateway.
+ *
+ * A forma rica é opcional — devolver só a string continua válido — porque um
+ * adapter que não saiba distinguir não deve ser obrigado a inventar. Quem sabe,
+ * informa, e a trilha deixa de registrar "criado" para um pagador que já existia
+ * e acabou de ser corrigido.
+ */
+export interface EnsureCustomerResult {
+    externalId: string;
+    action: 'created' | 'reconciled';
+}
+export interface CustomerRequest {
+    name: string;
+    documentNumber?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    /** Id interno do cliente — vira `externalReference` do lado do gateway. */
+    referenceId: string;
+}
 export interface SubscriptionRequest {
     referenceId: string;
     amount: number;
@@ -50,20 +86,91 @@ export interface SubscriptionResult {
 }
 /** Evento normalizado a partir de um webhook do gateway. */
 export interface WebhookEvent {
-    type: 'charge.paid' | 'charge.overdue' | 'charge.canceled' | 'charge.refunded' | 'unknown';
+    type: 'charge.created' | 'charge.paid' | 'charge.overdue' | 'charge.canceled' | 'charge.refunded' | 'charge.chargeback'
+    /**
+     * A baixa registrada foi DESFEITA na origem — o caso do recebimento em
+     * dinheiro informado à mão e depois cancelado no painel.
+     *
+     * Não é estorno: nesse caso o dinheiro nunca chegou. Manter os dois tipos
+     * separados importa porque a mensagem que o escritório lê é diferente, e
+     * chamar de "estornado" o que nunca foi pago seria mentir na tela.
+     */
+     | 'charge.settlement_undone' | 'unknown';
+    /**
+     * Id do EVENTO no gateway — a chave de deduplicação.
+     *
+     * Não confundir com `externalId`, que é o id da cobrança: o gateway reenvia o
+     * mesmo evento até receber 200, e reenvia eventos DIFERENTES sobre a mesma
+     * cobrança. Deduplicar pela cobrança perderia o segundo evento legítimo.
+     */
+    eventId: string | null;
     externalId: string | null;
     paidAt?: string | null;
+    /** Valor efetivamente creditado, quando o gateway informa. */
+    paidAmount?: number | null;
     raw?: unknown;
 }
+/**
+ * Identidade da conta no gateway, para provar de quem é o dinheiro.
+ *
+ * Só campos que o titular da conta já conhece — nome, documento, id. Nenhum
+ * deles é segredo; o segredo é a chave que os revelou, e ela não sai daqui.
+ */
+export interface ProviderAccountIdentity {
+    /** Id da conta no gateway, quando exposto. Vira `account_reference`. */
+    reference: string | null;
+    name: string | null;
+    /** CPF/CNPJ apenas em dígitos. Usado para comparar titularidade. */
+    documentNumber: string | null;
+}
 export interface BillingProvider {
     /** Identificador estável do adapter — casa com `charge.provider`. */
     readonly key: string;
+    /**
+     * Diz de quem é a conta que esta credencial abre.
+     *
+     * Existe para uma pergunta só: a chave que estão conectando pertence mesmo ao
+     * escritório certo? Confiar no nome da variável é como cinco chaves chamadas
+     * `ASAAS_<produto>_API_KEY` acabaram todas na mesma conta.
+     */
+    describeAccount?(): Promise<ProviderAccountIdentity>;
+    /**
+     * Garante um customer no gateway e devolve o id dele.
+     *
+     * Gateway nenhum aceita cobrança sem pagador. Sem este passo, `createCharge`
+     * falha na primeira chamada real — foi exatamente o que aconteceu com a
+     * primeira versão deste adapter, que montava o payload sem `customer`.
+     */
+    ensureCustomer?(req: CustomerRequest): Promise<string | EnsureCustomerResult>;
+    /**
+     * Atualiza um pagador JÁ existente no gateway com os dados atuais do Office.
+     *
+     * Separado de `ensureCustomer` porque as duas respondem perguntas diferentes:
+     * aquela garante que o pagador EXISTE, esta garante que ele está CORRETO. Sem
+     * a segunda, corrigir o CPF/CNPJ no Office não chega ao provedor, e o cliente
+     * corrigido no lugar certo continua impossível de cobrar.
+     *
+     * Opcional como o resto do contrato: um provider que não permita atualização
+     * simplesmente não a implementa, e a reconciliação é reportada como
+     * indisponível em vez de fingida.
+     */
+    updateCustomer?(externalId: string, req: CustomerRequest): Promise<void>;
     createCharge(req: ChargeRequest): Promise<ChargeResult>;
+    /** Busca as instruções de pagamento de uma cobrança já criada. */
+    fetchPaymentInstructions?(externalId: string, method: BillingMethod): Promise<PaymentInstructions>;
     cancelCharge(externalId: string): Promise<void>;
     createSubscription?(req: SubscriptionRequest): Promise<SubscriptionResult>;
     cancelSubscription?(externalId: string): Promise<void>;
     /** Traduz o corpo bruto de um webhook para o evento normalizado. */
     parseWebhook(payload: unknown, headers?: Record<string, string>): WebhookEvent;
+    /**
+     * Autentica o webhook. `false` reprova a requisição.
+     *
+     * Separado de `parseWebhook` de propósito: parsear é barato e não decide
+     * nada; autenticar é a fronteira de segurança, e uma rota pública que só
+     * parseia é uma rota que aceita evento forjado.
+     */
+    verifyWebhook?(payload: unknown, headers?: Record<string, string>): boolean;
 }
 /** Config passada ao construir um adapter (segredos vêm do Vault, nunca hardcoded). */
 export interface ProviderConfig {

package/dist/billing/provider/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/billing/provider/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/billing/provider/types.ts"],"names":[],"mappings":"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"}

package/dist/billing/provider-account.d.ts

@@ -0,0 +1,89 @@
+import type { Tx } from '../db/client.js';
+import type { Keyring } from '../vault/crypto.js';
+import type { BillingProvider } from './provider/types.js';
+/**
+ * A conta que recebe o dinheiro.
+ *
+ * Esta é a peça que o comentário do M1 em `routes/billing.ts` apontava como
+ * faltante, e é a fronteira financeira do produto: **o dinheiro de uma cobrança
+ * pertence ao escritório que cobrou**, não à Baruk. A conta sai de
+ * `payment_provider_account`, que é por tenant; a credencial sai do Vault, por
+ * referência. Em nenhum ponto o Core carrega uma credencial de plataforma para
+ * emitir cobrança de tenant — se a conta não existe, não há emissão.
+ *
+ * Isso é diferente do Billing SaaS (`subscription-billing/`), onde a credencial
+ * é da plataforma porque quem cobra é a Baruk. Os dois caminhos coexistem e não
+ * se cruzam: um resolve credencial daqui, o outro da config do serviço.
+ */
+export interface ProviderAccount {
+    id: string;
+    provider: string;
+    accountReference: string | null;
+    environment: 'sandbox' | 'live';
+    /** A conta que o escritório OPERA. Exatamente uma por (tenant, provider). */
+    isPrimary: boolean;
+    capabilities: string[];
+    credentialRef: string | null;
+    webhookCredentialRef: string | null;
+    status: string;
+}
+/** Conta ativa do tenant. `null` quando o escritório ainda não conectou nenhuma. */
+/**
+ * A conta pela qual o escritório OPERA.
+ *
+ * Antes era "a primeira conta ativa por data de criação". Isso funcionava
+ * enquanto só podia existir uma; com sandbox e produção coexistindo, viraria a
+ * pior forma de escolher para onde vai o dinheiro — implícita e dependente de
+ * ordem de inserção.
+ *
+ * Agora a escolha é uma MARCA explícita, e o banco garante que só há uma:
+ * `payment_provider_account_primary_uq`. Sem `LIMIT`, de propósito — se algum
+ * dia houvesse duas, o certo é o erro aparecer, não o sistema escolher sozinho.
+ */
+export declare function getActiveProviderAccount(tx: Tx): Promise<ProviderAccount | null>;
+/** Todas as contas vivas do escritório — o laboratório e a operação. */
+export declare function listProviderAccounts(tx: Tx): Promise<ProviderAccount[]>;
+/**
+ * Conta ativa de um AMBIENTE específico.
+ *
+ * Existe para quem sabe o que quer — um ensaio pede `sandbox` mesmo que a
+ * operação já esteja em produção. Nunca cai em outro ambiente por falta do
+ * pedido: sem conta naquele ambiente, devolve nulo.
+ */
+export declare function getProviderAccountByEnvironment(tx: Tx, environment: 'sandbox' | 'live'): Promise<ProviderAccount | null>;
+/**
+ * Promove uma conta a operacional — o ato de "entrar em produção".
+ *
+ * Explícito e reversível, em vez de efeito colateral de revogar o laboratório.
+ * A despromoção da anterior acontece na MESMA transação: entre um UPDATE e o
+ * outro existiria um instante com duas contas operacionais, e é justamente
+ * nesse instante que uma emissão escolheria errado.
+ */
+export declare function setPrimaryProviderAccount(tx: Tx, id: string): Promise<ProviderAccount>;
+/** Conta por id — usada pelo webhook, que descobre o tenant pela URL. */
+export declare function getProviderAccountById(tx: Tx, id: string): Promise<ProviderAccount | null>;
+/**
+ * Base do gateway para um par (provider, ambiente).
+ *
+ * Exportada porque a CONEXÃO da conta também precisa dela, e uma segunda cópia
+ * divergiria: foi assim que uma chave de sandbox chegou a ser validada contra
+ * produção — o adapter caía no default `live` e devolvia 401 com a credencial
+ * correta na mão.
+ */
+export declare function providerBaseUrl(provider: string, environment: string): string | undefined;
+export interface ResolvedProvider {
+    account: ProviderAccount;
+    provider: BillingProvider;
+}
+/**
+ * Monta o adapter já apontado para a conta do tenant.
+ *
+ * `revealSecret` é a única forma de a credencial sair do Vault, e ela sai
+ * direto para dentro do adapter — não é devolvida, logada nem guardada em
+ * variável de módulo.
+ */
+export declare function resolveProviderForTenant(tx: Tx, keyring: Keyring, tenantId: string, opts?: {
+    account?: ProviderAccount;
+    fetchImpl?: typeof fetch;
+}): Promise<ResolvedProvider | null>;
+//# sourceMappingURL=provider-account.d.ts.map

package/dist/billing/provider-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-account.d.ts","sourceRoot":"","sources":["../../src/billing/provider-account.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,SAAS,GAAG,MAAM,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AA4BD,oFAAoF;AACpF;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQtF;AAED,wEAAwE;AACxE,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAS7E;AAED;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,SAAS,GAAG,MAAM,GAC9B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQjC;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAkB5F;AAED,yEAAyE;AACzE,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAOhG;AAgBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzF;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,eAAe,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACjE,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA8BlC"}