@baruk/core 0.3.1 → 0.5.0

package/dist/collection/format.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Apresentação para o cliente final.
+ *
+ * O armazenamento continua canônico — `date` ISO no banco, `numeric(14,2)` no
+ * valor. Isto aqui é só a camada de leitura humana: um contribuinte brasileiro
+ * lê "15/08/2026", não "2026-08-15", e converter no ponto de exibição evita
+ * mexer no dado por causa de idioma.
+ */
+/** `2026-08-15` → `15/08/2026`. Entrada inválida volta como veio. */
+export declare function formatDateBR(iso: string | null | undefined): string;
+/**
+ * Valor monetário em pt-BR.
+ *
+ * `Intl` normalmente devolve espaço não separável entre "R$" e o número, o que
+ * costuma virar caractere estranho em cliente de e-mail antigo. Montamos o
+ * texto à mão para garantir "R$ 1.234,56" em qualquer leitor.
+ */
+export declare function formatBRL(value: number): string;
+/** Dias de atraso em linguagem natural. */
+export declare function formatOverdue(days: number): string;
+/**
+ * Como a dívida é identificada para o cliente.
+ *
+ * "Referência: serviço avulso" não diz nada a quem recebe. Com competência,
+ * dizemos o mês; sem ela, usamos a descrição do que foi contratado. Nada é
+ * inventado — se não houver nem uma nem outra, o campo simplesmente não aparece.
+ */
+export declare function describeReference(input: {
+    competence?: string | null;
+    description?: string | null;
+}): string | null;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/collection/format.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GAAG,MAAM,GAAG,IAAI,CAwBhB"}

package/dist/collection/format.js

@@ -0,0 +1,70 @@
+/**
+ * Apresentação para o cliente final.
+ *
+ * O armazenamento continua canônico — `date` ISO no banco, `numeric(14,2)` no
+ * valor. Isto aqui é só a camada de leitura humana: um contribuinte brasileiro
+ * lê "15/08/2026", não "2026-08-15", e converter no ponto de exibição evita
+ * mexer no dado por causa de idioma.
+ */
+/** `2026-08-15` → `15/08/2026`. Entrada inválida volta como veio. */
+export function formatDateBR(iso) {
+    if (!iso)
+        return '—';
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
+    return m ? `${m[3]}/${m[2]}/${m[1]}` : iso;
+}
+/**
+ * Valor monetário em pt-BR.
+ *
+ * `Intl` normalmente devolve espaço não separável entre "R$" e o número, o que
+ * costuma virar caractere estranho em cliente de e-mail antigo. Montamos o
+ * texto à mão para garantir "R$ 1.234,56" em qualquer leitor.
+ */
+export function formatBRL(value) {
+    const fixed = Math.abs(value).toFixed(2);
+    const [int, dec] = fixed.split('.');
+    const withThousands = int.replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+    return `${value < 0 ? '-' : ''}R$ ${withThousands},${dec}`;
+}
+/** Dias de atraso em linguagem natural. */
+export function formatOverdue(days) {
+    if (days <= 0)
+        return '';
+    if (days === 1)
+        return 'há 1 dia';
+    return `há ${days} dias`;
+}
+/**
+ * Como a dívida é identificada para o cliente.
+ *
+ * "Referência: serviço avulso" não diz nada a quem recebe. Com competência,
+ * dizemos o mês; sem ela, usamos a descrição do que foi contratado. Nada é
+ * inventado — se não houver nem uma nem outra, o campo simplesmente não aparece.
+ */
+export function describeReference(input) {
+    if (input.competence) {
+        const m = /^(\d{4})-(\d{2})$/.exec(input.competence);
+        if (m) {
+            const meses = [
+                'janeiro',
+                'fevereiro',
+                'março',
+                'abril',
+                'maio',
+                'junho',
+                'julho',
+                'agosto',
+                'setembro',
+                'outubro',
+                'novembro',
+                'dezembro',
+            ];
+            const idx = Number(m[2]) - 1;
+            if (idx >= 0 && idx < 12)
+                return `honorários de ${meses[idx]} de ${m[1]}`;
+        }
+        return `competência ${input.competence}`;
+    }
+    return input.description?.trim() || null;
+}
+//# sourceMappingURL=format.js.map

