@baruk/core 0.3.1 → 0.5.0

package/dist/cjs/communication/adapters/whatsapp-templates.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Gestão de template no WhatsApp — adapter da Meta Cloud API.
+ *
+ * Implementa `TemplateManagementProvider`. Todo o vocabulário da Meta mora
+ * aqui: `components`, `BODY`, `example.body_text`, categorias em maiúsculas,
+ * `POST /{waba-id}/message_templates`. O domínio não conhece nenhum deles.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWhatsAppTemplateProvider = createWhatsAppTemplateProvider;
+const graph_js_1 = require("../graph.js");
+const whatsapp_language_js_1 = require("./whatsapp-language.js");
+const TIMEOUT_MS = 20_000;
+/** O domínio fala minúsculo; a Meta espera maiúsculo. A tradução mora aqui. */
+const CATEGORY = {
+    utility: 'UTILITY',
+    marketing: 'MARKETING',
+    authentication: 'AUTHENTICATION',
+};
+/**
+ * Classificação do erro da Meta.
+ *
+ * `duplicate_name` merece classe própria porque é o desfecho ESPERADO de uma
+ * resubmissão — quem chama trata como "já existe", relê e segue, em vez de
+ * tratar como falha e tentar de novo.
+ */
+function classify(status, code, subcode) {
+    if (code === 190 || code === 200 || code === 10 || code === 3)
+        return 'unauthorized';
+    // 2388023 / subcode 2388024: nome de template já em uso na conta.
+    if (code === 2388023 || subcode === 2388024)
+        return 'duplicate_name';
+    if (code === 4 || code === 80007 || status === 429)
+        return 'rate_limited';
+    if (status >= 500)
+        return 'network';
+    if (code === 100 || code === 132000)
+        return 'invalid_content';
+    return 'provider_error';
+}
+function createWhatsAppTemplateProvider(config) {
+    const doFetch = config.fetchImpl ?? fetch;
+    return {
+        channel: 'whatsapp',
+        async submit(submission) {
+            const body = {
+                name: submission.name,
+                language: (0, whatsapp_language_js_1.metaLanguageCode)(submission.language),
+                category: CATEGORY[submission.category],
+                components: [
+                    {
+                        type: 'BODY',
+                        text: submission.bodyText,
+                        // `body_text` é uma lista de listas: uma linha de exemplos por
+                        // conjunto de variáveis do corpo. Omitido quando não há variável —
+                        // um `example` vazio é recusado.
+                        ...(submission.bodyExample && submission.bodyExample.length > 0
+                            ? { example: { body_text: [submission.bodyExample] } }
+                            : {}),
+                    },
+                ],
+            };
+            let res;
+            try {
+                res = await doFetch((0, graph_js_1.graphUrl)(`${encodeURIComponent(config.wabaId)}/message_templates`, config.env), {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${config.accessToken}`,
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(TIMEOUT_MS),
+                });
+            }
+            catch {
+                // Nada da exceção é propagado: em algumas implementações de `fetch` a
+                // mensagem inclui a URL, e a URL leva o token no header — mas o corpo
+                // do erro também pode ecoar cabeçalhos em proxies.
+                return { ok: false, reason: 'network' };
+            }
+            const payload = (await res.json().catch(() => null));
+            if (!res.ok) {
+                const err = (payload?.error ?? {});
+                return { ok: false, reason: classify(res.status, err.code, err.error_subcode) };
+            }
+            const id = payload?.id;
+            const status = payload?.status;
+            const category = payload?.category;
+            return {
+                ok: true,
+                ...(typeof id === 'string' ? { providerRef: id } : {}),
+                // Sem `status` no corpo, o desfecho honesto é "submetido, revisão
+                // pendente" — e não inventar `APPROVED`.
+                status: typeof status === 'string' ? status : 'PENDING',
+                ...(typeof category === 'string' ? { category } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=whatsapp-templates.js.map

package/dist/cjs/communication/adapters/whatsapp-templates.js.map

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

package/dist/cjs/communication/adapters/whatsapp.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Adapter de WhatsApp — Meta Cloud API.
+ *
+ * O provider é escolha desta implementação, não do domínio: o consumidor pede
+ * `channel: 'whatsapp'` e nunca vê `wamid`, `phoneNumberId` nem código de erro
+ * da Meta. Trocar por Twilio ou Zenvia é escrever outro arquivo deste tamanho e
+ * registrar outro adapter — nenhuma linha de régua muda.
+ *
+ * **Trava de envio real.** Enquanto `liveSend` não for explicitamente ligado, o
+ * adapter recusa com `unavailable` ANTES de qualquer rede. A trava é do código,
+ * não do processo: uma frente que promete "não enviar mensagem real" e depende
+ * de ninguém chamar a função errada não prometeu nada.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWhatsAppChannel = createWhatsAppChannel;
+const graph_js_1 = require("../graph.js");
+const whatsapp_language_js_1 = require("./whatsapp-language.js");
+/**
+ * O que a Meta Cloud API garante, e o que este adapter exerce.
+ *
+ * **Sem idempotência de provider.** A referência da Cloud API não documenta
+ * cabeçalho de idempotência nem parâmetro equivalente; o `wamid` é identificador
+ * de mensagem devolvido DEPOIS do aceite, que é outra coisa — ele não impede a
+ * segunda chamada de virar a segunda mensagem.
+ *
+ * A consequência prática está no motor, não aqui: uma reserva de WhatsApp retomada
+ * de um titular que já tinha chamado a Meta **não é reenviada**. Ela para em
+ * `unknown_outcome`, visível para quem opera. Inventar uma chave que a Meta não lê
+ * daria a aparência da proteção sem nada por trás — que é pior que não ter.
+ *
+ * `supportsDeliveryWebhook` é `true` porque a rota de callback da Meta existe e é
+ * exercida (`routes/communication-webhooks.ts`); `supportsReadReceipt` também,
+ * porque `read` é um dos status que ela trata.
+ */
+const META_CLOUD_CAPABILITIES = {
+    supportsProviderIdempotency: false,
+    supportsMessageLookup: false,
+    supportsDeliveryWebhook: true,
+    supportsReadReceipt: true,
+};
+/*
+ * A versão da Graph API mora em `../graph.ts`, e não aqui.
+ *
+ * Este arquivo declarava `v21.0` — de 2024-10, no fim da janela de dois anos em
+ * que a Meta mantém uma versão viva. Duas versões no mesmo runtime não falham
+ * quando divergem: falham quando a mais velha é desativada, e o sintoma é meio
+ * canal parado enquanto o resto funciona.
+ */
+const TIMEOUT_MS = 10_000;
+/**
+ * Classificação dos códigos de erro da Meta.
+ *
+ * A distinção que mais importa não é temporário × permanente — é **problema do
+ * destinatário × problema nosso**. Um token expirado (190) devolvido como
+ * `permanent` marcaria o CLIENTE como contato inválido e o tiraria da régua para
+ * sempre, quando o defeito é uma credencial nossa que alguém precisa renovar.
+ * Por isso erro de configuração vira `unavailable`: não gasta tentativa, não
+ * acusa o cliente, e aparece na tela como pendência do escritório.
+ */
+function classify(code, subcode) {
+    // Credencial/permissão/configuração — nosso problema, não do destinatário.
+    if (code === 190 || code === 200 || code === 10 || code === 3)
+        return 'unavailable';
+    if (code === 100 && subcode === 33)
+        return 'unavailable';
+    // Limites de taxa — sempre vale tentar de novo.
+    if (code === 4 || code === 80007 || code === 130429 || code === 131048 || code === 131056) {
+        return 'temporary';
+    }
+    // Falhas internas da plataforma.
+    if (code === 1 || code === 2 || code === 131000)
+        return 'temporary';
+    // Destinatário: não tem WhatsApp, número inexistente, recusa de entrega.
+    if (code === 131026 || code === 131052 || code === 133010)
+        return 'permanent';
+    // Fora da janela de sessão sem template válido, e problemas de template.
+    if (code === 131047 || (code >= 132000 && code <= 132015))
+        return 'permanent';
+    // Parâmetro inválido é defeito de integração; retry repetiria o mesmo erro.
+    if (code === 100)
+        return 'permanent';
+    // Código desconhecido: `temporary`. Um erro novo da Meta tratado como
+    // permanente removeria o cliente da régua em definitivo por algo que ninguém
+    // ainda entendeu — o dano de tentar de novo é muito menor.
+    return 'temporary';
+}
+function createWhatsAppChannel(config) {
+    const doFetch = config.fetchImpl ?? fetch;
+    return {
+        key: 'whatsapp',
+        providerName: 'meta_cloud',
+        capabilities: META_CLOUD_CAPABILITIES,
+        isConfigured(_ctx) {
+            return (config.account.status === 'active' &&
+                Boolean(config.account.meta?.phoneNumberId) &&
+                Boolean(config.account.senderId));
+        },
+        async send(message) {
+            if (!config.liveSend) {
+                return {
+                    kind: 'unavailable',
+                    code: 'live_send_disabled',
+                    detail: 'envio real de WhatsApp não autorizado neste ambiente',
+                };
+            }
+            const phoneNumberId = config.account.meta?.phoneNumberId;
+            if (!phoneNumberId) {
+                return {
+                    kind: 'unavailable',
+                    code: 'no_phone_number_id',
+                    detail: 'conta sem phoneNumberId',
+                };
+            }
+            const token = await config.resolveCredential(config.account.credentialRef);
+            if (!token) {
+                return { kind: 'unavailable', code: 'no_credential', detail: 'credencial ausente' };
+            }
+            const body = buildBody(message);
+            if (!body) {
+                return {
+                    kind: 'permanent',
+                    code: 'content_mismatch',
+                    detail: 'conteúdo inválido para WhatsApp',
+                };
+            }
+            let res;
+            try {
+                res = await doFetch((0, graph_js_1.graphUrl)(`${encodeURIComponent(phoneNumberId)}/messages`), {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${token}`,
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(TIMEOUT_MS),
+                });
+            }
+            catch {
+                // Timeout e falha de rede nunca carregam a causa real do lado do
+                // provider — e a mensagem da exceção pode conter a URL com credencial
+                // embutida em algumas implementações. Não propaga nada dela.
+                return { kind: 'temporary', code: 'network', detail: 'falha de rede ao chamar o provider' };
+            }
+            if (res.ok) {
+                const payload = (await res.json().catch(() => null));
+                const providerRef = payload?.messages?.[0]?.id;
+                // `sent` = a Meta aceitou. NÃO é entrega: quem afirma entrega é o
+                // webhook, depois. Ver `status.ts`.
+                return { kind: 'sent', providerRef };
+            }
+            const err = (await res
+                .json()
+                .then((b) => typeof b === 'object' && b !== null && 'error' in b
+                ? (b.error ?? {})
+                : {})
+                .catch(() => ({})));
+            const code = err.code ?? res.status;
+            const kind = res.status >= 500 ? 'temporary' : classify(code, err.error_subcode);
+            return {
+                kind,
+                code: `meta_${code}`,
+                // Só a mensagem do provider, truncada. Nunca o corpo enviado (carrega as
+                // variáveis do template, que são PII) e nunca os headers.
+                detail: (err.message ?? `HTTP ${res.status}`).slice(0, 200),
+            };
+        },
+    };
+}
+function buildBody(message) {
+    const to = message.to.replace(/^\+/, '');
+    if (message.content.kind === 'whatsapp_template') {
+        const { templateName, language, variables } = message.content;
+        return {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'template',
+            template: {
+                name: templateName,
+                // A Meta escreve `pt_BR`; o domínio, `pt-BR`. A tradução é do adapter.
+                language: { code: (0, whatsapp_language_js_1.metaLanguageCode)(language) },
+                // `components` só entra quando há variável: um template sem parâmetro
+                // recebendo `parameters: []` é recusado pela Meta.
+                ...(variables.length > 0
+                    ? {
+                        components: [
+                            {
+                                type: 'body',
+                                parameters: variables.map((text) => ({ type: 'text', text })),
+                            },
+                        ],
+                    }
+                    : {}),
+            },
+        };
+    }
+    if (message.content.kind === 'text') {
+        // Texto livre só é aceito DENTRO da janela de 24h aberta pelo cliente. O
+        // motor não tem como saber se a janela está aberta — e por isso este caminho
+        // existe para resposta a conversa iniciada pelo cliente, nunca para
+        // cobrança ativa, que é sempre template.
+        return {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'text',
+            text: { preview_url: false, body: message.content.body },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=whatsapp.js.map

package/dist/cjs/communication/adapters/whatsapp.js.map

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

package/dist/cjs/communication/audit.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Trilha de comunicação — o que o motor decidiu, e por quê.
+ *
+ * **Não é log.** Log é texto que alguém talvez leia; isto é registro estruturado
+ * e consultável, com um vocabulário fechado de eventos. A diferença aparece na
+ * pergunta que o escritório faz de verdade: "por que este cliente não recebeu?".
+ * Um `console.warn` responde isso para quem estiver com o terminal aberto no
+ * instante certo; uma trilha responde seis meses depois.
+ *
+ * A trilha financeira (`dunning_event`) continua sendo o estado da ETAPA da
+ * régua. Esta é o histórico da INTENÇÃO de comunicar — que é outra coisa: uma
+ * etapa pode ter uma intenção recusada por consentimento, outra por telefone
+ * inválido e uma terceira entregue, e `dunning_event` só guarda o desfecho final
+ * de uma delas.
+ *
+ * O que NUNCA entra aqui: valor de credencial, corpo de mensagem, telefone,
+ * e-mail. O destinatário aparece como referência lógica (`recipientRef`), que já
+ * é o vocabulário do consumidor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNullAuditSink = createNullAuditSink;
+exports.createRecordingAuditSink = createRecordingAuditSink;
+exports.eventKindForSkip = eventKindForSkip;
+/**
+ * Sink que não grava nada.
+ *
+ * Existe para consumidores que ainda não têm armazenamento, e é EXPLÍCITO de
+ * propósito: um sink opcional viraria `deps.audit?.record(...)` espalhado pelo
+ * motor, e a diferença entre "não configurou trilha" e "esqueceu de chamar"
+ * deixaria de ser visível.
+ */
+function createNullAuditSink() {
+    return { async record() { } };
+}
+/** Coleta em memória — para teste e para o relatório de dry-run. */
+function createRecordingAuditSink() {
+    const events = [];
+    return {
+        events,
+        async record(event) {
+            events.push(event);
+        },
+    };
+}
+/**
+ * De qual evento de trilha um pulo é.
+ *
+ * Três motivos ganham nome próprio porque exigem ações operacionais opostas:
+ * opt-out é decisão do cliente (e ninguém no escritório deve "resolver"), falta
+ * de contato é cadastro, e o resto é ambiente. Colapsá-los em `dispatch_skipped`
+ * mandaria o escritório procurar no lugar errado nos dois primeiros casos.
+ */
+function eventKindForSkip(reason) {
+    if (reason === 'opted_out')
+        return 'consent_blocked';
+    if (reason === 'no_recipient' || reason === 'invalid_recipient')
+        return 'invalid_contact';
+    return 'dispatch_skipped';
+}
+//# sourceMappingURL=audit.js.map

package/dist/cjs/communication/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/communication/audit.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AA6EH,kDAEC;AAGD,4DAUC;AAUD,4CAIC;AArCD;;;;;;;GAOG;AACH,SAAgB,mBAAmB;IACjC,OAAO,EAAE,KAAK,CAAC,MAAM,KAAmB,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,oEAAoE;AACpE,SAAgB,wBAAwB;IAGtC,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,OAAO;QACL,MAAM;QACN,KAAK,CAAC,MAAM,CAAC,KAAyB;YACpC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAAC,MAAkB;IACjD,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,iBAAiB,CAAC;IACrD,IAAI,MAAM,KAAK,cAAc,IAAI,MAAM,KAAK,mBAAmB;QAAE,OAAO,iBAAiB,CAAC;IAC1F,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/cjs/communication/capabilities.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * O que o PROVIDER por trás de um canal garante — declarado pelo adapter.
+ *
+ * Existe para que o motor possa tomar uma decisão que depende do provider sem
+ * nunca saber qual provider é. A alternativa é a que o certificador proibiu
+ * explicitamente:
+ *
+ *     if (provider === 'resend') { ...reenvia... } else { ...não reenvia... }
+ *
+ * Espalhado pelo núcleo, esse `if` transforma "trocar de provider" em mudança de
+ * regra de negócio, e faz o motor compartilhado carregar o catálogo de fornecedor
+ * de cada produto. Aqui o adapter DECLARA a garantia e o motor lê a declaração.
+ *
+ * **Toda capability nasce `false`.** O default não é conservadorismo estético: um
+ * campo opcional que o adapter esquece de declarar viraria uma garantia
+ * imaginária, e a consequência de imaginar idempotência que não existe é o
+ * cliente recebendo a mesma cobrança duas vezes. Quem tem a garantia declara; o
+ * silêncio significa ausência.
+ *
+ * **A declaração descreve o que ESTE ADAPTER exerce, não o que o provider anuncia
+ * no site.** O Resend publica webhooks de entrega; o adapter de e-mail daqui não
+ * consome nenhum, então `supportsDeliveryWebhook` é `false` para ele. Declarar a
+ * capacidade do fornecedor em vez da capacidade do código seria documentar uma
+ * integração que não existe — que é o defeito `DOCUMENTATION_MATCHES_RUNTIME`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESEND_IDEMPOTENCY_WINDOW_MS = exports.NO_PROVIDER_GUARANTEES = void 0;
+exports.providerIdempotencyCovers = providerIdempotencyCovers;
+/**
+ * Nenhuma garantia externa. É o que vale para todo canal que não declare o
+ * contrário — e é o que faz um adapter novo nascer seguro em vez de nascer
+ * otimista.
+ */
+exports.NO_PROVIDER_GUARANTEES = {
+    supportsProviderIdempotency: false,
+    supportsMessageLookup: false,
+    supportsDeliveryWebhook: false,
+    supportsReadReceipt: false,
+};
+/**
+ * Reenviar com a MESMA chave é seguro agora?
+ *
+ * Chamado quando o desfecho da tentativa anterior é desconhecido — o titular da
+ * reserva chamou o provider e morreu antes de assentar. A pergunta não é "o
+ * provider tem idempotência", é "a chave que eu usei ainda está viva lá".
+ *
+ * Fora da janela, a chave já não significa nada para o provider: a segunda
+ * chamada seria uma mensagem nova, e o cliente receberia duas. Por isso a
+ * expiração devolve `false` — e o motor, sem cobertura, não reenvia.
+ *
+ * **Recebe IDADE, não instante.** A diferença não é estética: o instante da
+ * primeira chamada é medido pelo relógio de quem guardou o dado (o `now()` do
+ * banco), e compará-lo com o `Date.now()` do processo mistura dois relógios que
+ * não têm obrigação de concordar. Numa deriva de poucos segundos isso passa
+ * despercebido; num processo com relógio adiantado, "dentro da janela" vira
+ * "fora" e o motor deixa de reenviar o que podia — ou o contrário. Quem guarda o
+ * dado calcula a idade, e a comparação acontece numa escala só.
+ *
+ * `ageMs` ausente significa que nenhuma chamada externa foi registrada, e aí não
+ * há o que cobrir: quem pergunta nesse estado está perguntando a coisa errada,
+ * então a resposta é `false`.
+ */
+function providerIdempotencyCovers(capabilities, ageMs) {
+    if (!capabilities.supportsProviderIdempotency)
+        return false;
+    const window = capabilities.providerIdempotencyWindowMs;
+    if (!window || window <= 0)
+        return false;
+    if (ageMs === null || ageMs < 0)
+        return false;
+    return ageMs < window;
+}
+/** Janela de idempotência do Resend: 24 horas. Ver `adapters/email.ts`. */
+exports.RESEND_IDEMPOTENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
+//# sourceMappingURL=capabilities.js.map

package/dist/cjs/communication/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/communication/capabilities.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AAoEH,8DASC;AA5CD;;;;GAIG;AACU,QAAA,sBAAsB,GAAwB;IACzD,2BAA2B,EAAE,KAAK;IAClC,qBAAqB,EAAE,KAAK;IAC5B,uBAAuB,EAAE,KAAK;IAC9B,mBAAmB,EAAE,KAAK;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,yBAAyB,CACvC,YAAiC,EACjC,KAAoB;IAEpB,IAAI,CAAC,YAAY,CAAC,2BAA2B;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,MAAM,GAAG,YAAY,CAAC,2BAA2B,CAAC;IACxD,IAAI,CAAC,MAAM,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,KAAK,GAAG,MAAM,CAAC;AACxB,CAAC;AAED,2EAA2E;AAC9D,QAAA,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}

package/dist/cjs/communication/channel.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Contrato canônico de canal do ecossistema — e-mail, WhatsApp, SMS e
+ * notificação interna sob a mesma interface.
+ *
+ * O ponto de desenho está no CONTEÚDO, não na interface. A abstração de canal
+ * que já existia na cobrança da SC (`collection/channel.ts`) carregava
+ * `subject` + `html` obrigatórios: um payload de e-mail com nome genérico. Um
+ * adapter de WhatsApp receberia HTML renderizado e teria de desmontá-lo de
+ * volta em texto, e um de SMS idem — o canal vazando para dentro do domínio
+ * pela porta do payload.
+ *
+ * Aqui o conteúdo é uma união discriminada, resolvida DEPOIS que o canal foi
+ * escolhido. Cada canal recebe o que sabe entregar, e o compilador recusa o
+ * resto.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHANNEL_ACCEPTS = exports.CHANNEL_KEYS = void 0;
+exports.channelAccepts = channelAccepts;
+exports.unavailableChannel = unavailableChannel;
+exports.resolveChannel = resolveChannel;
+const capabilities_js_1 = require("./capabilities.js");
+exports.CHANNEL_KEYS = ['email', 'whatsapp', 'sms', 'notification'];
+/** Quais conteúdos cada canal aceita. Consultado antes do envio, não dentro do adapter. */
+exports.CHANNEL_ACCEPTS = {
+    email: ['email'],
+    whatsapp: ['whatsapp_template', 'text'],
+    sms: ['text'],
+    notification: ['text'],
+};
+function channelAccepts(channel, content) {
+    return exports.CHANNEL_ACCEPTS[channel].includes(content.kind);
+}
+/**
+ * Canal indisponível.
+ *
+ * Deliberadamente NÃO simula entrega. Um adapter que responde `sent` sem enviar
+ * transforma a trilha em ficção: o escritório vê "cobrado" e o cliente nunca
+ * recebeu nada. Herdado da abstração da SC, que já acertou isso.
+ */
+function unavailableChannel(key, reason) {
+    return {
+        key,
+        providerName: 'none',
+        capabilities: capabilities_js_1.NO_PROVIDER_GUARANTEES,
+        isConfigured: () => false,
+        send: async () => ({ kind: 'unavailable', code: 'channel_not_configured', detail: reason }),
+    };
+}
+function resolveChannel(registry, key) {
+    return registry[key] ?? unavailableChannel(key, `canal ${key} não registrado`);
+}
+//# sourceMappingURL=channel.js.map

package/dist/cjs/communication/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/communication/channel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAsCH,wCAEC;AA0ED,gDAQC;AAID,wCAEC;AA7HD,uDAA2D;AAK9C,QAAA,YAAY,GAA0B,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;AAsBhG,2FAA2F;AAC9E,QAAA,eAAe,GAA0D;IACpF,KAAK,EAAE,CAAC,OAAO,CAAC;IAChB,QAAQ,EAAE,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,SAAgB,cAAc,CAAC,OAAmB,EAAE,OAAuB;IACzE,OAAO,uBAAe,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAmED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,GAAe,EAAE,MAAc;IAChE,OAAO;QACL,GAAG;QACH,YAAY,EAAE,MAAM;QACpB,YAAY,EAAE,wCAAsB;QACpC,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK;QACzB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC;AAID,SAAgB,cAAc,CAAC,QAAyB,EAAE,GAAe;IACvE,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAAC,CAAC;AACjF,CAAC"}