@baruk/core 0.3.0 → 0.4.2

package/dist/collection/subject.js

@@ -0,0 +1,99 @@
+/**
+ * Quem é o ASSUNTO de uma cobrança — e se existe um.
+ *
+ * ## O falso positivo que este módulo existe para matar
+ *
+ * O preflight de envio avulso respondia `eligible: true` medindo seis portas —
+ * identidade, credencial, destinatário, telefone, consentimento, template — e
+ * nenhuma delas pergunta **sobre o quê** a mensagem falaria. Um cliente sem
+ * recebível nenhum passava nas seis, e a rota de envio recusava logo depois por
+ * falta de valor e vencimento.
+ *
+ * Um preflight que aprova o que a execução recusa é pior que não ter preflight:
+ * ele desloca a descoberta do defeito para o momento do disparo, que é
+ * exatamente onde ninguém quer descobrir nada.
+ *
+ * ## Por que aqui, e não no handler
+ *
+ * "Este recebível está devido na etapa D+3 hoje?" é regra da RÉGUA. Ela já vive
+ * em `policy.ts` (`dueSteps`, `scheduledDateFor`) e em `engine.ts`
+ * (`isCollectible`), e é usada pelo ciclo automático. Reimplementar a mesma
+ * conta dentro de uma rota criaria a segunda derivação de sempre — as duas
+ * concordariam no dia da escrita e divergiriam na primeira mudança da régua,
+ * com o avulso mandando o que o ciclo não mandaria.
+ *
+ * Este módulo não decide política nova: ele **lê** a política vigente e responde
+ * quem ela alcança, sem escrever nada.
+ */
+import { listReceivables } from '../billing/ar-repository.js';
+import { dueSteps } from './policy.js';
+import { getCollectionPolicy, handledStepKeys } from './repository.js';
+/**
+ * Um recebível ainda merece cobrança?
+ *
+ * Cópia deliberada da regra de `engine.ts`, que era privada. Exportar de lá e
+ * importar aqui criaria ciclo (`engine` já importa deste módulo o suficiente);
+ * a duplicação é de UMA função pequena e está coberta pelo teste de
+ * equivalência em `collection-subject.test.ts`, que exercita as duas contra os
+ * mesmos casos.
+ */
+export function isCollectibleSubject(r) {
+    if (r.status === 'paid' || r.status === 'canceled')
+        return false;
+    if (r.status === 'renegotiated' || r.status === 'written_off')
+        return false;
+    // Saldo zero sem status `paid` é quem já pagou e o status não foi reavaliado.
+    // Cobrar aqui é o pior erro operacional deste motor.
+    if (r.outstandingAmount <= 0)
+        return false;
+    if (!r.dueDate)
+        return false;
+    return true;
+}
+/**
+ * Os recebíveis do cliente que a etapa alcança HOJE.
+ *
+ * Vazio quer dizer "não há sobre o que cobrar nesta etapa", e é um desfecho
+ * legítimo — não um erro. Cabe a quem chama transformar isso em recusa.
+ *
+ * A ordem é a mesma da régua (vencimento mais antigo primeiro), para que o
+ * avulso e o ciclo escolham o mesmo quando houver mais de um.
+ */
+export async function findEligibleSubjects(tx, q) {
+    const policy = q.policy ?? (await getCollectionPolicy(tx));
+    /*
+     * Nenhuma checagem própria de política ou de etapa aqui.
+     *
+     * A primeira versão tinha duas — "a régua está ativa" e "a etapa existe e
+     * está ativa" — e o teste de mutação derrubou as duas: removê-las não quebrava
+     * caso nenhum, porque `dueSteps` já decide exatamente isso. Guard que nenhum
+     * teste consegue distinguir não é guard: é uma segunda codificação da mesma
+     * regra, esperando para divergir da primeira.
+     *
+     * O que sobra deste módulo é o que ele de fato acrescenta: recortar por
+     * cliente, aplicar `isCollectibleSubject` e perguntar à régua. `dueSteps`
+     * continua sendo a única autoridade sobre quando uma etapa vence.
+     */
+    const { items } = await listReceivables(tx, { clientId: q.clientId, limit: 200 });
+    const elegiveis = [];
+    for (const r of items) {
+        if (!isCollectibleSubject(r))
+            continue;
+        const handled = await handledStepKeys(tx, r.id);
+        const due = dueSteps(policy, r.dueDate, q.today, handled);
+        if (due.some((d) => d.step.key === q.stepKey))
+            elegiveis.push(r);
+    }
+    return elegiveis;
+}
+/**
+ * O assunto que o envio avulso usaria, ou `null`.
+ *
+ * Quando há mais de um, o mais antigo — mesma preferência da régua. Escolher o
+ * mais recente faria a dívida velha envelhecer sem cobrança.
+ */
+export async function resolveSubjectForStep(tx, q) {
+    const todos = await findEligibleSubjects(tx, q);
+    return todos[0] ?? null;
+}
+//# sourceMappingURL=subject.js.map

