@baruk/core 0.3.0 → 0.4.2

package/dist/billing/payment-rail.d.ts

@@ -0,0 +1,118 @@
+import type { Tx } from '../db/client.js';
+import type { PaymentInstructions } from './provider/types.js';
+import type { BillingMethod, BillingProvider } from './provider/types.js';
+import type { ProviderAccount } from './provider-account.js';
+/**
+ * Payment Rail — do recebível interno até a cobrança pagável.
+ *
+ * O domínio continua falando de `receivable`; quem conhece gateway é o adapter.
+ * Este módulo é a costura entre os dois, e o lugar onde mora a idempotência.
+ *
+ * Nada aqui é específico de Asaas. Trocar de provider é trocar o adapter
+ * registrado — o fluxo (garantir pagador → emitir → guardar instruções →
+ * reconciliar) é o mesmo em qualquer gateway brasileiro.
+ */
+export interface PayableCharge {
+    id: string;
+    receivableId: string;
+    provider: string;
+    externalId: string | null;
+    method: BillingMethod;
+    amount: number;
+    status: string;
+    instructions: PaymentInstructions;
+}
+/**
+ * Cobrança viva de um recebível.
+ *
+ * "Viva" exclui cancelada e estornada — é a mesma definição do índice único da
+ * migration, e as duas precisam concordar: se divergirem, o código busca uma
+ * cobrança que o banco considera livre e a emissão seguinte estoura.
+ */
+export declare function findActiveCharge(tx: Tx, receivableId: string): Promise<PayableCharge | null>;
+export interface EnsureChargeInput {
+    receivableId: string;
+    clientId: string;
+    amount: number;
+    dueDate: string | null;
+    description: string | null;
+    method: BillingMethod;
+    customer: {
+        name: string;
+        documentNumber?: string | null;
+        email?: string | null;
+        phone?: string | null;
+    };
+    /** Data de referência. Injetada para o comportamento ser determinístico. */
+    today?: string;
+}
+export interface EnsureChargeResult {
+    charge: PayableCharge;
+    /** `false` quando a cobrança já existia — o chamador não deve auditar de novo. */
+    created: boolean;
+    /**
+     * O que aconteceu com o cadastro do pagador no provedor.
+     *
+     * Sai daqui para a trilha de auditoria: "reconciliado" é um fato sobre um
+     * sistema externo, e sem registrá-lo não há como responder depois por que uma
+     * emissão que falhava passou a funcionar.
+     */
+    customerSync: CustomerReconcileOutcome['action'];
+}
+/**
+ * Emite a cobrança de um recebível, ou devolve a que já existe.
+ *
+ * Três camadas de proteção contra duplicidade, porque cada uma falha num caso
+ * diferente:
+ *
+ * 1. **Busca antes de emitir** — resolve o caso comum (clique repetido, job que
+ *    roda de novo depois de concluir).
+ * 2. **`externalReference` determinístico** — o gateway recebe sempre a mesma
+ *    referência para o mesmo recebível, o que dá rastreabilidade de ida e volta.
+ * 3. **Índice único parcial** — resolve a corrida real: dois processos que
+ *    passaram juntos pela busca. O segundo leva erro do banco e relê.
+ *
+ * Só a terceira é garantia; as duas primeiras existem para que a terceira quase
+ * nunca precise disparar.
+ */
+export declare function ensureChargeForReceivable(tx: Tx, deps: {
+    provider: BillingProvider;
+    account: ProviderAccount;
+}, input: EnsureChargeInput): Promise<EnsureChargeResult>;
+/**
+ * Digest dos campos cadastrais que o provedor recebe.
+ *
+ * É o que permite responder "mudou desde a última sincronização?" sem manter uma
+ * segunda cópia de dado pessoal. Só entram os campos que o adapter realmente
+ * envia — incluir um campo que ninguém sincroniza faria a impressão digital
+ * mudar sem nada para reconciliar, e o sistema chamaria o gateway à toa.
+ *
+ * Normalização antes do hash: `null`, `undefined` e string vazia são a mesma
+ * ausência, e "  Fulano " é o mesmo nome que "Fulano". Sem isso, salvar a ficha
+ * sem editar nada dispararia uma sincronização.
+ */
+export declare function customerFingerprint(c: {
+    name: string;
+    documentNumber?: string | null;
+    email?: string | null;
+    phone?: string | null;
+}): string;
+export interface CustomerReconcileOutcome {
+    externalId: string | null;
+    /** `created` = pagador novo · `reconciled` = existia e foi atualizado · `unchanged` = já correspondia. */
+    action: 'created' | 'reconciled' | 'unchanged' | 'unsupported';
+}
+/**
+ * QR do PIX de uma cobrança, em PNG.
+ *
+ * O gateway entrega o QR como base64, e base64 embutido no e-mail não funciona:
+ * o Gmail serve toda imagem pelo próprio proxy, que só busca http(s). Guardamos
+ * o base64 e servimos por URL — o mesmo dado, num endereço que o cliente de
+ * e-mail consegue buscar.
+ *
+ * Devolve `null` quando a cobrança não tem QR (boleto, cobrança antiga, gateway
+ * que não expõe). Quem chama responde 404, e o e-mail simplesmente não mostra
+ * imagem.
+ */
+export declare function pixQrPngOf(tx: Tx, chargeId: string): Promise<Buffer | null>;
+//# sourceMappingURL=payment-rail.d.ts.map

