@baruk/core 0.3.1 → 0.5.0

package/dist/communication/claim.js

@@ -0,0 +1,224 @@
+/**
+ * Reserva atômica do direito de enviar.
+ *
+ * O desenho anterior era, em substância:
+ *
+ *     alreadySent(key)  →  adapter.send()  →  markSent(key)
+ *
+ * Três passos, e o intervalo entre o primeiro e o terceiro é uma janela aberta:
+ * dois workers que perguntam "já enviei?" ao mesmo tempo recebem "não" os dois,
+ * e os dois chamam o provider. O cliente recebe a mesma cobrança duas vezes. A
+ * marcação posterior não conserta nada — o dinheiro do envio já saiu, e a
+ * mensagem também.
+ *
+ * Aqui a ordem é outra:
+ *
+ *     claim(key)  →  markProviderAttempt  →  [só o vencedor] send()  →  settle
+ *
+ * `claim` é uma operação ÚNICA e atômica no armazenamento: ou ela devolve a
+ * reserva, ou devolve o motivo de não ter devolvido. Não existe estado
+ * intermediário observável entre "verifiquei" e "reservei", porque não há dois
+ * momentos. Quem não ganhou a reserva não chama o provider — nem para "tentar de
+ * novo mais rápido".
+ *
+ * **A reserva vem ANTES do efeito externo, e essa é a regra inteira.** Qualquer
+ * proteção que aconteça depois de `send` é contabilidade do que já foi feito,
+ * não controle.
+ *
+ * ## O que a H2 acrescentou, e por quê
+ *
+ * A reserva tem prazo, porque processo morre segurando reserva e uma etapa calada
+ * para sempre é pior que uma duplicata rara. Mas retomar por prazo vencido, do
+ * jeito que estava, era retomar **às cegas**: o motor não tinha como distinguir
+ *
+ *   (a) o titular anterior morreu ANTES de falar com o provider — nada saiu, e
+ *       reenviar é obviamente certo;
+ *   (b) o titular anterior morreu DEPOIS de falar com o provider — pode ter saído,
+ *       e reenviar duplica.
+ *
+ * Os dois casos chegavam aqui com a mesma cara. `markProviderAttempt` é o que os
+ * separa: uma marca durável, gravada IMEDIATAMENTE antes da chamada externa, em
+ * fronteira própria. Quem retoma uma reserva que já tinha essa marca sabe que o
+ * desfecho é **desconhecido**, não "não enviado" — e desconhecido não autoriza
+ * reenvio cego.
+ *
+ * A marca é conservadora de propósito: gravar antes de chamar significa que um
+ * processo que morre entre a marca e a chamada é classificado como "pode ter
+ * enviado" quando não enviou. Erra para o lado de calar uma mensagem, nunca para
+ * o lado de mandar duas.
+ */
+/** Prazo da reserva. Ver `createInMemoryDispatchClaimStore` para o raciocínio. */
+export const DEFAULT_CLAIM_TTL_MS = 10 * 60 * 1000;
+/**
+ * Reserva em memória — **um processo só**.
+ *
+ * Serve a testes e a consumidores que rodam em instância única. Não serve a
+ * produção com mais de um worker, e a limitação está aqui em vez de num
+ * comentário do consumidor porque é o consumidor que erra: "por enquanto é uma
+ * instância" é verdade até o dia do primeiro redeploy com sobreposição.
+ *
+ * É atômica dentro do processo porque a decisão inteira acontece sem `await` no
+ * meio — em JavaScript isso basta para que dois `dispatch` concorrentes não se
+ * intercalem no ponto de decisão. Essa propriedade é o que o teste de
+ * concorrência in-process exercita; a prova de múltiplos processos é do store
+ * SQL.
+ *
+ * O prazo (`ttlMs`) existe pela mesma razão do store SQL: processo que morre
+ * segurando reserva não pode calar a etapa para sempre. Dez minutos é muito
+ * maior que qualquer timeout de provider (o mais longo aqui é 10 s) e muito
+ * menor que o intervalo entre ciclos da régua (24 h).
+ */
+export function createInMemoryDispatchClaimStore(options = {}) {
+    const ttl = options.ttlMs ?? DEFAULT_CLAIM_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const entries = new Map();
+    let seq = 0;
+    const write = async (entry, event) => {
+        if (!options.audit)
+            return;
+        await options.audit.record({
+            kind: event.kind,
+            ctx: entry.req.ctx,
+            channel: entry.req.channel,
+            eventType: entry.req.eventType,
+            subjectRef: entry.req.subjectRef,
+            recipientRef: entry.req.recipientRef,
+            idempotencyKey: entry.req.idempotencyKey,
+            providerRef: event.providerRef ?? null,
+            skipReason: event.skipReason ?? null,
+            status: event.status ?? null,
+            code: event.code ?? null,
+            detail: event.detail ?? null,
+            attempt: entry.attempt,
+        });
+    };
+    return {
+        async claim(req) {
+            // NENHUM `await` daqui até o `entries.set`. Um `await` aqui reabriria
+            // exatamente a janela que este módulo existe para fechar.
+            const current = entries.get(req.idempotencyKey);
+            const at = now();
+            if (current) {
+                if (current.state === 'sent')
+                    return { granted: false, reason: 'already_sent' };
+                if (current.state === 'failed_permanent') {
+                    return { granted: false, reason: 'permanently_failed' };
+                }
+                if (current.state === 'unknown_outcome') {
+                    return {
+                        granted: false,
+                        reason: 'unknown_outcome',
+                        detail: 'desfecho da tentativa anterior é desconhecido',
+                    };
+                }
+                if (current.state === 'in_flight' && current.expiresAt > at) {
+                    return { granted: false, reason: 'in_flight' };
+                }
+            }
+            const attempt = (current?.attempt ?? 0) + 1;
+            const recovered = current?.state === 'in_flight' && current.expiresAt <= at;
+            const providerAttempts = current?.providerAttempts ?? 0;
+            const claimId = current?.claimId ?? `mem-${++seq}`;
+            const claimToken = `tok-${++seq}`;
+            const entry = {
+                claimId,
+                claimToken,
+                state: 'in_flight',
+                attempt,
+                expiresAt: at + ttl,
+                providerAttempts,
+                providerFirstAttemptAt: current?.providerFirstAttemptAt ?? null,
+                req,
+            };
+            entries.set(req.idempotencyKey, entry);
+            const claim = {
+                claimId,
+                claimToken,
+                idempotencyKey: req.idempotencyKey,
+                attempt,
+                recoveredFromExpiredClaim: recovered,
+                // Retomada só é DESCONHECIDA se o titular anterior chegou a falar com o
+                // provider. Recuperar uma reserva que morreu antes disso é seguro, e
+                // tratá-la como desconhecida calaria a etapa sem motivo.
+                previousAttemptReachedProvider: recovered && providerAttempts > 0,
+                providerFirstAttemptAgeMs: entry.providerFirstAttemptAt === null ? null : at - entry.providerFirstAttemptAt,
+            };
+            await write(entry, {
+                kind: 'dispatch_claimed',
+                code: claim.previousAttemptReachedProvider
+                    ? 'recovered_unknown_outcome'
+                    : recovered
+                        ? 'recovered_from_expired_claim'
+                        : null,
+            });
+            return { granted: true, claim };
+        },
+        async markProviderAttempt(claim) {
+            const current = entries.get(claim.idempotencyKey);
+            // Linha sumiu, ou a geração é outra: quem chamou perdeu a reserva. A marca
+            // NÃO é gravada — gravá-la contaria uma tentativa externa do titular atual
+            // para o zumbi, e a próxima retomada leria o número errado.
+            if (!current || current.claimToken !== claim.claimToken) {
+                return { authority: 'lost', detail: 'reserva retomada por outra execução' };
+            }
+            if (current.state !== 'in_flight') {
+                return {
+                    authority: 'already_final',
+                    state: current.state,
+                    detail: `chave já assentada como ${current.state}`,
+                };
+            }
+            current.providerAttempts += 1;
+            current.providerFirstAttemptAt = current.providerFirstAttemptAt ?? now();
+            return { authority: 'held' };
+        },
+        async settle(claim, outcome, event) {
+            const current = entries.get(claim.idempotencyKey);
+            // Reserva já tomada por outro (prazo vencido): quem perdeu o direito não
+            // assenta o desfecho. A comparação é pelo TOKEN da geração, não pelo id da
+            // linha — o id sobrevive à retomada, o token não.
+            if (!current || current.claimToken !== claim.claimToken)
+                return;
+            if (outcome.kind === 'sent') {
+                current.state = 'sent';
+            }
+            else if (outcome.kind === 'failed') {
+                current.state = outcome.permanent ? 'failed_permanent' : 'failed_retryable';
+                current.expiresAt = 0;
+            }
+            else if (outcome.kind === 'unknown') {
+                current.state = 'unknown_outcome';
+                current.expiresAt = 0;
+            }
+            else {
+                // `released`: a chave volta a estar livre, sem contar como falha. O
+                // `attempt` permanece — é histórico, e serve para ver insistência.
+                current.state = 'failed_retryable';
+                current.expiresAt = 0;
+            }
+            await write(current, event);
+        },
+        async peek(idempotencyKey) {
+            const current = entries.get(idempotencyKey);
+            if (!current)
+                return 'none';
+            if (current.state === 'in_flight' && current.expiresAt <= now())
+                return 'failed_retryable';
+            return current.state;
+        },
+        async resolveUnknownOutcome(idempotencyKey, resolution, detail) {
+            const current = entries.get(idempotencyKey);
+            if (!current || current.state !== 'unknown_outcome')
+                return;
+            current.state = resolution === 'sent' ? 'sent' : 'failed_retryable';
+            current.expiresAt = 0;
+            await write(current, {
+                kind: resolution === 'sent' ? 'dispatch_sent' : 'dispatch_failed',
+                status: resolution === 'sent' ? 'sent' : null,
+                code: `unknown_resolved_${resolution}`,
+                detail: detail ?? null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=claim.js.map

package/dist/communication/claim.js.map

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

package/dist/communication/clearance.d.ts

@@ -0,0 +1,53 @@
+import type { ChannelKey } from './channel.js';
+/**
+ * Liberação do destinatário pelo REMETENTE.
+ *
+ * ## Por que não é consentimento
+ *
+ * Consentimento responde "esta pessoa aceita ser contatada?" — a vontade do
+ * destinatário. Para cobrança transacional, a relação contratual já responde, e
+ * é por isso que a política do produto trata `unknown` como permitido no
+ * e-mail.
+ *
+ * Isto responde outra pergunta: **"alguém do escritório olhou este endereço e
+ * liberou este cliente para comunicação externa?"**. As duas se separam
+ * exatamente no caso que importa — um cliente recém-importado tem relação
+ * contratual (consentimento resolvido) e nenhuma conferência (liberação
+ * ausente).
+ *
+ * Sem a separação, importar a carteira ligaria a régua de cobrança para toda
+ * ela no primeiro cron, sobre dados que ninguém verificou. Foi exatamente o que
+ * aconteceu no tenant de QA, com 81 e-mails.
+ *
+ * ## Por que a ausência bloqueia
+ *
+ * O padrão é NÃO liberado, e não há política que inverta isso. Um default
+ * "libera se ninguém disse nada" transformaria a omissão em autorização — e a
+ * omissão é o estado natural de todo cliente que acabou de entrar.
+ */
+export interface RecipientClearance {
+    cleared: boolean;
+    /** Quando um humano liberou. `null` enquanto ninguém liberou. */
+    clearedAt: string | null;
+}
+export interface RecipientClearanceStore {
+    /**
+     * `recipientRef` é a referência do destinatário no domínio do consumidor —
+     * o mesmo valor usado pelo consentimento e pela idempotência (para a régua de
+     * cobrança, o id do cliente).
+     */
+    find(recipientRef: string, channel: ChannelKey): Promise<RecipientClearance>;
+}
+/**
+ * Loja que libera tudo — para fluxos em que o destinatário **é** o remetente.
+ *
+ * O caso legítimo: notificação para a equipe do próprio escritório, teste de
+ * canal para o endereço de quem está configurando, ensaio sem envio. Ali não há
+ * terceiro a proteger, e exigir liberação seria cerimônia sem objeto.
+ *
+ * Existe com nome explícito, e não como default do motor, para que usá-la seja
+ * uma escolha visível na chamada em vez de o que acontece quando alguém
+ * esquece.
+ */
+export declare const CLEARANCE_NOT_REQUIRED: RecipientClearanceStore;
+//# sourceMappingURL=clearance.d.ts.map

package/dist/communication/clearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearance.d.ts","sourceRoot":"","sources":["../../src/communication/clearance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9E;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,uBAEpC,CAAC"}

package/dist/communication/clearance.js

@@ -0,0 +1,15 @@
+/**
+ * Loja que libera tudo — para fluxos em que o destinatário **é** o remetente.
+ *
+ * O caso legítimo: notificação para a equipe do próprio escritório, teste de
+ * canal para o endereço de quem está configurando, ensaio sem envio. Ali não há
+ * terceiro a proteger, e exigir liberação seria cerimônia sem objeto.
+ *
+ * Existe com nome explícito, e não como default do motor, para que usá-la seja
+ * uma escolha visível na chamada em vez de o que acontece quando alguém
+ * esquece.
+ */
+export const CLEARANCE_NOT_REQUIRED = {
+    find: async () => ({ cleared: true, clearedAt: null }),
+};
+//# sourceMappingURL=clearance.js.map

package/dist/communication/clearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearance.js","sourceRoot":"","sources":["../../src/communication/clearance.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA4B;IAC7D,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;CACvD,CAAC"}

package/dist/communication/consent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Permissão de contato por canal.
+ *
+ * O motor implementa o MECANISMO (registrar, consultar, recusar). A POLÍTICA —
+ * o que fazer quando ninguém decidiu ainda — é do produto, porque a resposta
+ * depende da relação: um escritório cobrando honorário de cliente contratado
+ * não está na mesma posição de quem manda promoção para uma lista.
+ *
+ * O que o motor não faz, em nenhuma configuração: inventar consentimento.
+ */
+import type { ChannelKey } from './channel.js';
+/**
+ * `unknown` NÃO é "pode". É "ninguém decidiu ainda", e é um estado distinto de
+ * propósito: colapsá-lo em `granted` é como um opt-out que ninguém registrou
+ * vira permissão, e colapsá-lo em `denied` trava a cobrança de toda a carteira
+ * legada que nunca teve o campo preenchido.
+ */
+export type ConsentState = 'granted' | 'denied' | 'unknown';
+export type ConsentSource = 'staff' | 'customer_reply' | 'import' | 'contract' | 'provider';
+export interface ConsentRecord {
+    channel: ChannelKey;
+    state: ConsentState;
+    source: ConsentSource;
+    decidedAt: string;
+}
+/**
+ * O que fazer com `unknown`, por canal. Configuração do produto.
+ *
+ * O default de fábrica é `fail_safe` — não envia. Vale para todo canal em que o
+ * produto não declarou nada: um canal novo entra fechado, e ligar é um ato
+ * explícito.
+ */
+export type UnknownPolicy = 'allow' | 'fail_safe';
+export interface ConsentPolicy {
+    /** Por canal. Ausente => `fail_safe`. */
+    onUnknown?: Partial<Record<ChannelKey, UnknownPolicy>>;
+}
+export type ConsentDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'opted_out' | 'consent_unknown';
+    detail: string;
+};
+/**
+ * `denied` é absoluto.
+ *
+ * Nenhuma política do produto reverte um opt-out — não há parâmetro para isso, e
+ * é deliberado. Um `denied` vindo de `customer_reply` (o cliente respondeu SAIR
+ * no WhatsApp) é o registro mais forte que existe no sistema, e o dia em que
+ * alguém puder configurar "ignorar opt-out para cobrança" é o dia em que a
+ * configuração vai estar ligada em algum tenant.
+ */
+export declare function evaluateConsent(channel: ChannelKey, record: ConsentRecord | null, policy?: ConsentPolicy): ConsentDecision;
+/**
+ * Fonte de consentimento. Implementada pelo produto.
+ *
+ * Recebe a referência do destinatário no domínio do consumidor (id do cliente),
+ * nunca o telefone: a permissão pertence à PESSOA, não ao número. Amarrá-la ao
+ * número faria o opt-out evaporar no dia em que o cliente trocasse de celular.
+ */
+export interface ConsentStore {
+    find(recipientRef: string, channel: ChannelKey): Promise<ConsentRecord | null>;
+}
+//# sourceMappingURL=consent.d.ts.map

package/dist/communication/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/communication/consent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,eAAe,GACzB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,aAAa,GAAG,IAAI,EAC5B,MAAM,GAAE,aAAkB,GACzB,eAAe,CAoBjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAChF"}

package/dist/communication/consent.js

@@ -0,0 +1,40 @@
+/**
+ * Permissão de contato por canal.
+ *
+ * O motor implementa o MECANISMO (registrar, consultar, recusar). A POLÍTICA —
+ * o que fazer quando ninguém decidiu ainda — é do produto, porque a resposta
+ * depende da relação: um escritório cobrando honorário de cliente contratado
+ * não está na mesma posição de quem manda promoção para uma lista.
+ *
+ * O que o motor não faz, em nenhuma configuração: inventar consentimento.
+ */
+/**
+ * `denied` é absoluto.
+ *
+ * Nenhuma política do produto reverte um opt-out — não há parâmetro para isso, e
+ * é deliberado. Um `denied` vindo de `customer_reply` (o cliente respondeu SAIR
+ * no WhatsApp) é o registro mais forte que existe no sistema, e o dia em que
+ * alguém puder configurar "ignorar opt-out para cobrança" é o dia em que a
+ * configuração vai estar ligada em algum tenant.
+ */
+export function evaluateConsent(channel, record, policy = {}) {
+    if (record?.state === 'denied') {
+        return {
+            allowed: false,
+            reason: 'opted_out',
+            detail: `destinatário recusou o canal ${channel}`,
+        };
+    }
+    if (record?.state === 'granted')
+        return { allowed: true };
+    // Sem registro, ou registro `unknown`: a política do produto decide.
+    const onUnknown = policy.onUnknown?.[channel] ?? 'fail_safe';
+    if (onUnknown === 'allow')
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: 'consent_unknown',
+        detail: `sem permissão registrada para ${channel}`,
+    };
+}
+//# sourceMappingURL=consent.js.map

package/dist/communication/consent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../src/communication/consent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsCH;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAmB,EACnB,MAA4B,EAC5B,SAAwB,EAAE;IAE1B,IAAI,MAAM,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,gCAAgC,OAAO,EAAE;SAClD,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAE1D,qEAAqE;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,IAAI,WAAW,CAAC;IAC7D,IAAI,SAAS,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAEpD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,iBAAiB;QACzB,MAAM,EAAE,iCAAiC,OAAO,EAAE;KACnD,CAAC;AACJ,CAAC"}

package/dist/communication/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contexto de toda operação de comunicação do ecossistema.
+ *
+ * Existe porque o motor é UM e os consumidores são vários. Sem contexto
+ * explícito, "envie esta mensagem" é ambíguo em três dimensões que só aparecem
+ * quando já é tarde: de qual escritório, sob qual marca, com qual número.
+ *
+ * Nenhum campo tem valor padrão, e nenhum é inferido do ambiente. Um default
+ * aqui seria a porta pela qual um produto envia com a identidade de outro — e
+ * seria justamente no caso que ninguém testou, porque o caminho feliz sempre
+ * passa o contexto certo.
+ */
+/**
+ * Identificador do produto consumidor — slug estável, nunca nome de exibição.
+ *
+ * Deliberadamente uma string validada por FORMA, e não uma união fechada dos
+ * produtos existentes: enumerar produtos aqui obrigaria a editar o motor
+ * compartilhado para cadastrar cada consumidor novo, que é exatamente como um
+ * motor de infraestrutura vira um monolito central cheio de regra de negócio.
+ */
+export type ProductKey = string;
+/** Marca sob a qual a mensagem sai. Distinta do produto: um produto pode servir várias marcas. */
+export type BrandKey = string;
+export interface CommunicationContext {
+    /** Escritório/organização dona do dado. Nunca opcional — é a fronteira de isolamento. */
+    tenantId: string;
+    product: ProductKey;
+    brand: BrandKey;
+}
+export type ContextRejection = 'tenant' | 'product' | 'brand';
+/**
+ * Valida o contexto na BORDA do motor.
+ *
+ * Rejeitar aqui, e não no adapter, é o que garante que nenhum caminho de envio
+ * exista sem contexto: o adapter recebe um contexto já validado ou não é
+ * chamado. Um adapter que valida por conta própria é um adapter que pode
+ * esquecer.
+ */
+export declare function validateContext(ctx: CommunicationContext): ContextRejection | null;
+/**
+ * Forma canônica do contexto para chave e trilha: `tenant/product/brand`.
+ *
+ * Não é PII e não é segredo — é o que aparece em log e em métrica, e é o que
+ * permite atribuir custo por tenant, produto e marca depois, sem que nada
+ * precise ser reinstrumentado.
+ */
+export declare function contextRef(ctx: CommunicationContext): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/communication/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/communication/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,kGAAkG;AAClG,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAI9B,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,oBAAoB,GAAG,gBAAgB,GAAG,IAAI,CAKlF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAE5D"}

package/dist/communication/context.js

@@ -0,0 +1,41 @@
+/**
+ * Contexto de toda operação de comunicação do ecossistema.
+ *
+ * Existe porque o motor é UM e os consumidores são vários. Sem contexto
+ * explícito, "envie esta mensagem" é ambíguo em três dimensões que só aparecem
+ * quando já é tarde: de qual escritório, sob qual marca, com qual número.
+ *
+ * Nenhum campo tem valor padrão, e nenhum é inferido do ambiente. Um default
+ * aqui seria a porta pela qual um produto envia com a identidade de outro — e
+ * seria justamente no caso que ninguém testou, porque o caminho feliz sempre
+ * passa o contexto certo.
+ */
+const SLUG = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+/**
+ * Valida o contexto na BORDA do motor.
+ *
+ * Rejeitar aqui, e não no adapter, é o que garante que nenhum caminho de envio
+ * exista sem contexto: o adapter recebe um contexto já validado ou não é
+ * chamado. Um adapter que valida por conta própria é um adapter que pode
+ * esquecer.
+ */
+export function validateContext(ctx) {
+    if (!ctx.tenantId || !ctx.tenantId.trim())
+        return 'tenant';
+    if (!SLUG.test(ctx.product))
+        return 'product';
+    if (!SLUG.test(ctx.brand))
+        return 'brand';
+    return null;
+}
+/**
+ * Forma canônica do contexto para chave e trilha: `tenant/product/brand`.
+ *
+ * Não é PII e não é segredo — é o que aparece em log e em métrica, e é o que
+ * permite atribuir custo por tenant, produto e marca depois, sem que nada
+ * precise ser reinstrumentado.
+ */
+export function contextRef(ctx) {
+    return `${ctx.tenantId}/${ctx.product}/${ctx.brand}`;
+}
+//# sourceMappingURL=context.js.map

package/dist/communication/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/communication/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,IAAI,GAAG,gCAAgC,CAAC;AAW9C;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAyB;IACvD,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAyB;IAClD,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;AACvD,CAAC"}

package/dist/communication/credentials.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Resolução de credencial de canal — do NOME lógico ao segredo.
+ *
+ * **O motor nunca vê o segredo antes da borda do adapter.** O que atravessa o
+ * domínio é `credentialRef`, um nome; o valor só é materializado no último
+ * passo, e a trava por conta (`credentialResolverFor`) garante que o adapter só
+ * consiga abrir a referência DAQUELA conta.
+ *
+ * O que muda nesta fase é de onde o valor vem.
+ *
+ * O resolvedor anterior traduzia um punhado de nomes fixos de variável de
+ * ambiente. Isso funciona para um tenant e falha de duas maneiras para dois:
+ * ou os dois apontam para o mesmo nome e COMPARTILHAM o token — a WABA de uma
+ * marca respondendo pelo comportamento de outra —, ou apontam para nomes
+ * distintos e nenhum resolve. Nenhuma das duas é aceitável num canal em que o
+ * bloqueio se propaga.
+ *
+ * A saída não é uma tabela nova de segredos: o ecossistema já tem o Vault
+ * Engine (migração 0012) — AES-256-GCM, chave-mestra fora do banco, tenant como
+ * dado autenticado adicional da cifra, RLS FORCE, vencimento e rotação. Um
+ * segundo cofre seria um segundo lugar para errar.
+ */
+/**
+ * Acesso ao cofre, na forma mínima que o motor precisa.
+ *
+ * Implementado pelo produto. O motor não sabe que existe `vault_credential`,
+ * nem keyring, nem permissão de decifrar — sabe pedir um nome para um tenant.
+ */
+export interface TenantSecretStore {
+    /**
+     * Devolve o segredo, ou `undefined` quando não existe / está vencido /
+     * revogado. **Nunca lança por ausência**: ausência é um desfecho normal, e
+     * quem chama trata como canal indisponível.
+     */
+    reveal(tenantId: string, name: string): Promise<string | undefined>;
+}
+/**
+ * Resolvedor composto: cofre primeiro, ambiente só para o legado declarado.
+ *
+ * A ordem importa e é fixa. Se o ambiente viesse primeiro, uma variável com o
+ * nome certo passaria na frente do cofre do tenant sem que ninguém percebesse —
+ * e o sintoma seria o pior possível: envio bem-sucedido, pela conta errada.
+ */
+export declare function createChannelCredentialResolver(tenantId: string, secrets: TenantSecretStore | null, env?: NodeJS.ProcessEnv): (ref: string) => Promise<string | undefined>;
+/**
+ * A referência aponta para o cofre?
+ *
+ * Usado por guard e por tela: um vínculo novo com referência de ambiente é
+ * dívida sendo criada, e deve ser visível no momento do cadastro, não seis meses
+ * depois.
+ */
+export declare function isVaultRef(ref: string): boolean;
+/**
+ * Referência aceitável para um vínculo NOVO?
+ *
+ * `NO_GLOBAL_WHATSAPP_CREDENTIAL_FOR_NEW_TENANTS` deixa de ser promessa de
+ * documento e vira predicado que um teste consegue exercer.
+ */
+export declare function isAcceptableForNewBinding(channel: string, ref: string): boolean;
+/**
+ * Resolvedor que não abre NADA — nem cofre, nem ambiente.
+ *
+ * Existe para as composições que montam o motor só para LER configuração
+ * (quais canais estão registrados, qual o remetente, qual o `credentialRef`) e
+ * nunca despacham. `GET /v1/communication/channels` é exatamente esse caso.
+ *
+ * Passar o resolvedor de envio ali seria dar à rota de leitura a capacidade de
+ * decifrar, ainda que ela não a exerça hoje. Capacidade que não é exercida é
+ * capacidade que alguém exerce depois, na primeira mudança que parecer
+ * inofensiva — e a diferença entre "não usa" e "não pode" é a única que sobrevive
+ * a essa mudança.
+ */
+export declare function noCredentialResolver(): (ref: string) => Promise<string | undefined>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/communication/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/communication/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACrE;AA2BD;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,iBAAiB,GAAG,IAAI,EACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsB9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEnF"}