@baruk/core 0.3.0 → 0.4.2

package/dist/collection/policy.js

@@ -0,0 +1,141 @@
+/**
+ * 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));
+}
+/** 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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"}

package/dist/collection/repository.js

@@ -0,0 +1,246 @@
+import { uuidv7 } from '@baruk/shared';
+import { DEFAULT_POLICY, parsePolicySteps } from './policy.js';
+const iso = (d) => (d ? d.toISOString().slice(0, 10) : null);
+function mapAction(r) {
+    return {
+        id: r.id,
+        receivableId: r.receivable_id,
+        clientId: r.client_id,
+        clientName: r.client_name,
+        stepKey: r.step_key,
+        channel: r.channel,
+        template: r.template,
+        status: r.status,
+        scheduledFor: iso(r.scheduled_for),
+        attempts: r.attempts,
+        lastError: r.last_error,
+        sentAt: r.sent_at?.toISOString() ?? null,
+        closedAt: r.closed_at?.toISOString() ?? null,
+        closedReason: r.closed_reason,
+        recipientRef: r.recipient_ref,
+        amountAtSend: r.amount_at_send === null ? null : Number(r.amount_at_send),
+        createdAt: r.created_at.toISOString(),
+    };
+}
+const SELECT_ACTION = `
+  SELECT d.id, d.receivable_id, r.client_id, c.display_name AS client_name, d.step_key,
+         d.channel, d.template, d.status, d.scheduled_for, d.attempts, d.last_error,
+         d.sent_at, d.closed_at, d.closed_reason, d.recipient_ref, d.amount_at_send, d.created_at
+    FROM dunning_event d
+    LEFT JOIN receivable r ON r.id = d.receivable_id
+    LEFT JOIN client c ON c.id = r.client_id AND c.deleted_at IS NULL`;
+// ── Política ────────────────────────────────────────────────────────────────
+/** Política ativa do tenant; cai no padrão do produto quando não há nenhuma. */
+export async function getCollectionPolicy(tx) {
+    const rows = await tx `
+    SELECT id, name, steps, active FROM dunning_rule
+     WHERE active AND is_default
+     ORDER BY created_at LIMIT 1
+  `;
+    const row = rows[0];
+    if (!row)
+        return DEFAULT_POLICY;
+    const steps = parsePolicySteps(row.steps);
+    // Política cadastrada mas ilegível não pode virar "sem cobrança nenhuma"
+    // silenciosamente: melhor cair no padrão e deixar a régua rodando.
+    if (steps.length === 0)
+        return { ...DEFAULT_POLICY, id: row.id, name: row.name };
+    return { id: row.id, name: row.name, steps, active: row.active };
+}
+export async function upsertCollectionPolicy(tx, input) {
+    const steps = parsePolicySteps(input.steps);
+    const existing = await tx `
+    SELECT id FROM dunning_rule WHERE is_default LIMIT 1
+  `;
+    if (existing[0]) {
+        await tx `
+      UPDATE dunning_rule
+         SET name = ${input.name}, steps = ${tx.json(steps)},
+             active = ${input.active ?? true}, updated_at = now()
+       WHERE id = ${existing[0].id}
+    `;
+    }
+    else {
+        await tx `
+      INSERT INTO dunning_rule (id, tenant_id, name, steps, active, is_default)
+      VALUES (${uuidv7()},
+              (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+              ${input.name}, ${tx.json(steps)}, ${input.active ?? true}, true)
+    `;
+    }
+    return getCollectionPolicy(tx);
+}
+// ── Ações ───────────────────────────────────────────────────────────────────
+/**
+ * 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 async function scheduleAction(tx, input) {
+    const rows = await tx `
+    INSERT INTO dunning_event (id, tenant_id, receivable_id, step_key, channel, template,
+                               status, scheduled_for)
+    VALUES (${uuidv7()},
+            (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+            ${input.receivableId}, ${input.stepKey}, ${input.channel}, ${input.template},
+            'scheduled', ${input.scheduledFor})
+    ON CONFLICT (tenant_id, receivable_id, step_key) WHERE receivable_id IS NOT NULL
+    DO NOTHING
+    RETURNING id
+  `;
+    if (!rows[0])
+        return null;
+    return getAction(tx, rows[0].id);
+}
+export async function getAction(tx, id) {
+    const rows = await tx `${tx.unsafe(SELECT_ACTION)} WHERE d.id = ${id}`;
+    const row = rows[0];
+    if (!row)
+        throw new Error('Ação de cobrança não encontrada');
+    return mapAction(row);
+}
+export async function listActions(tx, filter = {}) {
+    const limit = Math.min(Math.max(filter.limit ?? 100, 1), 500);
+    const rows = await tx `
+    ${tx.unsafe(SELECT_ACTION)}
+     WHERE d.receivable_id IS NOT NULL
+       ${filter.status ? tx `AND d.status = ${filter.status}` : tx ``}
+       ${filter.receivableId ? tx `AND d.receivable_id = ${filter.receivableId}` : tx ``}
+       ${filter.clientId ? tx `AND r.client_id = ${filter.clientId}` : tx ``}
+       ${filter.dueOnly
+        ? tx `AND d.status = 'scheduled' AND d.scheduled_for <= ${filter.dueUntil ?? tx `CURRENT_DATE`}`
+        : tx ``}
+     ORDER BY d.scheduled_for NULLS LAST, d.created_at
+     LIMIT ${limit}
+  `;
+    return rows.map(mapAction);
+}
+/** Etapas já registradas para um recebível — alimenta a idempotência da régua. */
+export async function handledStepKeys(tx, receivableId) {
+    const rows = await tx `
+    SELECT step_key FROM dunning_event WHERE receivable_id = ${receivableId}
+  `;
+    return new Set(rows.map((r) => r.step_key));
+}
+/**
+ * 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 async function markSent(tx, id, input) {
+    await tx `
+    UPDATE dunning_event
+       SET status = 'sent', sent_at = now(), attempts = attempts + 1,
+           recipient_ref = ${input.recipientRef}, amount_at_send = ${input.amount},
+           last_error = NULL, closed_at = now(),
+           provider_ref = COALESCE(${input.providerRef ?? null}, provider_ref),
+           idempotency_key = COALESCE(${input.idempotencyKey ?? null}, idempotency_key)
+     WHERE id = ${id}
+  `;
+}
+export async function markFailed(tx, id, input) {
+    await tx `
+    UPDATE dunning_event
+       SET status = ${input.permanent ? 'failed' : 'scheduled'},
+           attempts = attempts + 1,
+           last_error = ${input.error.slice(0, 300)},
+           closed_at = ${input.permanent ? tx `now()` : null},
+           closed_reason = ${input.permanent ? 'permanent_failure' : null}
+     WHERE id = ${id}
+  `;
+}
+export async function markEscalated(tx, id, reason = 'escalated') {
+    await tx `
+    UPDATE dunning_event
+       SET status = 'escalated', closed_at = now(), closed_reason = ${reason}
+     WHERE id = ${id}
+  `;
+}
+/**
+ * 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 async function cancelPendingActions(tx, receivableId, reason) {
+    const rows = await tx `
+    UPDATE dunning_event
+       SET status = 'canceled', closed_at = now(), closed_reason = ${reason}
+     WHERE receivable_id = ${receivableId} AND status = 'scheduled'
+    RETURNING id
+  `;
+    return rows.length;
+}
+export async function collectionMetrics(tx) {
+    const [m] = await tx `
+    SELECT
+      count(*) FILTER (WHERE status = 'scheduled')::int AS scheduled,
+      count(*) FILTER (WHERE status = 'sent')::int AS sent,
+      count(*) FILTER (WHERE status = 'failed')::int AS failed,
+      count(*) FILTER (WHERE status = 'canceled')::int AS canceled,
+      count(*) FILTER (WHERE status = 'canceled' AND closed_reason = 'paid')::int AS stopped_by_payment,
+      count(*) FILTER (WHERE status = 'escalated')::int AS escalated,
+      count(*) FILTER (WHERE closed_reason = 'no_contact_data')::int AS no_contact_data,
+      count(*) FILTER (WHERE status = 'scheduled' AND scheduled_for <= CURRENT_DATE)::int AS due_today
+      FROM dunning_event WHERE receivable_id IS NOT NULL
+  `;
+    const [p] = await tx `
+    SELECT COALESCE(sum(r.amount), 0) AS amount
+      FROM receivable r
+     WHERE r.status = 'paid'
+       AND EXISTS (SELECT 1 FROM dunning_event d
+                    WHERE d.receivable_id = r.id AND d.status = 'sent')
+  `;
+    return {
+        scheduled: m.scheduled,
+        sent: m.sent,
+        failed: m.failed,
+        canceled: m.canceled,
+        stoppedByPayment: m.stopped_by_payment,
+        escalated: m.escalated,
+        noContactData: m.no_contact_data,
+        dueToday: m.due_today,
+        amountPaidAfterCollection: Number(p.amount),
+    };
+}
+export async function clientTimeline(tx, clientId, limit = 100) {
+    const rows = await tx `
+    SELECT created_at AS at, 'receivable_created' AS kind,
+           COALESCE(competence, 'avulso') AS detail, amount, id AS receivable_id
+      FROM receivable WHERE client_id = ${clientId} AND deleted_at IS NULL
+    UNION ALL
+    SELECT p.paid_at, 'payment', p.method, p.amount, p.receivable_id
+      FROM payment p JOIN receivable r ON r.id = p.receivable_id
+     WHERE r.client_id = ${clientId} AND p.status = 'confirmed'
+    UNION ALL
+    SELECT d.sent_at, 'collection_sent', d.step_key || ' · ' || d.channel, d.amount_at_send, d.receivable_id
+      FROM dunning_event d JOIN receivable r ON r.id = d.receivable_id
+     WHERE r.client_id = ${clientId} AND d.status = 'sent' AND d.sent_at IS NOT NULL
+    UNION ALL
+    SELECT d.closed_at, 'collection_canceled', d.step_key || ' · ' || COALESCE(d.closed_reason, '-'), NULL, d.receivable_id
+      FROM dunning_event d JOIN receivable r ON r.id = d.receivable_id
+     WHERE r.client_id = ${clientId} AND d.status = 'canceled' AND d.closed_at IS NOT NULL
+    UNION ALL
+    SELECT d.closed_at, 'collection_escalated', d.step_key, NULL, d.receivable_id
+      FROM dunning_event d JOIN receivable r ON r.id = d.receivable_id
+     WHERE r.client_id = ${clientId} AND d.status = 'escalated' AND d.closed_at IS NOT NULL
+    ORDER BY at DESC
+    LIMIT ${limit}
+  `;
+    return rows.map((r) => ({
+        at: r.at.toISOString(),
+        kind: r.kind,
+        detail: r.detail,
+        amount: r.amount === null ? null : Number(r.amount),
+        receivableId: r.receivable_id,
+    }));
+}
+//# sourceMappingURL=repository.js.map

package/dist/collection/repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../../src/collection/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAyB,MAAM,aAAa,CAAC;AAqEtF,MAAM,GAAG,GAAG,CAAC,CAAc,EAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAEzF,SAAS,SAAS,CAAC,CAAY;IAC7B,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,YAAY,EAAE,CAAC,CAAC,aAAa;QAC7B,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,UAAU,EAAE,CAAC,CAAC,WAAW;QACzB,OAAO,EAAE,CAAC,CAAC,QAAQ;QACnB,OAAO,EAAE,CAAC,CAAC,OAA+B;QAC1C,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QAClC,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,CAAC,CAAC,UAAU;QACvB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,IAAI;QACxC,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,IAAI;QAC5C,YAAY,EAAE,CAAC,CAAC,aAAa;QAC7B,YAAY,EAAE,CAAC,CAAC,aAAa;QAC7B,YAAY,EAAE,CAAC,CAAC,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC;QACzE,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAG;;;;;;sEAMgD,CAAC;AAEvE,+EAA+E;AAE/E,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAM;IAC9C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAiE;;;;GAIrF,CAAC;IACF,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG;QAAE,OAAO,cAAc,CAAC;IAChC,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1C,yEAAyE;IACzE,mEAAmE;IACnE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,cAAc,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IACjF,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;AACnE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,EAAM,EACN,KAAyD;IAEzD,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAkB;;GAE1C,CAAC;IACF,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,MAAM,EAAE,CAAA;;sBAEU,KAAK,CAAC,IAAI,aAAa,EAAE,CAAC,IAAI,CAAC,KAAc,CAAC;wBAC5C,KAAK,CAAC,MAAM,IAAI,IAAI;oBACxB,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;KAC7B,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,CAAA;;gBAEI,MAAM,EAAE;;gBAER,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,CAAC,KAAc,CAAC,KAAK,KAAK,CAAC,MAAM,IAAI,IAAI;KAC1E,CAAC;IACJ,CAAC;IACD,OAAO,mBAAmB,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,KAMC;IAED,MAAM,IAAI,GAAG,MAAM,EAAE,CAAkB;;;cAG3B,MAAM,EAAE;;cAER,KAAK,CAAC,YAAY,KAAK,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,QAAQ;2BAC5D,KAAK,CAAC,YAAY;;;;GAI1C,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAAM,EAAE,EAAU;IAChD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAa,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,EAAE,EAAE,CAAC;IACnF,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC7D,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAoBD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAM,EACN,SAAuB,EAAE;IAEzB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,EAAE,CAAa;MAC9B,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;;SAErB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA,kBAAkB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA,EAAE;SAC1D,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA,yBAAyB,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA,EAAE;SAC7E,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA,qBAAqB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA,EAAE;SAEjE,MAAM,CAAC,OAAO;QACZ,CAAC,CAAC,EAAE,CAAA,qDAAqD,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAA,cAAc,EAAE;QAC9F,CAAC,CAAC,EAAE,CAAA,EACR;;aAEM,KAAK;GACf,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAM,EAAE,YAAoB;IAChE,MAAM,IAAI,GAAG,MAAM,EAAE,CAAwB;+DACgB,YAAY;GACxE,CAAC;IACF,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,EAAM,EACN,EAAU,EACV,KAMC;IAED,MAAM,EAAE,CAAA;;;6BAGmB,KAAK,CAAC,YAAY,sBAAsB,KAAK,CAAC,MAAM;;qCAE5C,KAAK,CAAC,WAAW,IAAI,IAAI;wCACtB,KAAK,CAAC,cAAc,IAAI,IAAI;kBAClD,EAAE;GACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,EAAM,EACN,EAAU,EACV,KAA4C;IAE5C,MAAM,EAAE,CAAA;;sBAEY,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW;;0BAEpC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;yBAC1B,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAA,OAAO,CAAC,CAAC,CAAC,IAAI;6BAC9B,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI;kBACvD,EAAE;GACjB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAM,EACN,EAAU,EACV,SAAgC,WAAW;IAE3C,MAAM,EAAE,CAAA;;sEAE4D,MAAM;kBAC1D,EAAE;GACjB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAM,EACN,YAAoB,EACpB,MAA6B;IAE7B,MAAM,IAAI,GAAG,MAAM,EAAE,CAAkB;;qEAE4B,MAAM;6BAC9C,YAAY;;GAEtC,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAqBD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAM;IAC5C,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAWnB;;;;;;;;;;;GAWA,CAAC;IAEF,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAsB;;;;;;GAMzC,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,CAAE,CAAC,SAAS;QACvB,IAAI,EAAE,CAAE,CAAC,IAAI;QACb,MAAM,EAAE,CAAE,CAAC,MAAM;QACjB,QAAQ,EAAE,CAAE,CAAC,QAAQ;QACrB,gBAAgB,EAAE,CAAE,CAAC,kBAAkB;QACvC,SAAS,EAAE,CAAE,CAAC,SAAS;QACvB,aAAa,EAAE,CAAE,CAAC,eAAe;QACjC,QAAQ,EAAE,CAAE,CAAC,SAAS;QACtB,yBAAyB,EAAE,MAAM,CAAC,CAAE,CAAC,MAAM,CAAC;KAC7C,CAAC;AACJ,CAAC;AAgBD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,QAAgB,EAChB,KAAK,GAAG,GAAG;IAEX,MAAM,IAAI,GAAG,MAAM,EAAE,CAQpB;;;0CAGuC,QAAQ;;;;2BAIvB,QAAQ;;;;2BAIR,QAAQ;;;;2BAIR,QAAQ;;;;2BAIR,QAAQ;;YAEvB,KAAK;GACd,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtB,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE;QACtB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QACnD,YAAY,EAAE,CAAC,CAAC,aAAa;KAC9B,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/collection/subject.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 type { Tx } from '../db/client.js';
+import { type ReceivableWithBalance } from '../billing/ar-repository.js';
+import { type CollectionPolicy } from './policy.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 declare function isCollectibleSubject(r: ReceivableWithBalance): boolean;
+export interface EligibleSubjectQuery {
+    clientId: string;
+    /** Etapa da régua, como `D+3`. */
+    stepKey: string;
+    /** Data de referência, `YYYY-MM-DD`. Do chamador — o domínio não lê relógio. */
+    today: string;
+    policy?: CollectionPolicy;
+}
+/**
+ * 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 declare function findEligibleSubjects(tx: Tx, q: EligibleSubjectQuery): Promise<ReceivableWithBalance[]>;
+/**
+ * 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 declare function resolveSubjectForStep(tx: Tx, q: EligibleSubjectQuery): Promise<ReceivableWithBalance | null>;
+//# sourceMappingURL=subject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/collection/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9D;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAQtE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,EAAE,EACN,CAAC,EAAE,oBAAoB,GACtB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CA2BlC;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,CAAC,EAAE,oBAAoB,GACtB,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAGvC"}