package/dist/billing/payment-rail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-rail.d.ts","sourceRoot":"","sources":["../../src/billing/payment-rail.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,mBAAmB,CAAC;CACnC;AA0CD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,EAAE,EACN,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAU/B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,EAAE,EACN,IAAI,EAAE;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,EAC7D,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CA6E7B;AAoDD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GAAG,MAAM,CAMT;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0GAA0G;IAC1G,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;CAChE;AAoFD;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWjF"}

package/dist/billing/payment-rail.js

@@ -0,0 +1,295 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { assertLiveProviderAllowed, readLiveRuntime } from './live-guard.js';
+const toCharge = (r) => ({
+    id: r.id,
+    receivableId: r.receivable_id,
+    provider: r.provider,
+    externalId: r.external_id,
+    method: r.method,
+    amount: Number(r.amount),
+    status: r.status,
+    instructions: r.metadata ?? {},
+});
+/**
+ * Vencimento que o gateway aceita.
+ *
+ * Gateway não emite cobrança vencida — o Asaas recusa com `invalid_dueDate`. E
+ * recebível vencido é justamente o caso em que a cobrança mais importa: sem
+ * isto, quem está atrasado recebe o e-mail de cobrança **sem botão de pagar**,
+ * que é o oposto do que a régua existe para fazer.
+ *
+ * A data do gateway é empurrada para hoje; o vencimento REAL do recebível não
+ * muda, e é ele que o e-mail anuncia. O cliente vê "venceu em 10/08" no texto e
+ * uma cobrança pagável hoje — que é a verdade dos dois lados.
+ */
+function gatewayDueDate(dueDate, today) {
+    if (!dueDate)
+        return null;
+    const hoje = today ?? new Date().toISOString().slice(0, 10);
+    return dueDate < hoje ? hoje : dueDate;
+}
+/**
+ * Cobrança viva de um recebível.
+ *
+ * "Viva" exclui cancelada e estornada — é a mesma definição do índice único da
+ * migration, e as duas precisam concordar: se divergirem, o código busca uma
+ * cobrança que o banco considera livre e a emissão seguinte estoura.
+ */
+export async function findActiveCharge(tx, receivableId) {
+    const rows = await tx `
+    SELECT id, receivable_id, provider, external_id, method, amount, status, metadata
+    FROM charge
+    WHERE receivable_id = ${receivableId}
+      AND deleted_at IS NULL
+      AND status NOT IN ('canceled', 'refunded')
+    LIMIT 1
+  `;
+    return rows[0] ? toCharge(rows[0]) : null;
+}
+/**
+ * Emite a cobrança de um recebível, ou devolve a que já existe.
+ *
+ * Três camadas de proteção contra duplicidade, porque cada uma falha num caso
+ * diferente:
+ *
+ * 1. **Busca antes de emitir** — resolve o caso comum (clique repetido, job que
+ *    roda de novo depois de concluir).
+ * 2. **`externalReference` determinístico** — o gateway recebe sempre a mesma
+ *    referência para o mesmo recebível, o que dá rastreabilidade de ida e volta.
+ * 3. **Índice único parcial** — resolve a corrida real: dois processos que
+ *    passaram juntos pela busca. O segundo leva erro do banco e relê.
+ *
+ * Só a terceira é garantia; as duas primeiras existem para que a terceira quase
+ * nunca precise disparar.
+ */
+export async function ensureChargeForReceivable(tx, deps, input) {
+    // A chave geral vale para EMISSÃO NOVA, e só. Uma cobrança que já existe
+    // continua sendo devolvida, e o dinheiro que entrar continua sendo baixado:
+    // pausar emissão não pode significar parar de reconhecer pagamento.
+    // O escopo é o recebível: uma autorização nomeada libera a emissão DESTE
+    // lançamento e de nenhum outro, com a chave geral seguindo armada.
+    assertLiveProviderAllowed(deps.account.environment, readLiveRuntime(), 'charge', input.receivableId);
+    const existing = await findActiveCharge(tx, input.receivableId);
+    if (existing) {
+        return {
+            charge: await refreshInstructionsIfIncomplete(tx, deps, existing),
+            created: false,
+            customerSync: 'unchanged',
+        };
+    }
+    // Reconciliação ANTES da emissão, e não depois: o gateway valida o pagador no
+    // momento em que a cobrança é criada. Corrigir o cadastro depois de a emissão
+    // ser recusada não ajudaria ninguém.
+    const customerSync = await ensurePaymentCustomer(tx, deps, input);
+    const customerExternalId = customerSync.externalId;
+    const emitted = await deps.provider.createCharge({
+        // Determinístico: o mesmo recebível produz sempre a mesma referência, o que
+        // permite reconciliar manualmente no painel do gateway sem consultar o banco.
+        referenceId: `receivable:${input.receivableId}`,
+        amount: input.amount,
+        method: input.method,
+        dueDate: gatewayDueDate(input.dueDate, input.today),
+        description: input.description,
+        customer: input.customer,
+        customerExternalId,
+    });
+    const id = randomUUID();
+    const inserted = await tx `
+    INSERT INTO charge (
+      id, tenant_id, client_id, receivable_id, provider_account_id, provider,
+      external_id, method, amount, status, description, due_date, metadata
+    ) VALUES (
+      ${id},
+      NULLIF(current_setting('app.current_tenant', true), '')::uuid,
+      ${input.clientId}, ${input.receivableId}, ${deps.account.id}, ${deps.provider.key},
+      ${emitted.externalId}, ${input.method}, ${input.amount}, ${emitted.status},
+      ${input.description}, ${input.dueDate}, ${tx.json((emitted.payment ?? {}))}
+    )
+    -- O alvo do ON CONFLICT é EXPLÍCITO, e não um "DO NOTHING" genérico.
+    -- Genérico engoliria também um external_id repetido — que não é corrida, é
+    -- defeito do adapter — e o trataria como "alguém chegou primeiro",
+    -- cancelando no gateway uma cobrança legítima. Aqui, só a duplicata de
+    -- cobrança viva é tolerada; qualquer outro conflito estoura e aparece.
+    ON CONFLICT (tenant_id, receivable_id)
+      WHERE receivable_id IS NOT NULL
+        AND deleted_at IS NULL
+        AND status NOT IN ('canceled', 'refunded')
+      DO NOTHING
+    RETURNING id, receivable_id, provider, external_id, method, amount, status, metadata
+  `;
+    if (inserted[0])
+        return { charge: toCharge(inserted[0]), created: true, customerSync: customerSync.action };
+    // Perdemos a corrida: outro processo inseriu entre a busca e o INSERT. A
+    // cobrança que acabamos de emitir no gateway fica órfã — por isso ela é
+    // cancelada, em vez de deixarmos duas cobranças ativas para o mesmo valor.
+    if (emitted.externalId) {
+        await deps.provider.cancelCharge(emitted.externalId).catch(() => undefined);
+    }
+    const winner = await findActiveCharge(tx, input.receivableId);
+    if (!winner)
+        throw new Error('charge_conflict_without_winner');
+    return { charge: winner, created: false, customerSync: customerSync.action };
+}
+/**
+ * Completa as instruções de pagamento que faltaram na emissão.
+ *
+ * O QR do PIX vem de um endpoint separado, e essa chamada é tolerante a falha
+ * de propósito — derrubar a emissão inteira por causa de um extra trocaria uma
+ * cobrança incompleta por nenhuma cobrança. Só que, sem este refresh, a
+ * cobrança ficava incompleta **para sempre**: nada voltava a buscar.
+ *
+ * Aconteceu de verdade na primeira cobrança da conta sandbox da SC, enquanto a
+ * chave PIX ainda era provisionada do lado do gateway. A segunda emissão veio
+ * completa; a primeira teria seguido sem QR até alguém notar.
+ *
+ * Roda só quando falta algo e o provider sabe reconsultar — uma cobrança
+ * completa não gasta chamada nenhuma.
+ */
+async function refreshInstructionsIfIncomplete(tx, deps, charge) {
+    if (!deps.provider.fetchPaymentInstructions || !charge.externalId)
+        return charge;
+    if (!isIncomplete(charge))
+        return charge;
+    const fresh = await deps.provider
+        .fetchPaymentInstructions(charge.externalId, charge.method)
+        .catch(() => null);
+    if (!fresh)
+        return charge;
+    // Mescla em vez de substituir: o que já estava gravado não pode sumir porque
+    // uma reconsulta veio mais pobre que a original.
+    const merged = { ...charge.instructions, ...pruneEmpty(fresh) };
+    await tx `
+    UPDATE charge SET metadata = ${tx.json(merged)}, updated_at = now()
+    WHERE id = ${charge.id}
+  `;
+    return { ...charge, instructions: merged };
+}
+/** O que cada método precisa ter para o e-mail ficar completo. */
+function isIncomplete(charge) {
+    const i = charge.instructions;
+    if (charge.method === 'pix')
+        return !i.pixPayload || !i.pixQrCodeImage;
+    if (charge.method === 'boleto')
+        return !i.boletoUrl || !i.identificationField;
+    return !i.invoiceUrl;
+}
+function pruneEmpty(i) {
+    return Object.fromEntries(Object.entries(i).filter(([, v]) => v));
+}
+/**
+ * Digest dos campos cadastrais que o provedor recebe.
+ *
+ * É o que permite responder "mudou desde a última sincronização?" sem manter uma
+ * segunda cópia de dado pessoal. Só entram os campos que o adapter realmente
+ * envia — incluir um campo que ninguém sincroniza faria a impressão digital
+ * mudar sem nada para reconciliar, e o sistema chamaria o gateway à toa.
+ *
+ * Normalização antes do hash: `null`, `undefined` e string vazia são a mesma
+ * ausência, e "  Fulano " é o mesmo nome que "Fulano". Sem isso, salvar a ficha
+ * sem editar nada dispararia uma sincronização.
+ */
+export function customerFingerprint(c) {
+    const norm = (v) => (v ?? '').trim().toLowerCase();
+    const digits = (v) => (v ?? '').replace(/\D/g, '');
+    return createHash('sha256')
+        .update([norm(c.name), digits(c.documentNumber), norm(c.email), digits(c.phone)].join('\u0000'))
+        .digest('hex');
+}
+/**
+ * Garante que o pagador EXISTE no gateway e que ele está CORRETO.
+ *
+ * O mapa local continua evitando ida ao gateway na maioria das emissões — mas
+ * ele deixa de significar "existe, logo está certo para sempre", que era a
+ * dívida R. Agora ele guarda também a impressão digital do que foi sincronizado,
+ * e a decisão passa a ser:
+ *
+ *   sem registro          → cria (o adapter ainda busca antes, para não duplicar)
+ *   registro coerente     → devolve, sem tocar na rede
+ *   registro divergente   → ATUALIZA no gateway, e só então grava a nova digital
+ *
+ * Digital nula é tratada como divergente de propósito: é o estado das linhas
+ * anteriores a esta correção, e é assim que a base existente se cura na primeira
+ * emissão de cada cliente, sem backfill adivinhando o que o gateway tem.
+ *
+ * Falha de atualização NÃO é engolida e NÃO grava digital. O Office não pode
+ * registrar que sincronizou o que não sincronizou — na próxima tentativa, ele
+ * tenta de novo.
+ */
+async function ensurePaymentCustomer(tx, deps, input) {
+    if (!deps.provider.ensureCustomer)
+        return { externalId: null, action: 'unsupported' };
+    const customer = { ...input.customer, referenceId: `client:${input.clientId}` };
+    const fingerprint = customerFingerprint(input.customer);
+    const rows = await tx `
+    SELECT external_id, synced_fingerprint FROM payment_customer
+    WHERE provider_account_id = ${deps.account.id} AND client_id = ${input.clientId}
+    LIMIT 1
+  `;
+    if (rows[0]) {
+        if (rows[0].synced_fingerprint === fingerprint) {
+            return { externalId: rows[0].external_id, action: 'unchanged' };
+        }
+        if (!deps.provider.updateCustomer) {
+            // Provider sem atualização: devolver o id calado faria o Office parecer
+            // sincronizado. Melhor dizer que não é suportado e deixar quem chamou
+            // decidir — a alternativa é a dívida R de volta, silenciosa.
+            return { externalId: rows[0].external_id, action: 'unsupported' };
+        }
+        await deps.provider.updateCustomer(rows[0].external_id, customer);
+        await tx `
+      UPDATE payment_customer
+         SET synced_fingerprint = ${fingerprint}, synced_at = now(), updated_at = now()
+       WHERE provider_account_id = ${deps.account.id} AND client_id = ${input.clientId}
+    `;
+        return { externalId: rows[0].external_id, action: 'reconciled' };
+    }
+    const ensured = await deps.provider.ensureCustomer(customer);
+    // O adapter distingue "criei" de "encontrei e reconciliei"; o rail não teria
+    // como. Sem isto, a trilha registrava `created` para um pagador que já existia
+    // no gateway e acabara de ser corrigido — o histórico dizia a coisa errada
+    // justamente no caso que mais importa auditar.
+    const externalId = typeof ensured === 'string' ? ensured : ensured.externalId;
+    const action = typeof ensured === 'string' ? 'created' : ensured.action;
+    await tx `
+    INSERT INTO payment_customer (
+      id, tenant_id, client_id, provider_account_id, provider, external_id,
+      synced_fingerprint, synced_at
+    ) VALUES (
+      ${randomUUID()},
+      NULLIF(current_setting('app.current_tenant', true), '')::uuid,
+      ${input.clientId}, ${deps.account.id}, ${deps.provider.key}, ${externalId},
+      ${fingerprint}, now()
+    )
+    ON CONFLICT (tenant_id, provider_account_id, client_id) DO UPDATE
+      SET synced_fingerprint = EXCLUDED.synced_fingerprint,
+          synced_at = EXCLUDED.synced_at,
+          updated_at = now()
+  `;
+    return { externalId, action };
+}
+/**
+ * QR do PIX de uma cobrança, em PNG.
+ *
+ * O gateway entrega o QR como base64, e base64 embutido no e-mail não funciona:
+ * o Gmail serve toda imagem pelo próprio proxy, que só busca http(s). Guardamos
+ * o base64 e servimos por URL — o mesmo dado, num endereço que o cliente de
+ * e-mail consegue buscar.
+ *
+ * Devolve `null` quando a cobrança não tem QR (boleto, cobrança antiga, gateway
+ * que não expõe). Quem chama responde 404, e o e-mail simplesmente não mostra
+ * imagem.
+ */
+export async function pixQrPngOf(tx, chargeId) {
+    const rows = await tx `
+    SELECT metadata FROM charge WHERE id = ${chargeId} AND deleted_at IS NULL
+  `;
+    const raw = rows[0]?.metadata?.pixQrCodeImage;
+    if (!raw)
+        return null;
+    // Aceita tanto o data URI (formato em que o adapter guarda) quanto base64 cru.
+    const base64 = raw.startsWith('data:') ? (raw.split(',')[1] ?? '') : raw;
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64))
+        return null;
+    return Buffer.from(base64, 'base64');
+}
+//# sourceMappingURL=payment-rail.js.map

