@baruk/core 0.3.1 → 0.5.0

package/dist/billing/provider-account.js

@@ -0,0 +1,217 @@
+import { ConflictError, NotFoundError, ValidationError } from '@baruk/shared';
+import { assertLiveProviderAllowed, readLiveRuntime } from './live-guard.js';
+import { revealSecret } from '../vault/repository.js';
+import { resolveBillingProvider } from './provider/registry.js';
+const toAccount = (r) => ({
+    id: r.id,
+    provider: r.provider,
+    accountReference: r.account_reference,
+    environment: r.environment,
+    isPrimary: r.is_primary ?? false,
+    capabilities: Array.isArray(r.supported_capabilities)
+        ? r.supported_capabilities
+        : [],
+    credentialRef: r.credential_ref,
+    webhookCredentialRef: r.webhook_credential_ref,
+    status: r.status,
+});
+/** 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 async function getActiveProviderAccount(tx) {
+    const rows = await tx `
+    SELECT id, provider, account_reference, environment, supported_capabilities,
+           credential_ref, webhook_credential_ref, status, is_primary
+    FROM payment_provider_account
+    WHERE status = 'active' AND is_primary
+  `;
+    // O comentário acima prometia que duas contas fariam o erro aparecer. Não
+    // fazia: `rows[0]` escolhia a primeira em silêncio. A unicidade do índice é
+    // por (tenant, provider), então dois PROVEDORES primários — asaas e outro —
+    // cabem na mesma consulta, e a escolha voltaria a ser implícita.
+    //
+    // Uma promessa que o código não cumpre é pior que promessa nenhuma: alguém
+    // lê o comentário e para de verificar.
+    if (rows.length > 1)
+        throw new AmbiguousProviderAccount('primária', rows.length);
+    return rows[0] ? toAccount(rows[0]) : null;
+}
+/** Todas as contas vivas do escritório — o laboratório e a operação. */
+export async function listProviderAccounts(tx) {
+    const rows = await tx `
+    SELECT id, provider, account_reference, environment, supported_capabilities,
+           credential_ref, webhook_credential_ref, status, is_primary
+    FROM payment_provider_account
+    WHERE status <> 'revoked'
+    ORDER BY environment, created_at
+  `;
+    return rows.map(toAccount);
+}
+/**
+ * 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 async function getProviderAccountByEnvironment(tx, environment) {
+    const rows = await tx `
+    SELECT id, provider, account_reference, environment, supported_capabilities,
+           credential_ref, webhook_credential_ref, status, is_primary
+    FROM payment_provider_account
+    WHERE status = 'active' AND environment = ${environment}
+  `;
+    // Não há índice único por ambiente — duas contas `live` ativas são possíveis
+    // hoje. Escolher a primeira seria decidir por ordem de retorno para onde vai
+    // o dinheiro. Falhar aqui obriga alguém a resolver a duplicidade.
+    if (rows.length > 1)
+        throw new AmbiguousProviderAccount(environment, rows.length);
+    return rows[0] ? toAccount(rows[0]) : 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 async function setPrimaryProviderAccount(tx, id) {
+    const alvo = await tx `
+    SELECT provider FROM payment_provider_account
+     WHERE id = ${id} AND status = 'active'
+  `;
+    if (!alvo[0])
+        throw new NotFoundError('Conta de pagamento ativa não encontrada');
+    await tx `
+    UPDATE payment_provider_account SET is_primary = false, updated_at = now()
+     WHERE provider = ${alvo[0].provider} AND is_primary AND status <> 'revoked'
+  `;
+    await tx `
+    UPDATE payment_provider_account SET is_primary = true, updated_at = now()
+     WHERE id = ${id}
+  `;
+    const conta = await getProviderAccountById(tx, id);
+    if (!conta)
+        throw new NotFoundError('Conta de pagamento não encontrada');
+    return conta;
+}
+/**
+ * Conta por id, obrigatória e utilizável.
+ *
+ * Fail-closed de propósito: quem pede por id sabe qual conta quer, e cair na
+ * primária porque aquela sumiu seria trocar a conta sem avisar — justamente o
+ * que esta fase existe para impedir.
+ */
+export async function requireProviderAccountById(tx, id) {
+    const conta = await getProviderAccountById(tx, id);
+    if (!conta) {
+        throw new NotFoundError('A conta de pagamento que emitiu esta cobrança não existe mais.');
+    }
+    if (conta.status === 'revoked') {
+        throw new ConflictError('A conta de pagamento que emitiu esta cobrança foi revogada — não dá para operar por ela.', { code: 'PROVIDER_ACCOUNT_REVOKED' });
+    }
+    return conta;
+}
+/** Conta por id — usada pelo webhook, que descobre o tenant pela URL. */
+export async function getProviderAccountById(tx, id) {
+    const rows = await tx `
+    SELECT id, provider, account_reference, environment, supported_capabilities,
+           credential_ref, webhook_credential_ref, status, is_primary
+    FROM payment_provider_account WHERE id = ${id}
+  `;
+    return rows[0] ? toAccount(rows[0]) : null;
+}
+/**
+ * URL base do gateway conforme o ambiente declarado NA CONTA.
+ *
+ * A escolha não pode vir de env var do processo: dois tenants podem estar em
+ * ambientes diferentes na mesma instância — um escritório em homologação
+ * enquanto outro já cobra de verdade. Ambiente é atributo da conta.
+ */
+const BASE_URL = {
+    asaas: {
+        live: 'https://api.asaas.com/v3',
+        sandbox: 'https://api-sandbox.asaas.com/v3',
+    },
+};
+/**
+ * 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 function providerBaseUrl(provider, environment) {
+    return BASE_URL[provider]?.[environment];
+}
+/**
+ * Mais de uma conta elegível para o mesmo critério.
+ *
+ * Conflito e não erro de validação: o pedido está correto, quem está errado é o
+ * estado — há duas contas onde só pode haver uma. A saída é humana (revogar ou
+ * despromover uma), e por isso a mensagem diz o que fazer.
+ */
+export class AmbiguousProviderAccount extends ConflictError {
+    constructor(criterio, quantas) {
+        super(`Há ${quantas} contas de pagamento ativas para "${criterio}" — o sistema não escolhe ` +
+            'entre elas. Revogue ou despromova as que não devem operar antes de continuar.', { code: 'AMBIGUOUS_PROVIDER_ACCOUNT' });
+    }
+}
+/**
+ * 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 async function resolveProviderForTenant(tx, keyring, tenantId, opts = {}) {
+    const account = opts.account ??
+        (opts.accountId
+            ? await requireProviderAccountById(tx, opts.accountId)
+            : opts.environment
+                ? await getProviderAccountByEnvironment(tx, opts.environment)
+                : await getActiveProviderAccount(tx));
+    if (!account)
+        return null;
+    // Coerência final, independente do caminho: se a operação declarou o
+    // ambiente, a conta resolvida tem de ser dele. Vale inclusive para
+    // `opts.account`, que vem pronto de fora e ninguém mais confere.
+    if (opts.environment && account.environment !== opts.environment) {
+        throw new ConflictError(`A operação exige uma conta de pagamento "${opts.environment}", e a conta resolvida é ` +
+            `"${account.environment}". Nenhuma operação usa a conta do outro ambiente.`, { code: 'PROVIDER_ENVIRONMENT_MISMATCH' });
+    }
+    // Antes de a credencial sair do Vault: uma aplicação que não é produção não
+    // deve nem abrir conexão com a conta live — inclusive para receber webhook.
+    assertLiveProviderAllowed(account.environment, readLiveRuntime(), 'resolve');
+    if (!account.credentialRef) {
+        throw new ValidationError(`A conta de pagamento do escritório não tem credencial associada (provider "${account.provider}").`);
+    }
+    const { secret } = await revealSecret(tx, keyring, tenantId, account.credentialRef);
+    // O token de webhook é opcional na emissão e obrigatório na recepção: dá para
+    // emitir cobrança sem ele, mas a rota pública recusa tudo enquanto faltar.
+    const webhookSecret = account.webhookCredentialRef
+        ? (await revealSecret(tx, keyring, tenantId, account.webhookCredentialRef)).secret
+        : undefined;
+    return {
+        account,
+        provider: resolveBillingProvider(account.provider, {
+            apiKey: secret,
+            baseUrl: providerBaseUrl(account.provider, account.environment),
+            webhookSecret,
+            fetchImpl: opts.fetchImpl,
+        }),
+    };
+}
+//# sourceMappingURL=provider-account.js.map

package/dist/billing/provider-account.js.map

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

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

@@ -0,0 +1,67 @@
+import type { Tx } from '../db/client.js';
+import type { Keyring } from '../vault/crypto.js';
+import type { ProviderAccountIdentity } from './provider/types.js';
+import type { ProviderAccount } from './provider-account.js';
+/**
+ * Conectar a conta de pagamento de um escritório.
+ *
+ * Este é o único caminho pelo qual uma credencial de gateway entra no sistema.
+ * Ele existe para que ninguém precise fazer `INSERT` com segredo na mão — e
+ * para que três verificações aconteçam SEMPRE, não quando alguém lembrar:
+ *
+ * 1. a credencial funciona (é usada de verdade contra o gateway);
+ * 2. a conta que ela abre é **identificada**, e não presumida pelo nome;
+ * 3. essa conta **não pertence a outro tenant** já conectado.
+ *
+ * A terceira é a que impede o pior desfecho possível deste produto: dois
+ * escritórios apontando para a mesma conta, e o dinheiro de um caindo na conta
+ * do outro. Nome de variável nunca provou titularidade — cinco chaves chamadas
+ * `ASAAS_<produto>_API_KEY` acabaram todas na mesma conta da Baruk.
+ */
+export interface ConnectProviderAccountInput {
+    provider: string;
+    /** Credencial de API. Entra, é usada e vai para o Vault — nunca é devolvida. */
+    apiKey: string;
+    /** Token que autentica o webhook. Sem ele a rota de recepção recusa tudo. */
+    webhookToken?: string | null;
+    environment: 'sandbox' | 'live';
+    capabilities?: string[];
+    /** Base do gateway; só para testes apontarem a um servidor local. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ConnectedAccount {
+    account: ProviderAccount;
+    identity: ProviderAccountIdentity;
+}
+/**
+ * Conta que a PLATAFORMA usa para cobrar os próprios assinantes.
+ *
+ * Quando informada, nenhum tenant pode conectar-se a ela. É a proteção contra o
+ * erro mais fácil de cometer: reaproveitar a chave que já estava à mão.
+ */
+export interface PlatformAccountGuard {
+    documentNumber?: string | null;
+    reference?: string | null;
+}
+export declare function connectProviderAccount(tx: Tx, keyring: Keyring, tenantId: string, input: ConnectProviderAccountInput, platform?: PlatformAccountGuard): Promise<ConnectedAccount>;
+/** Revoga a conta. A credencial fica no Vault, marcada — histórico não se apaga. */
+export declare function revokeProviderAccount(tx: Tx, accountId: string): Promise<number>;
+/**
+ * Reconsulta a identidade da conta e atualiza o que estiver defasado.
+ *
+ * Existe por dois motivos concretos, os dois observados na conta da SC:
+ *
+ * - **a referência pode ter nascido nula** (o gateway não expunha id na época),
+ *   e sem ela o guard que impede duas organizações de receberem na mesma conta
+ *   fica inativo — o índice de unicidade é parcial;
+ * - **a credencial pode ter sido revogada do lado do gateway** sem ninguém
+ *   avisar, e `last_validated_at` é a única forma de saber quando foi a última
+ *   vez que ela comprovadamente funcionou.
+ *
+ * Não troca a credencial: só confirma de quem é a conta que ela abre.
+ */
+export declare function revalidateProviderAccount(tx: Tx, keyring: Keyring, tenantId: string, account: ProviderAccount, opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<ProviderAccountIdentity>;
+//# sourceMappingURL=provider-onboarding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-onboarding.d.ts","sourceRoot":"","sources":["../../src/billing/provider-onboarding.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,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,SAAS,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,uBAAuB,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,2BAA2B,EAClC,QAAQ,GAAE,oBAAyB,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAsG3B;AA6GD,oFAAoF;AACpF,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAmClC"}

package/dist/billing/provider-onboarding.js

@@ -0,0 +1,234 @@
+import { randomUUID } from 'node:crypto';
+import { ConflictError, ValidationError } from '@baruk/shared';
+import { createCredential, revealSecret } from '../vault/repository.js';
+import { resolveBillingProvider } from './provider/registry.js';
+import { providerBaseUrl } from './provider-account.js';
+export async function connectProviderAccount(tx, keyring, tenantId, input, platform = {}) {
+    const apiKey = input.apiKey.trim();
+    if (!apiKey)
+        throw new ValidationError('Credencial vazia.');
+    const provider = resolveBillingProvider(input.provider, {
+        apiKey,
+        // A base vem do AMBIENTE declarado, não do default do adapter. Sem isto,
+        // uma chave de sandbox é validada contra produção e volta 401 — o operador
+        // lê "credencial inválida" com a credencial certa na mão.
+        baseUrl: input.baseUrl ?? providerBaseUrl(input.provider, input.environment),
+        fetchImpl: input.fetchImpl,
+    });
+    if (!provider.describeAccount) {
+        throw new ValidationError(`O provider "${input.provider}" não sabe identificar a própria conta — conectar às cegas não é aceitável para dinheiro.`);
+    }
+    // A credencial é EXERCIDA aqui. Guardar sem usar significaria descobrir que
+    // ela não funciona na primeira cobrança de um cliente real.
+    const identity = await provider.describeAccount();
+    assertNotPlatformAccount(identity, platform);
+    // Conta do PRÓPRIO escritório: a RLS deixa ver, então dá para recusar com uma
+    // consulta limpa, sem provocar violação. Só o caso cross-tenant precisa do
+    // banco para ser detectado — e ele vem depois, isolado num savepoint.
+    // Por AMBIENTE, e não por provedor: duas contas do mesmo gateway em ambientes
+    // diferentes não são a mesma conta — têm credencial, endpoint e dinheiro
+    // distintos. Enquanto a checagem era por provedor, ativar produção exigia
+    // revogar o laboratório, e a decisão "vou cobrar de verdade" ficava amarrada a
+    // "vou perder onde ensaio".
+    const jaTem = await tx `
+    SELECT id FROM payment_provider_account
+    WHERE provider = ${input.provider} AND environment = ${input.environment}
+      AND status <> 'revoked' LIMIT 1
+  `;
+    if (jaTem[0]) {
+        throw new ConflictError(`Este escritório já tem uma conta ${input.provider} em ${input.environment}. ` +
+            'Revogue a atual antes de conectar outra neste ambiente.');
+    }
+    // A primeira conta do escritório nasce operacional; as seguintes nascem como
+    // laboratório. Promover é ato explícito — conectar produção não pode, sozinho,
+    // redirecionar o dinheiro.
+    const jaTemPrimaria = await tx `
+    SELECT id FROM payment_provider_account
+    WHERE provider = ${input.provider} AND is_primary AND status <> 'revoked' LIMIT 1
+  `;
+    const nasceOperacional = !jaTemPrimaria[0];
+    // A garantia de que nenhuma outra organização já usa esta conta é do BANCO
+    // (índice único em `provider, account_reference`), não de uma consulta aqui.
+    // Uma consulta não serviria: com RLS FORCE, `WHERE tenant_id <> atual`
+    // devolve sempre zero — a política esconde justamente a linha que a checagem
+    // precisaria encontrar. O guard pareceria proteger sem proteger.
+    const apiRef = await createCredential(tx, keyring, tenantId, {
+        name: credentialName(input.provider, input.environment, 'api'),
+        category: 'api_key',
+        secret: apiKey,
+        provider: input.provider,
+        // O metadata guarda de quem é a conta, para auditoria futura conseguir
+        // responder "esta chave abria qual conta?" sem precisar decifrá-la.
+        metadata: {
+            purpose: 'payment_provider_api_key',
+            accountName: identity.name,
+            accountReference: identity.reference,
+            environment: input.environment,
+        },
+    });
+    const webhookRef = input.webhookToken?.trim()
+        ? await createCredential(tx, keyring, tenantId, {
+            name: credentialName(input.provider, input.environment, 'webhook'),
+            category: 'api_key',
+            secret: input.webhookToken.trim(),
+            provider: input.provider,
+            metadata: { purpose: 'payment_provider_webhook_token', environment: input.environment },
+        })
+        : null;
+    const id = randomUUID();
+    await insertAccount(tx, id, input, identity, apiRef.id, webhookRef?.id ?? null, nasceOperacional);
+    return {
+        identity,
+        account: {
+            id,
+            provider: input.provider,
+            accountReference: identity.reference,
+            environment: input.environment,
+            capabilities: input.capabilities ?? ['pix', 'boleto'],
+            credentialRef: apiRef.id,
+            webhookCredentialRef: webhookRef?.id ?? null,
+            isPrimary: nasceOperacional,
+            status: 'active',
+        },
+    };
+}
+/**
+ * Insere a conta dentro de um SAVEPOINT.
+ *
+ * O savepoint não é zelo excessivo: uma violação de unicidade aborta a
+ * transação inteira, e a partir daí qualquer comando falha — inclusive os que o
+ * driver roda ao desfazer. O erro que chegaria ao usuário seria o do rollback,
+ * não o meu, e a rota devolveria 500 no lugar de uma explicação. Com o
+ * savepoint, só a tentativa de INSERT é desfeita e a mensagem certa sobrevive.
+ *
+ * O que se detecta aqui é o caso **cross-tenant**: a RLS esconde a conta de
+ * outro escritório, então nenhuma consulta encontraria o conflito — só o índice.
+ */
+async function insertAccount(tx, id, input, identity, credentialRef, webhookRef, nasceOperacional) {
+    try {
+        await tx.savepoint(async (sp) => {
+            await sp `
+    INSERT INTO payment_provider_account (
+      id, tenant_id, provider, account_reference, environment,
+      supported_capabilities, status, credential_ref, webhook_credential_ref,
+      last_validated_at, is_primary
+    ) VALUES (
+      ${id},
+      NULLIF(current_setting('app.current_tenant', true), '')::uuid,
+      ${input.provider}, ${identity.reference}, ${input.environment},
+      ${tx.json((input.capabilities ?? ['pix', 'boleto']))},
+      'active', ${credentialRef}, ${webhookRef}, now(), ${nasceOperacional}
+    )
+      RETURNING id
+      `;
+        });
+    }
+    catch (err) {
+        if (constraintOf(err) === 'payment_provider_account_reference_uq') {
+            throw new ConflictError('Esta conta de pagamento já está conectada a outra organização. ' +
+                'Duas organizações não podem receber na mesma conta.');
+        }
+        if (constraintOf(err) === 'payment_provider_account_provider_uq') {
+            throw new ConflictError(`Este escritório já tem uma conta ${input.provider} conectada. Revogue a atual antes de conectar outra.`);
+        }
+        throw err;
+    }
+}
+function constraintOf(err) {
+    const e = err;
+    return e?.constraint_name ?? e?.constraint ?? null;
+}
+/**
+ * Recusa a conta da plataforma.
+ *
+ * Comparação por documento E por referência: o mesmo CNPJ pode ter mais de uma
+ * conta, e a mesma conta pode aparecer com referências diferentes conforme o
+ * endpoint. Bater em qualquer um dos dois basta para recusar — aqui, falso
+ * positivo custa um pedido de esclarecimento, e falso negativo custa o dinheiro
+ * de um escritório caindo na conta da Baruk.
+ */
+function assertNotPlatformAccount(identity, platform) {
+    const mesmoDoc = platform.documentNumber &&
+        identity.documentNumber &&
+        onlyDigits(platform.documentNumber) === onlyDigits(identity.documentNumber);
+    const mesmaRef = platform.reference && identity.reference && platform.reference === identity.reference;
+    if (mesmoDoc || mesmaRef) {
+        throw new ValidationError('Esta credencial abre a conta da plataforma, não a do escritório. ' +
+            'O dinheiro cobrado pelo escritório precisa cair na conta dele — ' +
+            'use uma credencial da conta do próprio escritório.');
+    }
+}
+/**
+ * Nome da credencial no Vault.
+ *
+ * O prefixo é canônico e legível; o sufixo é o que torna o nome **único**. O
+ * Vault exige nome único por tenant, e um nome fixo impediria o caso legítimo
+ * de desconectar uma conta e conectar outra — a credencial antiga continua
+ * existindo, marcada, porque histórico de credencial não se apaga.
+ *
+ * Quem procura por semântica não usa o nome: `provider` e `metadata.purpose`
+ * são os campos indexáveis para isso.
+ */
+function credentialName(provider, environment, kind) {
+    return `baruk-office-${provider}-${environment}-${kind}-${randomUUID().slice(0, 8)}`;
+}
+function onlyDigits(v) {
+    return v.replace(/\D/g, '');
+}
+/** Revoga a conta. A credencial fica no Vault, marcada — histórico não se apaga. */
+export async function revokeProviderAccount(tx, accountId) {
+    const rows = await tx `
+    UPDATE payment_provider_account
+    SET status = 'revoked', revoked_at = now(), updated_at = now()
+    WHERE id = ${accountId} AND status <> 'revoked'
+    RETURNING id
+  `;
+    return rows.length;
+}
+/**
+ * Reconsulta a identidade da conta e atualiza o que estiver defasado.
+ *
+ * Existe por dois motivos concretos, os dois observados na conta da SC:
+ *
+ * - **a referência pode ter nascido nula** (o gateway não expunha id na época),
+ *   e sem ela o guard que impede duas organizações de receberem na mesma conta
+ *   fica inativo — o índice de unicidade é parcial;
+ * - **a credencial pode ter sido revogada do lado do gateway** sem ninguém
+ *   avisar, e `last_validated_at` é a única forma de saber quando foi a última
+ *   vez que ela comprovadamente funcionou.
+ *
+ * Não troca a credencial: só confirma de quem é a conta que ela abre.
+ */
+export async function revalidateProviderAccount(tx, keyring, tenantId, account, opts = {}) {
+    if (!account.credentialRef) {
+        throw new ValidationError('A conta não tem credencial associada.');
+    }
+    const { secret } = await revealSecret(tx, keyring, tenantId, account.credentialRef);
+    const provider = resolveBillingProvider(account.provider, {
+        apiKey: secret,
+        baseUrl: providerBaseUrl(account.provider, account.environment),
+        fetchImpl: opts.fetchImpl,
+    });
+    if (!provider.describeAccount) {
+        throw new ValidationError(`O provider "${account.provider}" não sabe identificar a própria conta.`);
+    }
+    const identity = await provider.describeAccount();
+    // A referência só é gravada quando falta. Sobrescrever uma referência
+    // existente com outra silenciosamente mudaria a identidade da conta que já
+    // está recebendo dinheiro — se divergir, é caso para o humano olhar.
+    if (!account.accountReference && identity.reference) {
+        await tx `
+      UPDATE payment_provider_account
+      SET account_reference = ${identity.reference}, last_validated_at = now(), updated_at = now()
+      WHERE id = ${account.id}
+    `;
+    }
+    else {
+        await tx `
+      UPDATE payment_provider_account
+      SET last_validated_at = now(), updated_at = now() WHERE id = ${account.id}
+    `;
+    }
+    return identity;
+}
+//# sourceMappingURL=provider-onboarding.js.map

package/dist/billing/provider-onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-onboarding.js","sourceRoot":"","sources":["../../src/billing/provider-onboarding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAG/D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiDxD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAM,EACN,OAAgB,EAChB,QAAgB,EAChB,KAAkC,EAClC,WAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,eAAe,CAAC,mBAAmB,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,CAAC,QAAQ,EAAE;QACtD,MAAM;QACN,yEAAyE;QACzE,2EAA2E;QAC3E,0DAA0D;QAC1D,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,eAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC;QAC5E,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC9B,MAAM,IAAI,eAAe,CACvB,eAAe,KAAK,CAAC,QAAQ,2FAA2F,CACzH,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAC;IAElD,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAE7C,8EAA8E;IAC9E,2EAA2E;IAC3E,sEAAsE;IACtE,8EAA8E;IAC9E,yEAAyE;IACzE,0EAA0E;IAC1E,+EAA+E;IAC/E,4BAA4B;IAC5B,MAAM,KAAK,GAAG,MAAM,EAAE,CAAkB;;uBAEnB,KAAK,CAAC,QAAQ,sBAAsB,KAAK,CAAC,WAAW;;GAEzE,CAAC;IACF,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CACrB,oCAAoC,KAAK,CAAC,QAAQ,OAAO,KAAK,CAAC,WAAW,IAAI;YAC5E,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,2BAA2B;IAC3B,MAAM,aAAa,GAAG,MAAM,EAAE,CAAkB;;uBAE3B,KAAK,CAAC,QAAQ;GAClC,CAAC;IACF,MAAM,gBAAgB,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAE3C,2EAA2E;IAC3E,6EAA6E;IAC7E,uEAAuE;IACvE,6EAA6E;IAC7E,iEAAiE;IAEjE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;QAC3D,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC;QAC9D,QAAQ,EAAE,SAAS;QACnB,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,uEAAuE;QACvE,oEAAoE;QACpE,QAAQ,EAAE;YACR,OAAO,EAAE,0BAA0B;YACnC,WAAW,EAAE,QAAQ,CAAC,IAAI;YAC1B,gBAAgB,EAAE,QAAQ,CAAC,SAAS;YACpC,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B;KACF,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE;QAC3C,CAAC,CAAC,MAAM,gBAAgB,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;YAC5C,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,CAAC;YAClE,QAAQ,EAAE,SAAS;YACnB,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE;YACjC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,EAAE,OAAO,EAAE,gCAAgC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE;SACxF,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC;IAET,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;IACxB,MAAM,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAElG,OAAO;QACL,QAAQ;QACR,OAAO,EAAE;YACP,EAAE;YACF,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,gBAAgB,EAAE,QAAQ,CAAC,SAAS;YACpC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC;YACrD,aAAa,EAAE,MAAM,CAAC,EAAE;YACxB,oBAAoB,EAAE,UAAU,EAAE,EAAE,IAAI,IAAI;YAC5C,SAAS,EAAE,gBAAgB;YAC3B,MAAM,EAAE,QAAQ;SACjB;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,aAAa,CAC1B,EAAM,EACN,EAAU,EACV,KAAkC,EAClC,QAAiC,EACjC,aAAqB,EACrB,UAAyB,EACzB,gBAAyB;IAEzB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YAC9B,MAAM,EAAE,CAAkB;;;;;;QAMxB,EAAE;;QAEF,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,SAAS,KAAK,KAAK,CAAC,WAAW;QAC3D,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAU,CAAC;kBACjD,aAAa,KAAK,UAAU,YAAY,gBAAgB;;;OAGnE,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,uCAAuC,EAAE,CAAC;YAClE,MAAM,IAAI,aAAa,CACrB,iEAAiE;gBAC/D,qDAAqD,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,sCAAsC,EAAE,CAAC;YACjE,MAAM,IAAI,aAAa,CACrB,oCAAoC,KAAK,CAAC,QAAQ,sDAAsD,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,MAAM,CAAC,GAAG,GAAwD,CAAC;IACnE,OAAO,CAAC,EAAE,eAAe,IAAI,CAAC,EAAE,UAAU,IAAI,IAAI,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,wBAAwB,CAC/B,QAAiC,EACjC,QAA8B;IAE9B,MAAM,QAAQ,GACZ,QAAQ,CAAC,cAAc;QACvB,QAAQ,CAAC,cAAc;QACvB,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC9E,MAAM,QAAQ,GACZ,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,KAAK,QAAQ,CAAC,SAAS,CAAC;IAExF,IAAI,QAAQ,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CACvB,mEAAmE;YACjE,kEAAkE;YAClE,oDAAoD,CACvD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,QAAgB,EAAE,WAAmB,EAAE,IAAuB;IACpF,OAAO,gBAAgB,QAAQ,IAAI,WAAW,IAAI,IAAI,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACvF,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,EAAM,EAAE,SAAiB;IACnE,MAAM,IAAI,GAAG,MAAM,EAAE,CAAkB;;;iBAGxB,SAAS;;GAEvB,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,EAAM,EACN,OAAgB,EAChB,QAAgB,EAChB,OAAwB,EACxB,OAAqC,EAAE;IAEvC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,eAAe,CAAC,uCAAuC,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACpF,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,QAAQ,EAAE;QACxD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,WAAW,CAAC;QAC/D,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC9B,MAAM,IAAI,eAAe,CACvB,eAAe,OAAO,CAAC,QAAQ,yCAAyC,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAC;IAElD,sEAAsE;IACtE,2EAA2E;IAC3E,qEAAqE;IACrE,IAAI,CAAC,OAAO,CAAC,gBAAgB,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACpD,MAAM,EAAE,CAAA;;gCAEoB,QAAQ,CAAC,SAAS;mBAC/B,OAAO,CAAC,EAAE;KACxB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,CAAA;;qEAEyD,OAAO,CAAC,EAAE;KAC1E,CAAC;IACJ,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/billing/receivable.d.ts

@@ -42,7 +42,11 @@ export interface ReceivableItemRecord {
     serviceItemRef: string | null;
     createdAt: string;
 }
-export type PaymentStatus = 'detected' | 'confirmed' | 'refunded';
+export type PaymentStatus = 'detected' | 'confirmed'
+/** O dinheiro entrou e voltou ao pagador. */
+ | 'refunded'
+/** O dinheiro nunca entrou: o registro de liquidação foi anulado na origem. */
+ | 'reversed';
 export interface PaymentRecord {
     id: string;
     receivableId: string;

package/dist/billing/receivable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receivable.d.ts","sourceRoot":"","sources":["../../src/billing/receivable.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"receivable.d.ts","sourceRoot":"","sources":["../../src/billing/receivable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,gBAAgB,GAC1B,MAAM,GAAG,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,cAAc,GAAG,aAAa,CAAC;AAE/F,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,WAAW;AACb,6CAA6C;GAC3C,UAAU;AACZ,+EAA+E;GAC7E,UAAU,CAAC;AAEf,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,MAAM,CAAC;AAC5D,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,UAAU,GAAG,oBAAoB,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,0BAA0B,CAAC;IACxC,qBAAqB,EAAE,aAAa,EAAE,CAAC;IACvC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,oFAAoF;IACpF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/billing/reconcile.d.ts

@@ -0,0 +1,58 @@
+import type { Tx } from '../db/client.js';
+import type { WebhookEvent } from './provider/types.js';
+/**
+ * Reconciliação — o webhook do gateway virando baixa no recebível.
+ *
+ * A rota que chama isto é pública. Toda a defesa mora aqui e no adapter:
+ * autenticação (adapter), deduplicação (esta função) e limite de efeito (só
+ * mexe no recebível apontado pela cobrança que o evento cita).
+ *
+ * Regra que atravessa o arquivo: **evento repetido não pode repetir efeito.**
+ * O gateway reenvia até receber 200, e vai reenviar depois de um timeout nosso
+ * mesmo tendo nós processado — do lado dele, a entrega falhou.
+ */
+export type ReconcileOutcome = 'duplicate' | 'charge_not_found' | 'already_paid' | 'paid' | 'refunded' | 'canceled' | 'overdue'
+/**
+ * O evento contradiz a baixa que já está registrada, e nenhuma máquina deve
+ * decidir sozinha o que fazer. Marca para o humano e para.
+ */
+ | 'needs_review'
+/** A liquidação foi anulada na origem: o saldo voltou a existir. */
+ | 'reversed'
+/** Nada havia para anular — evento repetido, ou anulação de algo nunca pago. */
+ | 'already_reversed' | 'ignored';
+export interface ReconcileResult {
+    outcome: ReconcileOutcome;
+    receivableId: string | null;
+    chargeId: string | null;
+}
+/**
+ * Grava o evento e diz se ele é novo.
+ *
+ * O INSERT é a trava: quem consegue inserir processa, quem colide já foi
+ * processado por outro. Fazer `SELECT` antes e `INSERT` depois deixaria uma
+ * janela entre os dois — e webhook duplicado chega em rajada, exatamente dentro
+ * dessa janela.
+ */
+export declare function recordWebhookEvent(tx: Tx, input: {
+    tenantId: string | null;
+    providerAccountId: string | null;
+    provider: string;
+    eventId: string;
+    eventType: string;
+    payload: unknown;
+}): Promise<{
+    id: string;
+    isNew: boolean;
+}>;
+export declare function markWebhookProcessed(tx: Tx, id: string, status: 'processed' | 'ignored' | 'failed'): Promise<void>;
+/**
+ * Aplica o evento normalizado ao recebível.
+ *
+ * Chamada DEPOIS de `recordWebhookEvent` ter dito que o evento é novo. Ainda
+ * assim confere o estado do recebível antes de baixar: dois eventos distintos
+ * (`CONFIRMED` e `RECEIVED`) descrevem o mesmo pagamento, passam os dois pelo
+ * dedup por serem eventos diferentes, e baixariam duas vezes o mesmo dinheiro.
+ */
+export declare function applyWebhookEvent(tx: Tx, event: WebhookEvent): Promise<ReconcileResult>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/billing/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/billing/reconcile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAE1C,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,kBAAkB,GAClB,cAAc,GACd,MAAM,GACN,UAAU,GACV,UAAU,GACV,SAAS;AACX;;;GAGG;GACD,cAAc;AAChB,oEAAoE;GAClE,UAAU;AACZ,gFAAgF;GAC9E,kBAAkB,GAClB,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAazC;AAED,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,EAAE,EACN,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GACzC,OAAO,CAAC,IAAI,CAAC,CAIf;AAUD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CA0D7F"}