package/dist/collection/subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/collection/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,eAAe,EAA8B,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAyB,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAwB;IAC3D,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,CAAC,CAAC,MAAM,KAAK,cAAc,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,KAAK,CAAC;IAC5E,8EAA8E;IAC9E,qDAAqD;IACrD,IAAI,CAAC,CAAC,iBAAiB,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAM,EACN,CAAuB;IAEvB,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,mBAAmB,CAAC,EAAE,CAAC,CAAC,CAAC;IAE3D;;;;;;;;;;;;OAYG;IAEH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAElF,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAAE,SAAS;QACvC,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC3D,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAM,EACN,CAAuB;IAEvB,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC1B,CAAC"}

package/dist/collection/template-catalog.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Catálogo de templates da COBRANÇA — do produto, não do motor.
+ *
+ * O motor sabe resolver template (escopo, versão, aprovação); ele não conhece
+ * nenhum. Os textos e os nomes registrados no provider vivem aqui, ao lado da
+ * régua que os usa.
+ *
+ * O corpo dos e-mails continua vindo de `copy.ts`/`email-layout.ts`: este
+ * catálogo declara QUAL template vale para cada etapa e canal, e as variáveis
+ * que ele consome. Duplicar o texto aqui criaria duas fontes para a mesma
+ * mensagem, e a segunda ficaria para trás na primeira correção.
+ */
+import type { Tx } from '../db/client.js';
+import type { TemplateStore } from '../communication/index.js';
+export declare function createCollectionTemplateStore(tx: Tx): TemplateStore;
+//# sourceMappingURL=template-catalog.d.ts.map

package/dist/collection/template-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-catalog.d.ts","sourceRoot":"","sources":["../../src/collection/template-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAA8B,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA6I3F,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,EAAE,GAAG,aAAa,CAsBnE"}

package/dist/collection/template-catalog.js

