@baruk/core 0.3.0 → 0.4.2

package/dist/collection/delivery-callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-callback.d.ts","sourceRoot":"","sources":["../../src/collection/delivery-callback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAInC,MAAM,MAAM,eAAe;AACzB,iCAAiC;AAC/B,SAAS;AACX,oFAAoF;GAClF,yBAAyB;AAC3B,4EAA4E;GAC1E,aAAa;AACf,wEAAwE;GACtE,iBAAiB,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAKD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,CAAC,CAmEzB;AA0CD,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAsCxB"}

package/dist/collection/delivery-callback.js

@@ -0,0 +1,147 @@
+/**
+ * Aplicação dos callbacks de entrega ao estado do produto.
+ *
+ * `communication/webhook.ts` traduz o vocabulário do provider e decide se o
+ * evento avança o estado; este arquivo é o que ESCREVE. A separação é a mesma de
+ * sempre: o motor não conhece `dunning_event`, e a régua não conhece a Meta.
+ *
+ * Três escritas, e a ordem entre elas importa menos que o fato de estarem na
+ * MESMA transação: um callback que atualiza a etapa e falha ao gravar a trilha
+ * deixaria a tela dizendo "entregue" sem nada que explique quando nem por qual
+ * caminho.
+ */
+import { randomUUID } from 'node:crypto';
+import { applyDeliveryEvent, } from '../communication/index.js';
+import { recordConsent } from './consent-repository.js';
+import { SC_PRODUCT } from './communication-bridge.js';
+/** Estados de `dunning_event` que descrevem uma mensagem já entregue ao provider. */
+const DELIVERABLE = ['sent', 'delivered', 'read', 'failed'];
+/**
+ * Aplica um callback de entrega.
+ *
+ * A via de acesso é o `provider_ref` — é a ÚNICA coisa que o webhook traz. Sem
+ * a coluna indexada da 0038 isso exigiria varrer a tabela, e a régua de um
+ * escritório grande tornaria cada callback caro o bastante para o provider
+ * desistir de reentregar.
+ */
+export async function applyDeliveryCallback(tx, tenantId, event) {
+    const rows = await tx `
+    SELECT id, receivable_id, status, idempotency_key
+      FROM dunning_event
+     WHERE provider_ref = ${event.providerRef}
+     LIMIT 1
+  `;
+    const action = rows[0];
+    // Sem ação correspondente não há o que atualizar. NÃO é erro: o mesmo número
+    // pode ter mandado mensagem por outro sistema, e um 4xx aqui faria o provider
+    // reentregar para sempre um evento que nunca vai ser reconhecido.
+    if (!action) {
+        await recordCallbackEvent(tx, tenantId, event, null, null, 'unknown_message');
+        return { outcome: 'unknown_message', receivableId: null, status: null };
+    }
+    // `advanceStatus` opera sobre estados de ENTREGA. Uma ação `scheduled`,
+    // `canceled` ou `escalated` não descreve mensagem entregue, e forçá-la para
+    // `delivered` inventaria uma entrega que a régua não fez.
+    const current = (DELIVERABLE.includes(action.status) ? action.status : 'sent');
+    const decision = applyDeliveryEvent(current, event);
+    if (!decision.apply) {
+        await recordCallbackEvent(tx, tenantId, event, action.receivable_id, action.idempotency_key, decision.reason);
+        return { outcome: decision.reason, receivableId: action.receivable_id, status: null };
+    }
+    await tx `
+    UPDATE dunning_event
+       SET status = ${decision.status},
+           delivered_at = CASE
+             WHEN ${decision.status} IN ('delivered', 'read') THEN COALESCE(delivered_at, ${event.occurredAt}::timestamptz)
+             ELSE delivered_at END,
+           read_at = CASE
+             WHEN ${decision.status} = 'read' THEN COALESCE(read_at, ${event.occurredAt}::timestamptz)
+             ELSE read_at END,
+           last_error = CASE
+             WHEN ${decision.status} = 'failed' THEN ${(event.detail ?? event.code ?? 'falha reportada pelo provider').slice(0, 300)}
+             ELSE last_error END
+     WHERE id = ${action.id}
+  `;
+    await recordCallbackEvent(tx, tenantId, event, action.receivable_id, action.idempotency_key, null, decision.status);
+    return {
+        outcome: 'applied',
+        receivableId: action.receivable_id,
+        status: decision.status,
+    };
+}
+const CALLBACK_KIND = {
+    delivered: 'callback_delivered',
+    read: 'callback_read',
+    failed: 'callback_failed',
+    opted_out: 'opt_out',
+};
+async function recordCallbackEvent(tx, tenantId, event, subjectRef, idempotencyKey, refusal, applied) {
+    // Evento recusado também vira linha. É a diferença entre "o provider nunca
+    // avisou" e "avisou e nós descartamos" — e só a segunda tem explicação.
+    const kind = refusal ? 'dispatch_skipped' : (CALLBACK_KIND[event.status] ?? 'dispatch_skipped');
+    await tx `
+    INSERT INTO communication_event (
+      id, tenant_id, product, brand, kind, channel, event_type, subject_ref,
+      recipient_ref, idempotency_key, provider_ref, skip_reason, status, code,
+      detail, occurred_at
+    ) VALUES (
+      ${randomUUID()}, ${tenantId}, ${SC_PRODUCT},
+      -- A marca vem da RESERVA que produziu a mensagem. Quando não há reserva
+      -- correspondente, o evento fica sem marca — é o caso do callback sobre um
+      -- identificador que não é nosso, e inventar um valor aqui faria a trilha
+      -- atribuir a um escritório algo que ele não enviou.
+      (SELECT brand FROM communication_dispatch
+        WHERE provider_ref = ${event.providerRef} LIMIT 1),
+      ${kind}, ${event.channel}, 'billing.dunning.callback', ${subjectRef},
+      NULL, ${idempotencyKey}, ${event.providerRef}, ${refusal},
+      ${applied ?? event.status}, ${event.code ?? null},
+      ${event.detail ? event.detail.slice(0, 300) : null}, ${event.occurredAt}::timestamptz
+    )
+  `;
+}
+/**
+ * Registra o opt-out que o cliente pediu respondendo no canal.
+ *
+ * `customer_reply` é a origem mais forte que existe: `recordConsent` impede que
+ * um operador a reverta pela tela. Por isso a resolução do telefone para cliente
+ * é feita pelo `phone_e164` canônico e nunca pelo campo digitado — casar por
+ * texto livre acertaria o cliente errado quando dois cadastros diferem só na
+ * pontuação, e bloquearia o canal de quem não pediu nada.
+ */
+export async function applyInboundOptOut(tx, tenantId, optOut) {
+    const e164 = optOut.from.startsWith('+') ? optOut.from : `+${optOut.from}`;
+    const rows = await tx `
+    SELECT id FROM client
+     WHERE phone_e164 = ${e164} AND deleted_at IS NULL
+     ORDER BY created_at
+     LIMIT 2
+  `;
+    // Dois clientes com o mesmo telefone é cadastro legítimo (marido e mulher,
+    // matriz e filial). Bloquear "o primeiro" seria escolher por sorte quem
+    // deixa de ser cobrado. Sem resolução única, nada é registrado — e o evento
+    // fica na trilha para um humano decidir.
+    if (rows.length !== 1)
+        return 'unknown_recipient';
+    await recordConsent(tx, {
+        tenantId,
+        clientId: rows[0].id,
+        channel: optOut.channel,
+        state: 'denied',
+        source: 'customer_reply',
+        note: 'opt-out recebido no canal',
+    });
+    await tx `
+    INSERT INTO communication_event (
+      id, tenant_id, product, brand, kind, channel, event_type, recipient_ref,
+      code, occurred_at
+    ) VALUES (
+      -- Opt-out é do CLIENTE, e vale para todas as marcas do escritório: o
+      -- pedido de silêncio não é por linha de produto. Sem marca, portanto.
+      ${randomUUID()}, ${tenantId}, ${SC_PRODUCT}, NULL, 'opt_out',
+      ${optOut.channel}, 'communication.opt_out', ${rows[0].id},
+      'customer_reply', ${optOut.occurredAt}::timestamptz
+    )
+  `;
+    return 'registered';
+}
+//# sourceMappingURL=delivery-callback.js.map