package/dist/collection/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/collection/format.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,GAA8B;IACzD,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,MAAM,CAAC,GAAG,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;IACxD,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IAChE,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,aAAa,IAAI,GAAG,EAAE,CAAC;AAC7D,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACzB,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAClC,OAAO,MAAM,IAAI,OAAO,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAGjC;IACC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,KAAK,GAAG;gBACZ,SAAS;gBACT,WAAW;gBACX,OAAO;gBACP,OAAO;gBACP,MAAM;gBACN,OAAO;gBACP,OAAO;gBACP,QAAQ;gBACR,UAAU;gBACV,SAAS;gBACT,UAAU;gBACV,UAAU;aACX,CAAC;YACF,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,EAAE;gBAAE,OAAO,iBAAiB,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,CAAC;QACD,OAAO,eAAe,KAAK,CAAC,UAAU,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;AAC3C,CAAC"}

package/dist/collection/payment-block.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Como o cliente paga — a verdade financeira que qualquer canal entrega.
+ *
+ * Mora aqui, e não no layout do e-mail, porque não é assunto do e-mail. O
+ * mesmo bloco alimenta WhatsApp, portal ou qualquer canal futuro: o motor de
+ * cobrança resolve o pagamento uma vez por recebível (`resolvePayment`), e cada
+ * canal decide como apresentar.
+ *
+ * A separação importa na prática: um canal que precisasse importar de
+ * `email-layout.ts` acabaria herdando decisões de renderização de e-mail — e a
+ * primeira regra de negócio duplicada dentro do canal seria a próxima.
+ *
+ * Tudo opcional porque cada gateway (e cada método) entrega um subconjunto
+ * diferente. Quem renderiza mostra o que veio; nada é inventado para preencher.
+ */
+export interface PaymentBlock {
+    /** Destino do CTA. Sem ele não há botão: um "Pagar agora" que não paga é pior que nada. */
+    url?: string;
+    pixPayload?: string;
+    pixQrCodeImage?: string;
+    boletoUrl?: string;
+    identificationField?: string;
+}
+//# sourceMappingURL=payment-block.d.ts.map

package/dist/collection/payment-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-block.d.ts","sourceRoot":"","sources":["../../src/collection/payment-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/collection/payment-block.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payment-block.js.map

package/dist/collection/payment-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-block.js","sourceRoot":"","sources":["../../src/collection/payment-block.ts"],"names":[],"mappings":""}

package/dist/collection/policy.d.ts