@@ -0,0 +1,162 @@
+/**
+ * Catálogo de templates da COBRANÇA — do produto, não do motor.
+ *
+ * O motor sabe resolver template (escopo, versão, aprovação); ele não conhece
+ * nenhum. Os textos e os nomes registrados no provider vivem aqui, ao lado da
+ * régua que os usa.
+ *
+ * O corpo dos e-mails continua vindo de `copy.ts`/`email-layout.ts`: este
+ * catálogo declara QUAL template vale para cada etapa e canal, e as variáveis
+ * que ele consome. Duplicar o texto aqui criaria duas fontes para a mesma
+ * mensagem, e a segunda ficaria para trás na primeira correção.
+ */
+import { SC_PRODUCT } from './communication-bridge.js';
+const LOCALE = 'pt-BR';
+/**
+ * Variáveis da cobrança, na ordem em que os templates de WhatsApp as declaram.
+ *
+ * A ordem é contrato com o template aprovado no provider: `{{1}}` é o nome,
+ * `{{2}}` o valor, `{{3}}` o vencimento. Trocar a ordem aqui sem re-aprovar o
+ * template lá manda o valor no lugar do nome — e a Meta aceita, porque para ela
+ * são três strings.
+ */
+const COLLECTION_VARS = ['clientName', 'amount', 'dueDate'];
+/**
+ * Sufixo do nome REGISTRADO NO PROVIDER.
+ *
+ * Muda **somente** quando um template novo é submetido e aprovado do lado da
+ * Meta. Mexer aqui sem submeter faz o despacho pedir um nome que não existe — e
+ * a Meta responde `132001`, que fala de "translation" e manda quem investiga
+ * procurar no lugar errado.
+ */
+const PROVIDER_TEMPLATE_SUFFIX = 'v1';
+/**
+ * Revisão INTERNA do catálogo de WhatsApp. **Nunca chega ao provider.**
+ *
+ * Entra na chave de idempotência (`buildIdempotencyKey` recebe
+ * `templateVersion`), e é o único jeito legítimo de dizer "esta é outra
+ * tentativa lógica" sem tocar no template aprovado.
+ *
+ * ## Por que os dois existem separados
+ *
+ * Eram dois literais `'v1'` — um em `version`, outro dentro da interpolação de
+ * `providerTemplateName` —, independentes de fato e idênticos na aparência. A
+ * primeira pessoa que precisasse de uma chave nova bumparia o que estivesse
+ * mais à mão, e havia 50% de chance de o despacho passar a pedir
+ * `billing_dunning_dplus3_v2` à Meta, que não tem esse template.
+ *
+ * `v2` aqui porque a revisão `v1` foi consumida: em 2026-09-01 a primeira
+ * tentativa real assentou a chave como `failed_permanent`, e o motor recusa
+ * repetição sobre chave assentada — corretamente. O template aprovado continua
+ * sendo `billing_dunning_dplus3_v1`.
+ *
+ * E-mail e SMS **não** bumpam: os dois têm despacho real em produção, e mudar a
+ * versão deles reabriria chaves já assentadas de 89 avisos que já saíram.
+ */
+const WHATSAPP_CATALOG_REVISION = 'v2';
+/**
+ * E-mail: sempre disponível, porque o corpo é montado pelo produto.
+ *
+ * `approved` aqui não significa "aprovado por um provider" — e-mail não tem
+ * registro prévio. Significa "utilizável", que é o que o motor precisa saber.
+ */
+function emailTemplate(eventType) {
+    return {
+        tenantId: null,
+        product: SC_PRODUCT,
+        brand: null,
+        channel: 'email',
+        eventType,
+        locale: LOCALE,
+        version: 'v1',
+        status: 'approved',
+        variables: [...COLLECTION_VARS],
+    };
+}
+/**
+ * WhatsApp: só existe se o escritório tiver registrado o template no provider.
+ *
+ * O nome segue o evento (`billing.dunning.dplus3` → `billing_dunning_dplus3_v1`)
+ * porque é a única convenção que não exige uma segunda tabela de-para que
+ * alguém precisaria manter sincronizada com o painel da Meta.
+ *
+ * **Não é declarado aprovado por padrão.** Um template que este código afirma
+ * existir e que ninguém registrou vira recusa do provider a cada etapa da régua
+ * — e a recusa chega como falha de entrega, sugerindo problema no cliente.
+ */
+function whatsappTemplate(eventType, approved) {
+    return {
+        tenantId: null,
+        product: SC_PRODUCT,
+        brand: null,
+        channel: 'whatsapp',
+        eventType,
+        locale: LOCALE,
+        // Revisão interna — some antes da fronteira do provider.
+        version: WHATSAPP_CATALOG_REVISION,
+        status: approved ? 'approved' : 'pending_approval',
+        // Nome no provider — o sufixo é o do TEMPLATE APROVADO, não o da revisão.
+        providerTemplateName: `${eventType.replace(/\./g, '_')}_${PROVIDER_TEMPLATE_SUFFIX}`,
+        variables: [...COLLECTION_VARS],
+    };
+}
+function smsTemplate(eventType, approved) {
+    return {
+        tenantId: null,
+        product: SC_PRODUCT,
+        brand: null,
+        channel: 'sms',
+        eventType,
+        locale: LOCALE,
+        version: 'v1',
+        status: approved ? 'approved' : 'pending_approval',
+        variables: [...COLLECTION_VARS],
+        // Curto de propósito: cada segmento é cobrado, e o link é o que faz o
+        // cliente agir. Sem link, a mensagem só informa.
+        body: '{{clientName}}, consta {{amount}} com vencimento {{dueDate}}.',
+    };
+}
+/**
+ * Quais eventos o escritório tem registrados em cada canal.
+ *
+ * Vem de `tenant.settings.channels.<canal>.approvedEvents`. Ausente = nenhum, e
+ * o e-mail segue funcionando: ligar um canal novo nunca pode desligar o que já
+ * funcionava.
+ */
+// `tenant` não tem RLS — é a tabela raiz, define a fronteira em vez de ser
+// protegida por ela. Toda leitura dela exige a amarra explícita na GUC da
+// sessão; sem isso, o `tenantId` do parâmetro é a única coisa que separa um
+// escritório do outro, e um parâmetro não é uma fronteira.
+async function approvedEvents(tx, tenantId, channel) {
+    const rows = await tx `
+    SELECT settings FROM tenant
+     WHERE id = ${tenantId}
+       AND id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+     LIMIT 1
+  `;
+    const channels = (rows[0]?.settings?.channels ?? {});
+    const list = channels[channel]?.approvedEvents;
+    return new Set(Array.isArray(list) ? list.filter((v) => typeof v === 'string') : []);
+}
+export function createCollectionTemplateStore(tx) {
+    return {
+        async candidates(ctx, channel, eventType, locale) {
+            if (ctx.product !== SC_PRODUCT || locale !== LOCALE)
+                return [];
+            if (channel === 'email')
+                return [emailTemplate(eventType)];
+            if (channel === 'whatsapp') {
+                const approved = await approvedEvents(tx, ctx.tenantId, 'whatsapp');
+                return [whatsappTemplate(eventType, approved.has(eventType))];
+            }
+            if (channel === 'sms') {
+                const approved = await approvedEvents(tx, ctx.tenantId, 'sms');
+                return [smsTemplate(eventType, approved.has(eventType))];
+            }
+            // `notification` é evento interno e não passa pelo motor: a régua o
+            // resolve antes, escalando para a fila humana sem mensagem ao cliente.
+            return [];
+        },
+    };
+}
+//# sourceMappingURL=template-catalog.js.map