package/dist/billing/payment-rail.js.map

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

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

@@ -1,15 +1,60 @@
-import type { BillingProvider, ChargeRequest, ChargeResult, ProviderConfig, SubscriptionRequest, SubscriptionResult, WebhookEvent } from './types.js';
+import type { EnsureCustomerResult, BillingMethod, BillingProvider, ChargeRequest, ChargeResult, CustomerRequest, PaymentInstructions, ProviderAccountIdentity, ProviderConfig, SubscriptionRequest, SubscriptionResult, WebhookEvent } from './types.js';
 export declare class AsaasProvider implements BillingProvider {
     readonly key = "asaas";
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly webhookSecret;
     private readonly fetchImpl;
     constructor(config: ProviderConfig);
     private call;
+    /**
+     * 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.
+     */
+    ensureCustomer(req: CustomerRequest): Promise<EnsureCustomerResult>;
+    /**
+     * 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.
+     */
+    updateCustomer(externalId: string, req: CustomerRequest): Promise<void>;
+    describeAccount(): Promise<ProviderAccountIdentity>;
     createCharge(req: ChargeRequest): Promise<ChargeResult>;
+    fetchPaymentInstructions(externalId: string, method: BillingMethod): Promise<PaymentInstructions>;
+    /**
+     * 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.
+     */
+    private instructionsFor;
     cancelCharge(externalId: string): Promise<void>;
     createSubscription(req: SubscriptionRequest): Promise<SubscriptionResult>;
     cancelSubscription(externalId: string): Promise<void>;
+    /**
+     * 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: unknown, headers?: Record<string, string>): boolean;
     parseWebhook(payload: unknown): WebhookEvent;
 }
 //# sourceMappingURL=asaas.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"asaas.d.ts","sourceRoot":"","sources":["../../../src/billing/provider/asaas.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACb,MAAM,YAAY,CAAC;AAyBpB,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,GAAG,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,MAAM,EAAE,cAAc;YAOpB,IAAI;IAaZ,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBvD,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAkBzE,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY;CAiB7C"}
+{"version":3,"file":"asaas.d.ts","sourceRoot":"","sources":["../../../src/billing/provider/asaas.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACb,MAAM,YAAY,CAAC;AA6BpB,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,GAAG,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,MAAM,EAAE,cAAc;YAQpB,IAAI;IAalB;;;;;;;;OAQG;IACG,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAyBzE;;;;;;;OAOG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvE,eAAe,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAoBnD,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAsBvD,wBAAwB,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,mBAAmB,CAAC;IAK/B;;;;;;;;;;OAUG;YACW,eAAe;IA6BvB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;;;;;OASG;IACH,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,OAAO;IAM/E,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY;CAkD7C"}