@@ -0,0 +1,78 @@
+import type { CollectionChannelKey } from './channel.js';
+/**
+ * Política de cobrança do escritório.
+ *
+ * Os offsets são RELATIVOS ao vencimento e vivem em `dunning_rule.steps` (jsonb,
+ * por tenant) — nenhum dia está no código. O padrão abaixo é ponto de partida
+ * para quem ainda não configurou nada, jamais política imposta.
+ */
+export type StepTiming = 'before_due' | 'on_due_date' | 'after_due';
+/** Tom da etapa. Governa o template, e serve de guarda contra escalada indevida. */
+export type StepTone = 'reminder' | 'due_notice' | 'friendly_collection' | 'overdue_collection' | 'human_escalation';
+export interface CollectionStep {
+    /** Chave estável — é o que garante idempotência. Mudar isto reexecuta a etapa. */
+    key: string;
+    timing: StepTiming;
+    /** Dias de distância do vencimento. Sempre positivo; `timing` dá o sinal. */
+    offsetDays: number;
+    channel: CollectionChannelKey;
+    tone: StepTone;
+    templateKey: string;
+    active?: boolean;
+}
+export interface CollectionPolicy {
+    id: string | null;
+    name: string;
+    steps: CollectionStep[];
+    active: boolean;
+}
+/**
+ * Régua padrão — sugestão, não regra do produto.
+ *
+ * Para a última etapa o canal é `notification`: escalar para humano é um evento
+ * INTERNO. Mandar ao cliente uma mensagem dizendo que o caso foi escalado seria
+ * transformar procedimento interno em pressão, e é exatamente onde cobrança
+ * automatizada vira problema jurídico e de relacionamento.
+ */
+export declare const DEFAULT_COLLECTION_STEPS: readonly CollectionStep[];
+export declare const DEFAULT_POLICY: CollectionPolicy;
+/** Data em que a etapa deve acontecer, dado o vencimento. */
+export declare function scheduledDateFor(step: CollectionStep, dueDate: string): string;
+/**
+ * Etapas já devidas em `today` e ainda não registradas.
+ *
+ * Pura e determinística: recebe o que já foi executado e devolve o que falta.
+ * Nenhum I/O — é o que permite testar a régua inteira sem banco nem provider.
+ */
+export declare function dueSteps(policy: CollectionPolicy, dueDate: string, today: string, alreadyHandled: ReadonlySet<string>): {
+    step: CollectionStep;
+    scheduledFor: string;
+}[];
+/**
+ * Canais que NÃO alcançam o cliente.
+ *
+ * `notification` é o canal do escalonamento para humano: a última etapa da régua
+ * padrão avisa a EQUIPE que o caso passou a ser conduzido manualmente. Está
+ * escrito ali em cima, na régua padrão: "escalar para humano é um evento
+ * INTERNO. Mandar ao cliente uma mensagem dizendo que o caso foi escalado seria"
+ * — e a frase termina em "constrangedor", que é a razão de ele não ser `email`.
+ *
+ * A lista é de canais INTERNOS, e não de canais "de WhatsApp", de propósito: o
+ * envio avulso força `order: ['whatsapp']` sobre etapas cujo canal é `email`, e
+ * exigir `channel === 'whatsapp'` aqui esvaziaria a régua inteira. O que decide
+ * não é por onde a etapa sairia, e sim PARA QUEM ela fala.
+ */
+export declare const INTERNAL_COLLECTION_CHANNELS: readonly CollectionChannelKey[];
+/**
+ * A etapa fala com o cliente?
+ *
+ * Existe porque, até aqui, o que impedia um aviso de escalonamento de chegar ao
+ * cliente era a ausência de template para ele do lado da Meta — barreira
+ * ACIDENTAL, que evaporaria no dia em que alguém registrasse esse template por
+ * qualquer outro motivo. A regra passa a ser de domínio, e não uma consequência
+ * do catálogo do provider.
+ */
+export declare function isCustomerFacingStep(step: Pick<CollectionStep, 'channel'>): boolean;
+/** Validação de política vinda do banco — protege contra jsonb malformado. */
+export declare function parsePolicySteps(raw: unknown): CollectionStep[];
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/collection/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,CAAC;AAEpE,oFAAoF;AACpF,MAAM,MAAM,QAAQ,GAClB,UAAU,GAAG,YAAY,GAAG,qBAAqB,GAAG,oBAAoB,GAAG,kBAAkB,CAAC;AAEhG,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,cAAc,EAiD7D,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAQF,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ9E;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAAE,CAQlD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,oBAAoB,EAAqB,CAAC;AAE9F;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,OAAO,CAEnF;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,EAAE,CAuC/D"}

package/dist/collection/policy.js