package/dist/collection/template-catalog.js.map

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

package/dist/collection/template.d.ts

@@ -0,0 +1,37 @@
+import type { StepTone } from './policy.js';
+/**
+ * Templates de cobrança.
+ *
+ * Substituição é por ALLOWLIST de variáveis, não por interpolação livre: o
+ * template vem de configuração de tenant, e um `${...}` avaliado seria execução
+ * arbitrária a partir de dado editável pelo usuário. Aqui, `{{x}}` só resolve se
+ * `x` estiver na lista; qualquer outra coisa fica literal e visível — falha à
+ * vista, nunca silenciosa.
+ */
+export interface TemplateVars {
+    clientName: string;
+    officeName: string;
+    dueDate: string;
+    outstandingAmount: string;
+    reference: string;
+}
+export declare const TEMPLATE_VARIABLES: readonly (keyof TemplateVars)[];
+export interface CollectionTemplate {
+    subject: string;
+    body: string;
+}
+/**
+ * Textos padrão por tom.
+ *
+ * Nenhum deles ameaça, cita medida judicial, negativação ou consequência legal.
+ * Cobrança automatizada que produz esse tipo de texto sem revisão humana é risco
+ * jurídico e de relacionamento — a etapa mais dura da régua padrão escala para
+ * uma pessoa em vez de escrever por conta própria.
+ */
+declare const DEFAULT_TEMPLATES: Record<string, CollectionTemplate>;
+/** Resolve o template; cai no padrão do tom quando o tenant não tem o seu. */
+export declare function resolveTemplate(templateKey: string, tone: StepTone, overrides?: Record<string, CollectionTemplate>): CollectionTemplate;
+/** Substitui `{{var}}` pelas variáveis da allowlist. O resto fica literal. */
+export declare function renderTemplate(text: string, vars: TemplateVars): string;
+export { DEFAULT_TEMPLATES };
+//# sourceMappingURL=template.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/collection/template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,CAAC,MAAM,YAAY,CAAC,EAM7D,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,QAAA,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAyCzD,CAAC;AAUF,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,QAAQ,EACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAC7C,kBAAkB,CAMpB;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAMvE;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/collection/template.js