package/dist/collection/delivery-callback.js.map

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

package/dist/collection/email-layout.d.ts

@@ -0,0 +1,45 @@
+import type { TenantBranding } from './branding.js';
+import type { PaymentBlock } from './payment-block.js';
+/**
+ * Shell transacional do e-mail de cobrança.
+ *
+ * Escrito com tabelas e estilo inline de propósito: Gmail remove `<style>` em
+ * boa parte dos contextos e o Outlook desktop renderiza com o motor do Word, que
+ * ignora flexbox, grid e boa parte de CSS moderno. O layout que "fica bonito no
+ * navegador" é justamente o que quebra na caixa de entrada.
+ *
+ * A única imagem é a logomarca, e o cabeçalho é construído para sobreviver ao
+ * bloqueio de imagens — padrão em muitos leitores. Nenhuma informação mora só
+ * dentro do arquivo: com as imagens desligadas, o nome do escritório continua
+ * escrito no cabeçalho.
+ *
+ * Cores e tipografia vêm do tenant (`TenantBranding`), não de constantes daqui.
+ * Nenhum escritório está no código.
+ */
+export interface EmailBlock {
+    greeting: string;
+    /** Parágrafos do corpo, na ordem. */
+    paragraphs: string[];
+    /** Destaque do valor/vencimento. Omitido quando não há dívida a exibir. */
+    highlight?: {
+        label: string;
+        amount: string;
+        dueLabel: string;
+        dueValue: string;
+    };
+    closing?: string;
+    /** Como pagar. Ausente quando o recebível ainda não tem cobrança emitida. */
+    payment?: PaymentBlock;
+}
+export declare function escapeHtml(s: string): string;
+export declare function renderCollectionEmail(b: TenantBranding, block: EmailBlock): string;
+/**
+ * Versão texto puro.
+ *
+ * Não é decoração: parte dos leitores prefere `text/plain`, filtros de spam
+ * penalizam mensagem só-HTML, e leitores de tela lidam melhor com o texto. O
+ * conteúdo tem de ser o MESMO — um plain text resumido faria dois clientes
+ * receberem informações diferentes.
+ */
+export declare function renderCollectionText(b: TenantBranding, block: EmailBlock): string;
+//# sourceMappingURL=email-layout.d.ts.map