@@ -0,0 +1,168 @@
+/**
+ * Régua padrão — sugestão, não regra do produto.
+ *
+ * Para a última etapa o canal é `notification`: escalar para humano é um evento
+ * INTERNO. Mandar ao cliente uma mensagem dizendo que o caso foi escalado seria
+ * transformar procedimento interno em pressão, e é exatamente onde cobrança
+ * automatizada vira problema jurídico e de relacionamento.
+ */
+export const DEFAULT_COLLECTION_STEPS = [
+    {
+        key: 'D-3',
+        timing: 'before_due',
+        offsetDays: 3,
+        channel: 'email',
+        tone: 'reminder',
+        templateKey: 'collection.reminder',
+    },
+    {
+        key: 'D0',
+        timing: 'on_due_date',
+        offsetDays: 0,
+        channel: 'email',
+        tone: 'due_notice',
+        templateKey: 'collection.due',
+    },
+    {
+        key: 'D+3',
+        timing: 'after_due',
+        offsetDays: 3,
+        channel: 'email',
+        tone: 'friendly_collection',
+        templateKey: 'collection.overdue_soft',
+    },
+    {
+        key: 'D+7',
+        timing: 'after_due',
+        offsetDays: 7,
+        channel: 'email',
+        tone: 'friendly_collection',
+        templateKey: 'collection.overdue_soft',
+    },
+    {
+        key: 'D+15',
+        timing: 'after_due',
+        offsetDays: 15,
+        channel: 'email',
+        tone: 'overdue_collection',
+        templateKey: 'collection.overdue',
+    },
+    {
+        key: 'D+30',
+        timing: 'after_due',
+        offsetDays: 30,
+        channel: 'notification',
+        tone: 'human_escalation',
+        templateKey: 'collection.escalate',
+    },
+];
+export const DEFAULT_POLICY = {
+    id: null,
+    name: 'Régua padrão',
+    steps: [...DEFAULT_COLLECTION_STEPS],
+    active: true,
+};
+function addDays(isoDate, days) {
+    const d = new Date(`${isoDate}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+/** Data em que a etapa deve acontecer, dado o vencimento. */
+export function scheduledDateFor(step, dueDate) {
+    const offset = step.timing === 'before_due'
+        ? -Math.abs(step.offsetDays)
+        : step.timing === 'after_due'
+            ? Math.abs(step.offsetDays)
+            : 0;
+    return addDays(dueDate, offset);
+}
+/**
+ * Etapas já devidas em `today` e ainda não registradas.
+ *
+ * Pura e determinística: recebe o que já foi executado e devolve o que falta.
+ * Nenhum I/O — é o que permite testar a régua inteira sem banco nem provider.
+ */
+export function dueSteps(policy, dueDate, today, alreadyHandled) {
+    if (!policy.active)
+        return [];
+    return policy.steps
+        .filter((s) => s.active !== false)
+        .filter((s) => !alreadyHandled.has(s.key))
+        .map((step) => ({ step, scheduledFor: scheduledDateFor(step, dueDate) }))
+        .filter((s) => s.scheduledFor <= today)
+        .sort((a, b) => a.scheduledFor.localeCompare(b.scheduledFor));
+}
+/**
+ * Canais que NÃO alcançam o cliente.
+ *
+ * `notification` é o canal do escalonamento para humano: a última etapa da régua
+ * padrão avisa a EQUIPE que o caso passou a ser conduzido manualmente. Está
+ * escrito ali em cima, na régua padrão: "escalar para humano é um evento
+ * INTERNO. Mandar ao cliente uma mensagem dizendo que o caso foi escalado seria"
+ * — e a frase termina em "constrangedor", que é a razão de ele não ser `email`.
+ *
+ * A lista é de canais INTERNOS, e não de canais "de WhatsApp", de propósito: o
+ * envio avulso força `order: ['whatsapp']` sobre etapas cujo canal é `email`, e
+ * exigir `channel === 'whatsapp'` aqui esvaziaria a régua inteira. O que decide
+ * não é por onde a etapa sairia, e sim PARA QUEM ela fala.
+ */
+export const INTERNAL_COLLECTION_CHANNELS = ['notification'];
+/**
+ * A etapa fala com o cliente?
+ *
+ * Existe porque, até aqui, o que impedia um aviso de escalonamento de chegar ao
+ * cliente era a ausência de template para ele do lado da Meta — barreira
+ * ACIDENTAL, que evaporaria no dia em que alguém registrasse esse template por
+ * qualquer outro motivo. A regra passa a ser de domínio, e não uma consequência
+ * do catálogo do provider.
+ */
+export function isCustomerFacingStep(step) {
+    return !INTERNAL_COLLECTION_CHANNELS.includes(step.channel);
+}
+/** Validação de política vinda do banco — protege contra jsonb malformado. */
+export function parsePolicySteps(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const timings = ['before_due', 'on_due_date', 'after_due'];
+    const channels = ['email', 'whatsapp', 'notification'];
+    const tones = [
+        'reminder',
+        'due_notice',
+        'friendly_collection',
+        'overdue_collection',
+        'human_escalation',
+    ];
+    const seen = new Set();
+    const steps = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const s = item;
+        const key = typeof s.key === 'string' ? s.key : null;
+        // Chave duplicada arruinaria a idempotência: duas etapas com a mesma chave
+        // se anulam no `alreadyHandled` e uma delas nunca rodaria.
+        if (!key || seen.has(key))
+            continue;
+        if (!timings.includes(s.timing))
+            continue;
+        if (!channels.includes(s.channel))
+            continue;
+        if (!tones.includes(s.tone))
+            continue;
+        const offset = Number(s.offsetDays);
+        if (!Number.isInteger(offset) || offset < 0 || offset > 365)
+            continue;
+        seen.add(key);
+        steps.push({
+            key,
+            timing: s.timing,
+            offsetDays: offset,
+            channel: s.channel,
+            tone: s.tone,
+            templateKey: typeof s.templateKey === 'string' ? s.templateKey : 'collection.reminder',
+            active: s.active !== false,
+        });
+    }
+    return steps;
+}
+//# sourceMappingURL=policy.js.map

package/dist/collection/policy.js.map

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

package/dist/collection/repository.d.ts

@@ -0,0 +1,129 @@
+import type { Tx } from '../db/client.js';
+import type { CollectionChannelKey } from './channel.js';
+import { type CollectionPolicy } from './policy.js';
+/**
+ * Persistência do motor de cobrança sobre `dunning_event` (estendida na 0028
+ * para ancorar no Receivable) e `dunning_rule` (política por tenant).
+ *
+ * Tenant e cliente são cortados pela RLS; nenhuma query filtra na mão.
+ */
+export type CollectionStatus = 'scheduled' | 'sent' | 'failed' | 'canceled' | 'escalated';
+export type CollectionCloseReason = 'paid' | 'canceled' | 'rule_disabled' | 'permanent_failure' | 'escalated' | 'no_contact_data' | 'opted_out' | 'consent_unknown';
+export interface CollectionActionRecord {
+    id: string;
+    receivableId: string | null;
+    clientId: string | null;
+    clientName: string | null;
+    stepKey: string;
+    channel: CollectionChannelKey;
+    template: string | null;
+    status: CollectionStatus;
+    scheduledFor: string | null;
+    attempts: number;
+    lastError: string | null;
+    sentAt: string | null;
+    closedAt: string | null;
+    closedReason: CollectionCloseReason | null;
+    recipientRef: string | null;
+    amountAtSend: number | null;
+    createdAt: string;
+}
+/** Política ativa do tenant; cai no padrão do produto quando não há nenhuma. */
+export declare function getCollectionPolicy(tx: Tx): Promise<CollectionPolicy>;
+export declare function upsertCollectionPolicy(tx: Tx, input: {
+    name: string;
+    steps: unknown;
+    active?: boolean;
+}): Promise<CollectionPolicy>;
+/**
+ * Agenda uma etapa. Idempotente pelo índice único parcial
+ * `(tenant, receivable, step_key)` — o `ON CONFLICT DO NOTHING` é o que
+ * transforma job repetido, retry, restart de worker e webhook duplicado em
+ * uma única ação lógica.
+ */
+export declare function scheduleAction(tx: Tx, input: {
+    receivableId: string;
+    stepKey: string;
+    channel: CollectionChannelKey;
+    template: string;
+    scheduledFor: string;
+}): Promise<CollectionActionRecord | null>;
+export declare function getAction(tx: Tx, id: string): Promise<CollectionActionRecord>;
+export interface ActionFilter {
+    status?: CollectionStatus;
+    receivableId?: string;
+    clientId?: string;
+    /** Só o que já deveria ter saído. */
+    dueOnly?: boolean;
+    /**
+     * Data de referência do "já deveria ter saído".
+     *
+     * Sem isto a consulta usava `CURRENT_DATE` do banco, e o `today` que o motor
+     * recebe valia só para o planejamento — a execução ignorava. O ciclo deixava
+     * de ser determinístico: reprocessar uma data passada agendava as etapas mas
+     * não executava nenhuma.
+     */
+    dueUntil?: string;
+    limit?: number;
+}
+export declare function listActions(tx: Tx, filter?: ActionFilter): Promise<CollectionActionRecord[]>;
+/** Etapas já registradas para um recebível — alimenta a idempotência da régua. */
+export declare function handledStepKeys(tx: Tx, receivableId: string): Promise<Set<string>>;
+/**
+ * Assenta o envio.
+ *
+ * O identificador do provider vai para `provider_ref` (migration 0038). Antes
+ * ele era espremido em `template` sob COALESCE: como `scheduleAction` sempre
+ * grava o template, o id do provider era descartado em silêncio — e, se o
+ * template estivesse nulo, ocupava o lugar do nome e corrompia o relatório.
+ *
+ * Nunca deu problema porque o adapter de e-mail não devolve identificador.
+ * WhatsApp e SMS devolvem sempre, e o webhook de entrega chega trazendo APENAS
+ * esse id: sem coluna própria e indexada, todo status de entrega se perderia.
+ */
+export declare function markSent(tx: Tx, id: string, input: {
+    recipientRef: string;
+    amount: number;
+    providerRef?: string;
+    /** Chave do motor compartilhado. Ausente no caminho legado. */
+    idempotencyKey?: string;
+}): Promise<void>;
+export declare function markFailed(tx: Tx, id: string, input: {
+    error: string;
+    permanent: boolean;
+}): Promise<void>;
+export declare function markEscalated(tx: Tx, id: string, reason?: CollectionCloseReason): Promise<void>;
+/**
+ * Cancela ações ainda não enviadas de um recebível.
+ *
+ * Só toca `scheduled`: o que já saiu é histórico e não se apaga. Retorna quantas
+ * foram canceladas para o job poder relatar honestamente o que aconteceu.
+ */
+export declare function cancelPendingActions(tx: Tx, receivableId: string, reason: CollectionCloseReason): Promise<number>;
+export interface CollectionMetrics {
+    scheduled: number;
+    sent: number;
+    failed: number;
+    canceled: number;
+    stoppedByPayment: number;
+    escalated: number;
+    /** Escalados por falta de canal — problema de cadastro, não de entrega. */
+    noContactData: number;
+    dueToday: number;
+    /**
+     * Valor de recebíveis que foram pagos DEPOIS de pelo menos uma cobrança ter
+     * saído. É correlação, não causa: o nome diz "após", nunca "por causa de".
+     */
+    amountPaidAfterCollection: number;
+}
+export declare function collectionMetrics(tx: Tx): Promise<CollectionMetrics>;
+/** Linha do tempo de um cliente: recebíveis, pagamentos e cobranças. */
+export interface TimelineEntry {
+    at: string;
+    kind: 'receivable_created' | 'payment' | 'collection_sent' | 'collection_canceled' | 'collection_escalated';
+    detail: string;
+    amount: number | null;
+    receivableId: string | null;
+}
+export declare function clientTimeline(tx: Tx, clientId: string, limit?: number): Promise<TimelineEntry[]>;
+//# sourceMappingURL=repository.d.ts.map

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

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