@@ -0,0 +1,73 @@
+export const TEMPLATE_VARIABLES = [
+    'clientName',
+    'officeName',
+    'dueDate',
+    'outstandingAmount',
+    'reference',
+];
+/**
+ * Textos padrão por tom.
+ *
+ * Nenhum deles ameaça, cita medida judicial, negativação ou consequência legal.
+ * Cobrança automatizada que produz esse tipo de texto sem revisão humana é risco
+ * jurídico e de relacionamento — a etapa mais dura da régua padrão escala para
+ * uma pessoa em vez de escrever por conta própria.
+ */
+const DEFAULT_TEMPLATES = {
+    'collection.reminder': {
+        subject: 'Lembrete: vencimento em {{dueDate}}',
+        body: 'Olá, {{clientName}}.\n\n' +
+            'Passando para lembrar que o valor de {{outstandingAmount}} vence em {{dueDate}}.\n' +
+            'Referência: {{reference}}.\n\n' +
+            'Se já tiver pago, desconsidere esta mensagem.\n\n{{officeName}}',
+    },
+    'collection.due': {
+        subject: 'Vence hoje: {{outstandingAmount}}',
+        body: 'Olá, {{clientName}}.\n\n' +
+            'O valor de {{outstandingAmount}} vence hoje ({{dueDate}}).\n' +
+            'Referência: {{reference}}.\n\n' +
+            'Se já tiver pago, desconsidere esta mensagem.\n\n{{officeName}}',
+    },
+    'collection.overdue_soft': {
+        subject: 'Pendência em aberto — {{reference}}',
+        body: 'Olá, {{clientName}}.\n\n' +
+            'Consta em aberto o valor de {{outstandingAmount}}, com vencimento em {{dueDate}}.\n' +
+            'Se o pagamento já foi feito, por favor nos avise para darmos baixa.\n\n' +
+            'Qualquer dúvida, estamos à disposição.\n\n{{officeName}}',
+    },
+    'collection.overdue': {
+        subject: 'Pendência em aberto desde {{dueDate}}',
+        body: 'Olá, {{clientName}}.\n\n' +
+            'O valor de {{outstandingAmount}}, vencido em {{dueDate}}, segue em aberto.\n' +
+            'Referência: {{reference}}.\n\n' +
+            'Pedimos que entre em contato para regularizarmos ou combinarmos a melhor forma.\n\n' +
+            '{{officeName}}',
+    },
+    // Interno: nunca vai ao cliente. Ver a nota em `policy.ts`.
+    'collection.escalate': {
+        subject: 'Cobrança escalada para atendimento humano — {{clientName}}',
+        body: 'A régua automática chegou ao fim para {{clientName}} ({{reference}}), com ' +
+            '{{outstandingAmount}} em aberto desde {{dueDate}}. A partir daqui a condução é humana.',
+    },
+};
+const TONE_FALLBACK = {
+    reminder: 'collection.reminder',
+    due_notice: 'collection.due',
+    friendly_collection: 'collection.overdue_soft',
+    overdue_collection: 'collection.overdue',
+    human_escalation: 'collection.escalate',
+};
+/** Resolve o template; cai no padrão do tom quando o tenant não tem o seu. */
+export function resolveTemplate(templateKey, tone, overrides) {
+    return (overrides?.[templateKey] ??
+        DEFAULT_TEMPLATES[templateKey] ??
+        DEFAULT_TEMPLATES[TONE_FALLBACK[tone]]);
+}
+/** Substitui `{{var}}` pelas variáveis da allowlist. O resto fica literal. */
+export function renderTemplate(text, vars) {
+    return text.replace(/\{\{\s*([a-zA-Z]+)\s*\}\}/g, (whole, name) => TEMPLATE_VARIABLES.includes(name)
+        ? String(vars[name] ?? '')
+        : whole);
+}
+export { DEFAULT_TEMPLATES };
+//# sourceMappingURL=template.js.map