package/dist/collection/email-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-layout.d.ts","sourceRoot":"","sources":["../../src/collection/email-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAgCD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAO5C;AAsID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAqElF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAmCjF"}

package/dist/collection/email-layout.js

@@ -0,0 +1,247 @@
+/**
+ * A cor é revalidada AQUI, e não só em `getTenantBranding`.
+ *
+ * Ela é interpolada dentro de um atributo `style`; confiar que o chamador já
+ * sanitizou é o tipo de suposição que se perde na primeira refatoração — basta
+ * alguém montar o branding à mão para injetar CSS (ou fechar o atributo e
+ * injetar markup) na mensagem que sai em nome do escritório.
+ */
+function safeColorForRender(v) {
+    return /^#[0-9a-fA-F]{6}$/.test(v) ? v : '#1f3a5f';
+}
+/**
+ * URL só entra no `href`/`src` se for https.
+ *
+ * O escape de HTML já impediria a fuga do atributo, mas ele não impede um
+ * `javascript:` de continuar sendo `javascript:`. E esta URL vem do metadata da
+ * cobrança, que passou por um gateway externo — validar aqui é o mesmo
+ * princípio já aplicado à cor: não confiar em quem chama.
+ */
+function safeUrlForRender(v) {
+    if (!v)
+        return null;
+    return /^https:\/\/[^\s"'<>]+$/i.test(v) ? v : null;
+}
+/** Mesma razão da cor: a stack de fontes também é interpolada num `style`. */
+function safeFontForRender(v) {
+    return /^[A-Za-z0-9 ,.'-]+$/.test(v) ? v : `-apple-system,'Segoe UI',Helvetica,Arial,sans-serif`;
+}
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Cabeçalho — a assinatura visual institucional da mensagem.
+ *
+ * Três formas, conforme o que o tenant tem:
+ *
+ * | `logoUrl` | `logoKind` | Cabeçalho |
+ * |---|---|---|
+ * | ausente | — | nome + tagline em tipografia |
+ * | presente | `symbol` | símbolo à esquerda, nome + tagline à direita |
+ * | presente | `lockup` | só a imagem (o nome já está desenhada nela) + tagline |
+ *
+ * O par símbolo+texto é montado com tabela, não com flex: o Outlook desktop
+ * renderiza com o motor do Word e empilharia as duas colunas.
+ */
+function header(b) {
+    const name = escapeHtml(b.officeName);
+    const font = safeFontForRender(b.fontFamily);
+    const tagline = b.tagline
+        ? `<div style="margin-top:6px;font-family:${font};font-size:12px;line-height:1.4;color:#ffffff;opacity:.72">${escapeHtml(b.tagline)}</div>`
+        : '';
+    const wordmark = `<span style="font-family:${font};font-size:19px;font-weight:700;color:#ffffff;letter-spacing:-.01em">${name}</span>${tagline}`;
+    if (!b.logoUrl)
+        return wordmark;
+    const src = escapeHtml(b.logoUrl);
+    if (b.logoKind === 'lockup') {
+        // O lockup já traz o nome desenhado — repetir em texto duplicaria a marca.
+        // Por isso o `alt` carrega o nome aqui: com imagens bloqueadas, é a única
+        // coisa que sobra no cabeçalho.
+        return `<img src="${src}" alt="${name}" height="36"
+      style="display:block;border:0;outline:none;text-decoration:none;height:36px;width:auto;max-width:260px" />${tagline}`;
+    }
+    // Símbolo: 40px, tamanho mínimo do manual de marca com folga, e discreto o
+    // bastante para o nome continuar sendo a primeira leitura. `alt` vazio de
+    // propósito — o nome está ao lado, e um `alt` repetido faria o leitor de tela
+    // (e o cliente com imagens bloqueadas) anunciar o escritório duas vezes.
+    return `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="border-collapse:collapse">
+      <tr>
+        <td valign="middle" style="padding-right:14px">
+          <img src="${src}" alt="" width="40" height="40"
+            style="display:block;border:0;outline:none;text-decoration:none;width:40px;height:40px" />
+        </td>
+        <td valign="middle">${wordmark}</td>
+      </tr>
+    </table>`;
+}
+/**
+ * Bloco de pagamento.
+ *
+ * Hierarquia deliberada: **um** botão, e o resto discreto abaixo. Dar o mesmo
+ * peso visual a PIX, boleto e link transforma a decisão de pagar numa escolha
+ * de meio — e quem hesita, adia. O botão é um `<a>` com padding, não um
+ * `<button>`: cliente de e-mail não executa formulário, e o Outlook desenha o
+ * fundo da tabela mesmo quando ignora o `border-radius`.
+ *
+ * O copia-e-cola do PIX vai em texto selecionável, sem botão de copiar — não há
+ * JavaScript em e-mail, e um botão que não copia nada é uma promessa quebrada.
+ */
+function renderPayment(b, t) {
+    if (!b)
+        return '';
+    const target = safeUrlForRender(b.url) ?? safeUrlForRender(b.boletoUrl);
+    const cta = target
+        ? `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="border-collapse:collapse;margin:0 0 18px">
+        <tr><td align="center" bgcolor="${t.primary}" style="border-radius:6px">
+          <a href="${escapeHtml(target)}"
+             style="display:inline-block;padding:14px 34px;font-family:${t.font};font-size:15px;font-weight:700;color:#ffffff;text-decoration:none;border-radius:6px">Pagar agora</a>
+        </td></tr>
+      </table>`
+        : '';
+    const alternativas = [];
+    // O QR precisa ser uma URL **https**.
+    //
+    // Um `data:` URI parece funcionar no navegador e **não funciona no Gmail**:
+    // ele serve toda imagem pelo próprio proxy, que só busca http(s). O resultado
+    // é o pior possível — um ícone quebrado onde deveria estar o meio de
+    // pagamento, exatamente como apareceu no QA.
+    //
+    // Sem URL válida, nenhuma `<img>` é emitida: o copia-e-cola abaixo continua
+    // pagando a conta, e uma imagem quebrada só faria o e-mail parecer defeituoso.
+    const qr = safeUrlForRender(b.pixQrCodeImage);
+    if (qr) {
+        alternativas.push(`<tr><td align="center" style="padding:4px 0 10px">
+        <img src="${escapeHtml(qr)}" alt="QR Code do PIX" width="150" height="150"
+          style="display:block;border:0;width:150px;height:150px" />
+      </td></tr>`);
+    }
+    if (b.pixPayload) {
+        alternativas.push(`<tr><td style="padding:0 0 10px">
+        <div style="font-family:${t.font};font-size:12px;color:${t.muted};margin-bottom:4px">PIX copia e cola</div>
+        <div style="font-family:Consolas,'Courier New',monospace;font-size:11px;line-height:1.5;color:#2b3440;word-break:break-all;background:#ffffff;border:1px solid #e3e8ee;border-radius:4px;padding:10px">${escapeHtml(b.pixPayload)}</div>
+      </td></tr>`);
+    }
+    if (b.identificationField) {
+        alternativas.push(`<tr><td style="padding:0 0 10px">
+        <div style="font-family:${t.font};font-size:12px;color:${t.muted};margin-bottom:4px">Linha digitável do boleto</div>
+        <div style="font-family:Consolas,'Courier New',monospace;font-size:12px;line-height:1.5;color:#2b3440;word-break:break-all">${escapeHtml(b.identificationField)}</div>
+      </td></tr>`);
+    }
+    if (!cta && !alternativas.length)
+        return '';
+    const alt = alternativas.length
+        ? `<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%"
+        style="border-collapse:collapse;margin:0 0 20px;background:#f6f8fa;border-radius:6px">
+        <tr><td style="padding:16px 18px">
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="border-collapse:collapse">
+            ${alternativas.join('')}
+          </table>
+        </td></tr>
+      </table>`
+        : '';
+    return `${cta}${alt}`;
+}
+export function renderCollectionEmail(b, block) {
+    const name = escapeHtml(b.officeName);
+    const primary = safeColorForRender(b.primaryColor);
+    const accent = safeColorForRender(b.accentColor);
+    const bg = safeColorForRender(b.backgroundColor);
+    const text = safeColorForRender(b.textColor);
+    const muted = safeColorForRender(b.mutedColor);
+    const font = safeFontForRender(b.fontFamily);
+    const p = (t) => `<p style="margin:0 0 16px;font-family:${font};font-size:15px;line-height:1.65;color:${text}">${escapeHtml(t)}</p>`;
+    const highlight = block.highlight
+        ? `<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%"
+        style="margin:0 0 24px;border-collapse:collapse;background:#f6f8fa;border-left:3px solid ${accent};border-radius:4px">
+        <tr>
+          <td style="padding:18px 20px">
+            <div style="font-family:${font};font-size:12px;letter-spacing:.06em;text-transform:uppercase;color:${muted};margin-bottom:6px">${escapeHtml(block.highlight.label)}</div>
+            <div style="font-family:${font};font-size:26px;font-weight:700;color:#1a2029;line-height:1.2">${escapeHtml(block.highlight.amount)}</div>
+            <div style="font-family:${font};font-size:14px;color:#4a5563;margin-top:8px">${escapeHtml(block.highlight.dueLabel)} <strong style="color:#1a2029">${escapeHtml(block.highlight.dueValue)}</strong></div>
+          </td>
+        </tr>
+      </table>`
+        : '';
+    const payment = renderPayment(block.payment, { primary, accent, muted, font });
+    const support = [
+        b.supportEmail ? escapeHtml(b.supportEmail) : null,
+        b.supportPhone ? escapeHtml(b.supportPhone) : null,
+        b.website ? escapeHtml(b.website.replace(/^https:\/\//, '')) : null,
+    ].filter(Boolean);
+    return `<!doctype html>
+<html lang="pt-BR"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<meta name="color-scheme" content="light" />
+<title>${name}</title></head>
+<body style="margin:0;padding:0;background:${bg};-webkit-text-size-adjust:100%">
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="background:${bg};border-collapse:collapse">
+  <tr><td align="center" style="padding:32px 12px">
+    <table role="presentation" cellpadding="0" cellspacing="0" border="0" width="600"
+      style="width:600px;max-width:100%;border-collapse:collapse;background:#ffffff;border-radius:8px;overflow:hidden;box-shadow:0 1px 3px rgba(16,24,40,.08)">
+
+      <tr><td style="background:${primary};padding:24px 32px">${header(b)}</td></tr>
+
+      <tr><td style="padding:32px">
+        ${p(block.greeting)}
+        ${block.paragraphs.map(p).join('')}
+        ${highlight}
+        ${payment}
+        ${block.closing ? p(block.closing) : ''}
+        <p style="margin:24px 0 0;font-family:${font};font-size:15px;line-height:1.6;color:${text}">
+          Atenciosamente,<br /><strong>${escapeHtml(b.signatureName)}</strong>
+        </p>
+      </td></tr>
+
+      <tr><td style="padding:20px 32px;background:#f6f8fa;border-top:1px solid #e3e8ee">
+        <p style="margin:0;font-family:${font};font-size:12px;line-height:1.6;color:${muted}">
+          Mensagem automática enviada por ${name}.${support.length ? ` Para falar conosco: ${support.join(' · ')}.` : ''}<br />
+          Se o pagamento já foi realizado, desconsidere este aviso.
+        </p>
+      </td></tr>
+
+    </table>
+  </td></tr>
+</table>
+</body></html>`;
+}
+/**
+ * Versão texto puro.
+ *
+ * Não é decoração: parte dos leitores prefere `text/plain`, filtros de spam
+ * penalizam mensagem só-HTML, e leitores de tela lidam melhor com o texto. O
+ * conteúdo tem de ser o MESMO — um plain text resumido faria dois clientes
+ * receberem informações diferentes.
+ */
+export function renderCollectionText(b, block) {
+    const parts = [block.greeting, '', ...block.paragraphs];
+    if (block.highlight) {
+        parts.push('', `${block.highlight.label}: ${block.highlight.amount}`, `${block.highlight.dueLabel} ${block.highlight.dueValue}`);
+    }
+    if (block.payment) {
+        const pay = block.payment;
+        const linhas = [];
+        const alvo = pay.url ?? pay.boletoUrl;
+        if (alvo)
+            linhas.push(`Pague aqui: ${alvo}`);
+        if (pay.pixPayload)
+            linhas.push('', 'PIX copia e cola:', pay.pixPayload);
+        if (pay.identificationField)
+            linhas.push('', 'Linha digitável:', pay.identificationField);
+        if (linhas.length)
+            parts.push('', ...linhas);
+    }
+    if (block.closing)
+        parts.push('', block.closing);
+    parts.push('', 'Atenciosamente,', b.signatureName);
+    const support = [b.supportEmail, b.supportPhone, b.website?.replace(/^https:\/\//, '')]
+        .filter(Boolean)
+        .join(' · ');
+    parts.push('', '---', `Mensagem automática enviada por ${b.officeName}.${support ? ` Para falar conosco: ${support}.` : ''}`, 'Se o pagamento já foi realizado, desconsidere este aviso.');
+    return parts.join('\n');
+}
+//# sourceMappingURL=email-layout.js.map

package/dist/collection/email-layout.js.map

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

package/dist/collection/engine.d.ts

@@ -0,0 +1,177 @@
+import type { Tx } from '../db/client.js';
+import { type CollectionPolicy, type CollectionStep } from './policy.js';
+import type { TenantBranding } from './branding.js';
+import type { PaymentBlock } from './payment-block.js';
+import { type ChannelAccountStore, type ChannelPolicy, type ChannelRegistry as CommChannelRegistry, type CommunicationAuditSink, type ConsentPolicy, type ConsentStore, type DispatchClaimStore, type SenderOrigin, type TemplateStore } from '../communication/index.js';
+import { type CollectionActionRecord } from './repository.js';
+export interface PlanReport {
+    examined: number;
+    scheduled: number;
+    skippedAlreadyHandled: number;
+    canceledByPayment: number;
+    canceledByCancellation: number;
+}
+/**
+ * Planeja: cancela o que não deve mais sair e agenda o que a régua manda.
+ *
+ * A ordem importa. Cancelar ANTES de agendar evita a janela em que um recebível
+ * pago recebe uma etapa nova no mesmo ciclo.
+ */
+export declare function planCollections(tx: Tx, today: string, policyOverride?: CollectionPolicy): Promise<PlanReport>;
+export interface ExecuteReport {
+    attempted: number;
+    sent: number;
+    failedTemporary: number;
+    failedPermanent: number;
+    skippedNoLongerDue: number;
+    skippedNoChannel: number;
+    escalated: number;
+}
+export interface ExecuteContext {
+    /** Identidade visual e dados de contato do escritório. */
+    branding: TenantBranding;
+    /** Resolve o destinatário lógico do cliente para o canal. */
+    resolveRecipient: (clientId: string, channel: string) => Promise<string | null>;
+    /** Descrição do recebível, para identificar a dívida sem inventar dado. */
+    describeReceivable?: (receivableId: string) => Promise<string | null>;
+    /**
+     * Como pagar este recebível, se já houver cobrança emitida.
+     *
+     * Opcional, e resolvido no momento do envio — não no agendamento. Entre um e
+     * outro passam dias: a cobrança pode ter sido criada depois, cancelada, ou o
+     * escritório pode ter conectado a conta de pagamento no meio. Congelar o link
+     * no agendamento mandaria o cliente para uma cobrança que não existe mais.
+     */
+    resolvePayment?: (receivableId: string) => Promise<PaymentBlock | null>;
+    /**
+     * Entrega pelo motor compartilhado do ecossistema. **Obrigatória.**
+     *
+     * Era opcional, e o opcional era o defeito. Enquanto este campo pôde faltar,
+     * havia um segundo caminho de envio — `channels` legado, HTML pronto, e-mail
+     * direto pelo Resend — com uma idempotência PRÓPRIA (`receivableId:stepKey`,
+     * que não era gravada em lugar nenhum). O cron usava um caminho, a rota
+     * manual usava o outro, e a proteção de cada um era invisível para o outro: os
+     * dois podiam enviar a mesma etapa no mesmo minuto.
+     *
+     * Sem `?`, o compilador recusa qualquer chamador que tente enviar por fora.
+     * A montagem canônica está em `communication-runtime.ts`, e ela é a única.
+     */
+    communication: CollectionCommunication;
+}
+/**
+ * O que a régua precisa fornecer para falar com o motor compartilhado.
+ *
+ * A SC não monta o `CommunicationIntent` à mão em cada etapa: ela declara uma
+ * vez de onde vêm contas, templates e consentimento, e o adaptador abaixo faz a
+ * tradução — que é o que impede o vocabulário de cobrança de vazar para o motor
+ * e o vocabulário do motor de vazar para a régua.
+ */
+export interface CollectionCommunication {
+    tenantId: string;
+    /** Marca do escritório. Distinta do tenant: um tenant pode operar sob mais de uma. */
+    brand: string;
+    channels: CommChannelRegistry;
+    accounts: ChannelAccountStore;
+    templates: TemplateStore;
+    consent: ConsentStore;
+    consentPolicy?: ConsentPolicy;
+    /**
+     * Canais a tentar, por etapa. Política do ESCRITÓRIO — o motor só executa.
+     *
+     * Recebe a etapa inteira, e não só a chave, para que a régua possa decidir por
+     * tom (uma etapa `reminder` pode preferir WhatsApp; uma `overdue_collection`,
+     * e-mail com trilha). Sem isto, o canal declarado no passo é o único usado.
+     */
+    policyFor?: (step: CollectionStep) => ChannelPolicy;
+    /**
+     * Reserva atômica do direito de enviar. Substitui `alreadySent`.
+     *
+     * A consulta antiga respondia "já enviei?" e devolvia um booleano — e entre a
+     * resposta e o envio havia uma janela em que a resposta continuava valendo
+     * para todo mundo que perguntasse. A reserva não responde: ela DECIDE, uma vez
+     * só, e só um chamador ganha. Ver `communication/claim.ts`.
+     */
+    claims: DispatchClaimStore;
+    /** Trilha estruturada do motor. Ver `communication/audit.ts`. */
+    audit: CommunicationAuditSink;
+    /**
+     * De onde veio o remetente de e-mail resolvido para este tenant.
+     *
+     * Vai para a trilha do ciclo. "Saiu pelo remetente da plataforma" tem de ser
+     * uma coisa que o escritório consegue ver, e não uma linha de código.
+     */
+    emailSenderOrigin?: SenderOrigin | null;
+    /** Percorre tudo e relata, sem chamar adapter nenhum e sem reservar chave. */
+    dryRun?: boolean;
+}
+/**
+ * Executa as ações vencidas.
+ *
+ * **Revalida o estado no momento do envio.** O agendamento pode ter dias; entre
+ * ele e agora o cliente pode ter pago, o recebível pode ter sido cancelado, ou
+ * uma baixa parcial pode ter mudado o valor. Confiar no que foi agendado é como
+ * o motor manda cobrança de dívida quitada.
+ */
+export declare function executeCollections(tx: Tx, ctx: ExecuteContext, today: string, policyOverride?: CollectionPolicy): Promise<ExecuteReport>;
+export interface CollectionCycleReport extends PlanReport, ExecuteReport {
+}
+/** Ciclo completo — o que o job roda. */
+export declare function runCollectionCycle(tx: Tx, ctx: ExecuteContext, today: string): Promise<CollectionCycleReport>;
+export type { CollectionActionRecord };
+/**
+ * Desliga a régua de um recebível que acabou de ser quitado.
+ *
+ * Existe porque a baixa passou a ter dois caminhos: o job diário, que varre
+ * todos os recebíveis, e o webhook, que sabe exatamente qual foi pago. Sem esta
+ * função o webhook baixaria o valor e deixaria a comunicação agendada — o
+ * cliente pagaria e receberia a cobrança de atraso mesmo assim, que é a pior
+ * falha possível numa régua automática.
+ *
+ * Só o que ainda não saiu é cancelado. Mensagem enviada é histórico.
+ */
+export declare function cancelDunningForSettled(tx: Tx, receivableId: string): Promise<number>;
+/**
+ * Religa a régua de um recebível cuja liquidação foi anulada.
+ *
+ * Sem isto, corrigir o saldo não bastaria: `planCollections` não reagenda um
+ * passo cujo `step_key` já existe na tabela — a idempotência olha a EXISTÊNCIA
+ * da linha, não o status dela. Os passos desligados pela baixa ficariam
+ * `canceled` para sempre, e o cliente voltaria a dever sem que ninguém jamais o
+ * lembrasse. O saldo estaria certo e a cobrança nunca aconteceria.
+ *
+ * Reabre **somente** o que foi fechado POR PAGAMENTO. Um passo cancelado porque
+ * o recebível foi cancelado, ou já enviado, é história e permanece intocado —
+ * reabrir tudo faria a régua reenviar mensagem que o cliente já recebeu.
+ */
+/**
+ * Religa etapas fechadas por FALHA DE INFRAESTRUTURA, nunca por decisão humana.
+ *
+ * Existe para o resíduo do incidente C1-PROV-R1B-C2: etapas que o motor fechou
+ * como `escalated` porque o canal ficou indisponível (cofre de credenciais fora
+ * do ar). A correção em `sendViaSharedEngine` impede que isso volte a
+ * acontecer, mas não desfaz o que já foi fechado — e nada mais no domínio
+ * consegue, porque `planCollections` não reagenda um `step_key` existente e
+ * `listActions` só enxerga `scheduled`.
+ *
+ * As guardas são deliberadamente estreitas, e cada uma exclui uma classe:
+ *
+ * - `closed_reason = 'escalated'` — deixa de fora `no_contact_data`,
+ *   `opted_out`, `consent_unknown`, `paid`, `canceled`, `rule_disabled` e
+ *   `permanent_failure`. Todas são decisão de negócio e permanecem terminais.
+ * - `attempts = 0` — `markEscalated` NUNCA incrementa `attempts`, enquanto
+ *   `markSent` e `markFailed` sempre incrementam. Zero prova que nenhum adapter
+ *   chegou a tentar.
+ * - `provider_ref IS NULL` e `sent_at IS NULL` — prova que nada saiu. Uma
+ *   mensagem entregue jamais é reaberta, e o cliente nunca recebe duplicata.
+ *
+ * O `step_key` é obrigatório: recuperação é pontual e auditável, nunca
+ * "reabra tudo deste recebível".
+ *
+ * O histórico da falha NÃO é apagado. `communication_event`
+ * (`dispatch_skipped` / `no_credential`) e `communication_dispatch`
+ * (`failed_retryable`) continuam intactos — esta função move apenas o estado da
+ * régua, e `last_error` registra a origem da reabertura.
+ */
+export declare function rearmDunningAfterInfraFailure(tx: Tx, receivableId: string, stepKey: string, incidentRef: string): Promise<number>;
+export declare function rearmDunningAfterReversal(tx: Tx, receivableId: string): Promise<number>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/collection/engine.d.ts.map

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