package/dist/collection/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/collection/template.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,kBAAkB,GAAoC;IACjE,YAAY;IACZ,YAAY;IACZ,SAAS;IACT,mBAAmB;IACnB,WAAW;CACZ,CAAC;AAOF;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAuC;IAC5D,qBAAqB,EAAE;QACrB,OAAO,EAAE,qCAAqC;QAC9C,IAAI,EACF,0BAA0B;YAC1B,oFAAoF;YACpF,gCAAgC;YAChC,iEAAiE;KACpE;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,mCAAmC;QAC5C,IAAI,EACF,0BAA0B;YAC1B,8DAA8D;YAC9D,gCAAgC;YAChC,iEAAiE;KACpE;IACD,yBAAyB,EAAE;QACzB,OAAO,EAAE,qCAAqC;QAC9C,IAAI,EACF,0BAA0B;YAC1B,qFAAqF;YACrF,yEAAyE;YACzE,0DAA0D;KAC7D;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE,uCAAuC;QAChD,IAAI,EACF,0BAA0B;YAC1B,8EAA8E;YAC9E,gCAAgC;YAChC,qFAAqF;YACrF,gBAAgB;KACnB;IACD,4DAA4D;IAC5D,qBAAqB,EAAE;QACrB,OAAO,EAAE,4DAA4D;QACrE,IAAI,EACF,4EAA4E;YAC5E,wFAAwF;KAC3F;CACF,CAAC;AAEF,MAAM,aAAa,GAA6B;IAC9C,QAAQ,EAAE,qBAAqB;IAC/B,UAAU,EAAE,gBAAgB;IAC5B,mBAAmB,EAAE,yBAAyB;IAC9C,kBAAkB,EAAE,oBAAoB;IACxC,gBAAgB,EAAE,qBAAqB;CACxC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAC7B,WAAmB,EACnB,IAAc,EACd,SAA8C;IAE9C,OAAO,CACL,SAAS,EAAE,CAAC,WAAW,CAAC;QACxB,iBAAiB,CAAC,WAAW,CAAC;QAC9B,iBAAiB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAE,CACxC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAkB;IAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,4BAA4B,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CACvE,kBAAwC,CAAC,QAAQ,CAAC,IAAI,CAAC;QACtD,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAA0B,CAAC,IAAI,EAAE,CAAC;QAChD,CAAC,CAAC,KAAK,CACV,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/communication/adapters/email.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Adapter de e-mail — envelope do envio que o Office já usa.
+ *
+ * **Nenhum motor novo de e-mail.** Convites, ativação, recuperação de senha e a
+ * régua de cobrança já passam por `mail/resend.ts`. Este adapter apenas o expõe
+ * sob o contrato multicanal, para que o e-mail seja UM canal entre outros em vez
+ * de o caminho especial que todos os outros tentam imitar.
+ *
+ * A supressão em teste continua onde estava, no `sendEmail` do core: uma guarda
+ * que mora no adapter é uma guarda que o próximo adapter esquece.
+ */
+import type { CommunicationChannel } from '../channel.js';
+import type { ChannelAccount } from '../identity.js';
+export interface EmailAdapterConfig {
+    /** Conta do tenant, resolvida ANTES pelo motor. Ver `identity.ts`. */
+    account: ChannelAccount;
+    /**
+     * Resolve o valor da credencial a partir da referência lógica.
+     *
+     * Recebe `account.credentialRef` e devolve o segredo. O segredo entra no
+     * adapter e morre nele: nunca é devolvido, logado nem anexado ao desfecho.
+     */
+    resolveCredential: (ref: string) => Promise<string | undefined>;
+    /** Injetável para teste. Nenhum teste deve alcançar a rede real. */
+    fetchImpl?: typeof fetch;
+}
+export declare function createEmailChannel(config: EmailAdapterConfig): CommunicationChannel;
+//# sourceMappingURL=email.d.ts.map

package/dist/communication/adapters/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../../src/communication/adapters/email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAoC,MAAM,eAAe,CAAC;AAE5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAyBrD,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,OAAO,EAAE,cAAc,CAAC;IACxB;;;;;OAKG;IACH,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,oBAAoB,CAyGnF"}

package/dist/communication/adapters/email.js

@@ -0,0 +1,129 @@
+/**
+ * Adapter de e-mail — envelope do envio que o Office já usa.
+ *
+ * **Nenhum motor novo de e-mail.** Convites, ativação, recuperação de senha e a
+ * régua de cobrança já passam por `mail/resend.ts`. Este adapter apenas o expõe
+ * sob o contrato multicanal, para que o e-mail seja UM canal entre outros em vez
+ * de o caminho especial que todos os outros tentam imitar.
+ *
+ * A supressão em teste continua onde estava, no `sendEmail` do core: uma guarda
+ * que mora no adapter é uma guarda que o próximo adapter esquece.
+ */
+import { sendEmailWithResult } from '../../mail/resend.js';
+import { RESEND_IDEMPOTENCY_WINDOW_MS } from '../capabilities.js';
+/**
+ * O que o Resend garante, e o que este adapter exerce.
+ *
+ * `supportsProviderIdempotency` é `true` porque o adapter MANDA a chave, não
+ * porque a documentação do fornecedor a menciona: a declaração descreve o código
+ * daqui. Enquanto a chave não era repassada — o estado que a segunda
+ * certificação encontrou —, declarar `true` teria sido documentar uma proteção
+ * inexistente.
+ *
+ * Os outros três são `false` por ausência de integração, não por ausência do
+ * fornecedor. O Resend publica webhooks de entrega e relata abertura; nenhuma
+ * rota daqui os consome hoje (a rota de callback existente é da Meta). Declarar a
+ * capacidade do fornecedor em vez da capacidade do código produziria exatamente
+ * a divergência entre documento e runtime que reprovou a rodada anterior.
+ */
+const RESEND_CAPABILITIES = {
+    supportsProviderIdempotency: true,
+    providerIdempotencyWindowMs: RESEND_IDEMPOTENCY_WINDOW_MS,
+    supportsMessageLookup: false,
+    supportsDeliveryWebhook: false,
+    supportsReadReceipt: false,
+};
+export function createEmailChannel(config) {
+    return {
+        key: 'email',
+        providerName: 'resend',
+        capabilities: RESEND_CAPABILITIES,
+        isConfigured(_ctx) {
+            return config.account.status === 'active' && Boolean(config.account.senderId);
+        },
+        async send(message) {
+            if (message.content.kind !== 'email') {
+                return { kind: 'permanent', code: 'content_mismatch', detail: 'conteúdo não é e-mail' };
+            }
+            const apiKey = await config.resolveCredential(config.account.credentialRef);
+            if (!apiKey) {
+                // Ausência de credencial é canal indisponível, não falha de entrega: não
+                // gasta tentativa e não marca o cliente como problema de cadastro.
+                return { kind: 'unavailable', code: 'no_credential', detail: 'credencial ausente' };
+            }
+            const from = config.account.displayName
+                ? `${config.account.displayName.replace(/["<>\\]/g, '').trim()} <${config.account.senderId}>`
+                : config.account.senderId;
+            const result = await sendEmailWithResult(apiKey, {
+                from,
+                to: message.to,
+                subject: message.content.subject,
+                html: message.content.html,
+                text: message.content.text,
+            }, {
+                /*
+                 * A chave do MOTOR, repassada ao provider.
+                 *
+                 * É a mesma em toda tentativa técnica do mesmo envio, porque é derivada
+                 * da intenção (tenant, produto, marca, canal, evento, assunto, versão
+                 * de template) e não da tentativa. Derivá-la aqui, ou embaralhá-la com
+                 * um contador de retry, teria o mecanismo ligado e proteção nenhuma: o
+                 * provider trataria cada retry como mensagem nova.
+                 *
+                 * Cabe no limite do provider por construção — a chave é um sha256 em
+                 * hexadecimal, 64 caracteres, e o Resend aceita de 1 a 256.
+                 */
+                idempotencyKey: message.idempotencyKey,
+                fetchImpl: config.fetchImpl,
+            });
+            if (result.ok)
+                return { kind: 'sent', providerRef: result.providerRef };
+            /*
+             * `409` é o mecanismo de idempotência falando, e a leitura correta não é
+             * "falhou".
+             *
+             * `invalid_idempotent_request`: esta chave já foi usada nas últimas 24h com
+             * um corpo diferente. Ou seja — houve uma chamada anterior aceita para esta
+             * mesma intenção. A mensagem SAIU. Tratar como falha devolveria a chave e a
+             * próxima rodada mandaria a segunda cobrança, que é precisamente o que a
+             * chave existe para impedir.
+             *
+             * `concurrent_idempotent_requests`: outra chamada com a mesma chave está em
+             * curso agora. Não é nosso caso comum (a reserva interna já barra isso
+             * antes), mas se acontecer, quem está enviando é a outra chamada — e
+             * reenviar por cima é o mesmo erro.
+             */
+            if (result.status === 409) {
+                return {
+                    kind: 'sent',
+                    code: 'provider_idempotent_replay',
+                    detail: 'provider já havia aceito esta chave',
+                };
+            }
+            // Chave fora do formato aceito é defeito de integração nosso, não do
+            // destinatário. `permanent` para não repetir a mesma chamada inválida em
+            // loop; o rótulo diz onde olhar.
+            if (result.errorCode === 'invalid_idempotency_key') {
+                return {
+                    kind: 'permanent',
+                    code: 'invalid_idempotency_key',
+                    detail: 'chave de idempotência recusada pelo provider',
+                };
+            }
+            // Sem credencial o canal está indisponível, não falho: não gasta tentativa
+            // e não acusa o cadastro do cliente.
+            if (result.localReason === 'no_credential') {
+                return { kind: 'unavailable', code: 'no_credential', detail: 'credencial ausente' };
+            }
+            // O resto — recusa do provider, supressão em teste, falha de rede — é
+            // TEMPORÁRIO. Marcar permanente encerraria a cobrança por algo que pode ser
+            // infraestrutura, e desistir cedo demais é pior que tentar de novo.
+            return {
+                kind: 'temporary',
+                code: result.errorCode ?? result.localReason ?? 'not_confirmed',
+                detail: 'provider não confirmou o envio',
+            };
+        },
+    };
+}
+//# sourceMappingURL=email.js.map

package/dist/communication/adapters/email.js.map

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