@baruk/core 0.3.0 → 0.4.2

package/dist/communication/stores/secrets.js

@@ -0,0 +1,122 @@
+/**
+ * `TenantSecretStore` sobre o Vault Engine — agora atrás de autorização real.
+ *
+ * `credentials.ts` já declarava a interface e já dizia por que o valor teria
+ * de vir do cofre (migração 0012), mas nenhum arquivo do repositório a
+ * implementava: `createChannelCredentialResolver` só era chamado em teste, e
+ * os três call sites de produção (`collection-cron.ts`, `routes/collections.ts`)
+ * seguiam presos a `environmentCredentialResolver()`. Uma referência
+ * `vault://...` resolvia para `undefined` em produção — não por bug, por
+ * ausência: o fio entre o cofre e o motor nunca foi ligado.
+ *
+ * Este módulo é esse fio. Não é um segundo cofre — reaproveita
+ * `vault/repository.ts` inteiro (RLS FORCE, AAD por tenant, envelope
+ * AES-256-GCM) e acrescenta só o que o motor precisava e o Vault não tinha:
+ * ler por NOME em vez de `id` (`revealSecretByName`).
+ *
+ * **O que mudou no lote C1A.1.** A primeira versão aceitava um
+ * `SecretAccessGrant` montado pelo CHAMADOR: `principal` e `reason` eram
+ * strings, e qualquer módulo interno podia declará-las e pedir decifração.
+ * Isso registrava quem disse ser — não provava quem era. Agora o store exige
+ * uma `WorkloadIdentity` autenticada (`rbac/workload.ts`), e cada `reveal()`
+ * consulta o banco, DENTRO da mesma transação, para saber se aquele principal
+ * tem `vault.credential.decrypt` NAQUELE tenant, para AQUELE propósito e sobre
+ * AQUELE nome de credencial. O grant deixou de ser declaração e virou linha em
+ * tabela que o papel da aplicação não consegue escrever.
+ *
+ * O `SecretAccessGrant` permanece — como REGISTRO DE AUDITORIA derivado da
+ * decisão, não como entrada. É o que vai para o `audit_log`.
+ */
+import { appendAudit } from '../../audit/audit.js';
+import { withContext } from '../../db/context.js';
+import { assertMintedWorkloadIdentity, authorizeWorkload, } from '../../rbac/workload.js';
+import { revealSecretByName } from '../../vault/repository.js';
+/** A permissão do catálogo RBAC exigida para decifrar. Uma só, específica. */
+export const VAULT_DECRYPT_PERMISSION = 'vault.credential.decrypt';
+const ACTOR_TYPE = 'automation';
+/**
+ * `TenantSecretStore` sobre o Vault Engine.
+ *
+ * `reveal(tenantId, name)` recebe `tenantId` POR CHAMADA — o store é
+ * construído uma vez, no processo, e serve qualquer tenant que o motor
+ * resolver depois. É o mesmo desenho de `createChannelCredentialResolver`:
+ * quem sabe o tenant é o CHAMADOR, nunca o store. Mas saber o tenant não
+ * autoriza: cada chamada é decidida contra os grants DAQUELE tenant.
+ *
+ * Deny-by-default em toda borda:
+ *  - identidade não emitida por `authenticateWorkload` → lança na CONSTRUÇÃO
+ *  - `tenantId`/`name` vazios          → nega sem tocar o banco
+ *  - sessão expirada                   → nega, audita `denied`
+ *  - principal revogado/desabilitado   → nega, audita `denied`
+ *  - sem grant casando tenant+permissão+propósito+recurso → nega, audita `denied`
+ *  - nome inexistente/revogado/de outro tenant → nega (RLS filtra a linha)
+ *  - vencida (`expires_at`)            → nega, NUNCA decifra
+ *  - erro de infraestrutura            → propaga (não é "ausência"; é falha)
+ *
+ * Toda chamada que chega ao banco grava uma linha em `audit_log` —
+ * sucesso, ausência ou negação. O reveal nunca é silencioso.
+ */
+export function createPostgresTenantSecretStore(db, keyring, identity, options) {
+    // Identidade forjada não passa da construção. Um `ForbiddenError` no boot é
+    // muito melhor que um `undefined` na primeira tentativa de envio.
+    assertMintedWorkloadIdentity(identity);
+    const purpose = options?.purpose;
+    const correlationId = options?.correlationId ?? null;
+    const auditBase = (grantId, denyReason) => ({
+        purpose,
+        principal: identity.principalKey,
+        principalId: identity.principalId,
+        permission: VAULT_DECRYPT_PERMISSION,
+        grantId,
+        correlationId,
+        ...(denyReason ? { denyReason } : {}),
+    });
+    return {
+        async reveal(tenantId, name) {
+            const trimmedTenant = tenantId?.trim() ?? '';
+            const trimmedName = name?.trim() ?? '';
+            // Contexto insuficiente: nem abre transação. Não há tenant para auditar
+            // contra, e um GUC vazio não é "nenhum tenant" — é erro de outra camada.
+            if (!trimmedTenant || !trimmedName)
+                return undefined;
+            return withContext(db, { tenantId: trimmedTenant }, async (tx) => {
+                const audit = async (result, grantId, denyReason, resourceId) => {
+                    await appendAudit(tx, {
+                        actorType: ACTOR_TYPE,
+                        // `audit_log.actor_id` tem FK para `"user"(id)` — um principal de
+                        // workload não é usuário e não cabe ali. A identidade vai em
+                        // `metadata.principalId`, que é um uuid, não um segredo.
+                        actorId: null,
+                        action: 'vault.reveal',
+                        resourceType: 'vault_credential',
+                        ...(resourceId ? { resourceId } : {}),
+                        result,
+                        metadata: { name: trimmedName, ...auditBase(grantId, denyReason) },
+                    });
+                };
+                const decision = await authorizeWorkload(tx, identity, {
+                    tenantId: trimmedTenant,
+                    permission: VAULT_DECRYPT_PERMISSION,
+                    purpose,
+                    resource: trimmedName,
+                });
+                if (!decision.allowed) {
+                    await audit('denied', null, decision.denyReason);
+                    return undefined;
+                }
+                const found = await revealSecretByName(tx, keyring, trimmedTenant, trimmedName);
+                if (!found) {
+                    await audit('failure', decision.grantId, 'not_found_or_revoked');
+                    return undefined;
+                }
+                if (found.status === 'expired') {
+                    await audit('failure', decision.grantId, 'expired', found.meta.id);
+                    return undefined;
+                }
+                await audit('success', decision.grantId, undefined, found.meta.id);
+                return found.secret;
+            });
+        },
+    };
+}
+//# sourceMappingURL=secrets.js.map

package/dist/communication/stores/secrets.js.map

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

package/dist/communication/template-provider.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Submissão de template de mensagem — contrato do DOMÍNIO.
+ *
+ * ## Por que existe separado do adapter
+ *
+ * Canais que exigem template aprovado não são exclusividade do WhatsApp: RCS e
+ * boa parte dos provedores de SMS transacional pedem o mesmo. O que o domínio
+ * precisa expressar é a INTENÇÃO — "submeter este texto, com estas variáveis,
+ * nesta categoria, para aprovação" — e não `POST /{waba-id}/message_templates`.
+ *
+ * Nada aqui menciona Meta, WABA ou Graph API. Trocar de provider é escrever
+ * outro adapter; nenhuma linha de catálogo, régua ou motor muda.
+ *
+ * ## O que o domínio NÃO decide
+ *
+ * O texto. Ele vem do consumidor, porque a forma como um escritório fala com o
+ * cliente é dele — o motor guarda e resolve templates, e não contém nenhum
+ * (adendo §14).
+ */
+import type { ChannelKey } from './channel.js';
+/**
+ * Categoria da mensagem, no vocabulário do domínio.
+ *
+ * Minúsculas de propósito: o adapter traduz para o que o provider espera. Um
+ * enum já no formato da Meta faria o domínio carregar a convenção dela.
+ *
+ * A distinção é material e não estética: `utility` é transacional, decorre de
+ * relação contratual e custa menos; `marketing` exige opt-in de outra natureza.
+ * Classificar errado é problema de conformidade, não de campo.
+ */
+export type TemplateCategory = 'utility' | 'marketing' | 'authentication';
+export interface TemplateSubmission {
+    /** Nome técnico. Estável — entra no envio e não pode mudar depois de aprovado. */
+    name: string;
+    /** Código de idioma no formato do provider (`pt_BR`). */
+    language: string;
+    category: TemplateCategory;
+    /**
+     * Corpo com marcadores posicionais `{{1}}`, `{{2}}`… A ordem é contrato com
+     * quem renderiza: trocar duas variáveis sem re-submeter manda o valor no
+     * lugar do nome, e o provider aceita — para ele são strings.
+     */
+    bodyText: string;
+    /**
+     * Um exemplo por variável, na mesma ordem.
+     *
+     * Não é enfeite: revisor humano reprova template cujo exemplo não deixa claro
+     * o que cada marcador recebe. Exemplos NUNCA devem conter dado real de
+     * cliente — vão para a fila de revisão de um terceiro.
+     */
+    bodyExample?: string[];
+}
+export type TemplateSubmissionRejection = 
+/** Nome já usado nesta conta. */
+'duplicate_name'
+/** Conteúdo recusado pelas regras do provider. */
+ | 'invalid_content'
+/** Credencial/permissão nossa. */
+ | 'unauthorized'
+/** Limite de taxa. */
+ | 'rate_limited' | 'network' | 'provider_error';
+export type TemplateSubmissionResult = {
+    ok: true;
+    /** Identificador do template no provider. Não é segredo. */
+    providerRef?: string;
+    /** Estado no momento da submissão — quase sempre pendente de revisão. */
+    status: string;
+    category?: string;
+} | {
+    ok: false;
+    reason: TemplateSubmissionRejection;
+};
+/**
+ * Porta de gestão de template, implementada por adapter de canal.
+ *
+ * `submit` é a única operação de ESCRITA aqui, e ela é deliberadamente estreita:
+ * não expõe edição nem remoção. Apagar um template aprovado quebra todo envio
+ * que o referencia, e essa não é uma capacidade que uma rota administrativa
+ * deva ganhar de graça.
+ */
+export interface TemplateManagementProvider {
+    readonly channel: ChannelKey;
+    submit(submission: TemplateSubmission): Promise<TemplateSubmissionResult>;
+}
+//# sourceMappingURL=template-provider.d.ts.map

package/dist/communication/template-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.d.ts","sourceRoot":"","sources":["../../src/communication/template-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE1E,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,MAAM,2BAA2B;AACrC,iCAAiC;AAC/B,gBAAgB;AAClB,kDAAkD;GAChD,iBAAiB;AACnB,kCAAkC;GAChC,cAAc;AAChB,sBAAsB;GACpB,cAAc,GACd,SAAS,GACT,gBAAgB,CAAC;AAErB,MAAM,MAAM,wBAAwB,GAChC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,CAAA;CAAE,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,MAAM,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC3E"}

package/dist/communication/template-provider.js

@@ -0,0 +1,21 @@
+/**
+ * Submissão de template de mensagem — contrato do DOMÍNIO.
+ *
+ * ## Por que existe separado do adapter
+ *
+ * Canais que exigem template aprovado não são exclusividade do WhatsApp: RCS e
+ * boa parte dos provedores de SMS transacional pedem o mesmo. O que o domínio
+ * precisa expressar é a INTENÇÃO — "submeter este texto, com estas variáveis,
+ * nesta categoria, para aprovação" — e não `POST /{waba-id}/message_templates`.
+ *
+ * Nada aqui menciona Meta, WABA ou Graph API. Trocar de provider é escrever
+ * outro adapter; nenhuma linha de catálogo, régua ou motor muda.
+ *
+ * ## O que o domínio NÃO decide
+ *
+ * O texto. Ele vem do consumidor, porque a forma como um escritório fala com o
+ * cliente é dele — o motor guarda e resolve templates, e não contém nenhum
+ * (adendo §14).
+ */
+export {};
+//# sourceMappingURL=template-provider.js.map

package/dist/communication/template-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-provider.js","sourceRoot":"","sources":["../../src/communication/template-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/communication/template.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Modelo de template do motor compartilhado.
+ *
+ * O motor guarda e resolve templates. Ele **não contém nenhum**: nenhuma string
+ * de cobrança da SC, nenhum texto de assinatura da Dental. O catálogo é dado do
+ * consumidor, e é assim que "motor compartilhado" não vira "monolito central
+ * cheio de regra de negócio alheia" (adendo §14).
+ *
+ * O que o motor sabe é o que todo canal precisa que alguém saiba: qual template
+ * vale para este contexto, nesta versão, neste idioma, e se ele está aprovado.
+ */
+import type { ChannelKey } from './channel.js';
+import type { CommunicationContext } from './context.js';
+/**
+ * `approved` é exigência real do canal, não burocracia interna: WhatsApp fora da
+ * janela de 24h só aceita template previamente aprovado pelo provedor. Um
+ * template `draft` que chega ao adapter é recusado pelo provider com erro
+ * permanente — e é muito melhor recusá-lo aqui, com um motivo legível, do que
+ * gastar a tentativa para descobrir lá.
+ */
+export type TemplateStatus = 'draft' | 'pending_approval' | 'approved' | 'rejected' | 'retired';
+export interface TemplateKey {
+    /** Escopo. `tenantId` nulo = template do produto, válido para todos os tenants dele. */
+    tenantId: string | null;
+    product: string;
+    /** Marca. Nulo = vale para qualquer marca do produto. */
+    brand: string | null;
+    channel: ChannelKey;
+    /** Evento de negócio: `billing.dunning.d3`, `subscription.payment_due`. */
+    eventType: string;
+    locale: string;
+}
+export interface TemplateRecord extends TemplateKey {
+    /** Estável dentro do escopo. É o que entra na chave de idempotência. */
+    version: string;
+    status: TemplateStatus;
+    /**
+     * Nome do template DO LADO DO PROVIDER, quando o canal exige registro prévio.
+     *
+     * Só o WhatsApp usa hoje. Vive aqui, e não no adapter, porque o mesmo evento
+     * pode estar registrado com nomes diferentes em providers diferentes — e
+     * descobrir isso no adapter significaria o adapter conhecendo o catálogo.
+     */
+    providerTemplateName?: string;
+    /** Variáveis que o template espera, na ORDEM em que o canal as substitui. */
+    variables: readonly string[];
+    /** Corpo, para canais de texto livre. Ausente quando o provider é o dono do corpo. */
+    body?: string;
+    subject?: string;
+}
+export type TemplateRejection = 'not_found' | 'not_approved' | 'variable_mismatch';
+export type TemplateResolution = {
+    ok: true;
+    template: TemplateRecord;
+} | {
+    ok: false;
+    reason: TemplateRejection;
+    detail: string;
+};
+export interface TemplateStore {
+    /** Todos os candidatos para o evento/canal, em qualquer escopo. */
+    candidates(ctx: CommunicationContext, channel: ChannelKey, eventType: string, locale: string): Promise<TemplateRecord[]>;
+}
+/**
+ * Resolve o template mais específico e aprovado.
+ *
+ * Um candidato de escopo mais específico porém NÃO aprovado não silencia os
+ * menos específicos — cair para o padrão do produto é melhor que não enviar. Mas
+ * também não é escolhido: enviar um rascunho seria pior que os dois.
+ */
+export declare function resolveTemplate(store: TemplateStore, ctx: CommunicationContext, channel: ChannelKey, eventType: string, locale: string): Promise<TemplateResolution>;
+/**
+ * Ordena as variáveis do consumidor na ordem que o template declara.
+ *
+ * Devolve falha quando falta alguma, em vez de substituir por vazio. Um template
+ * de cobrança com o valor em branco — "consta em aberto o valor de ." — chega ao
+ * cliente parecendo defeito do escritório, e o WhatsApp recusa a mensagem de
+ * qualquer forma quando um parâmetro posicional vem vazio.
+ */
+export declare function orderVariables(template: TemplateRecord, values: Record<string, string>): {
+    ok: true;
+    ordered: string[];
+} | {
+    ok: false;
+    missing: string[];
+};
+//# sourceMappingURL=template.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/communication/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAEhG,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;IACpB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,UAAU,CACR,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAC9B;AAaD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAiB7B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAMpE"}

package/dist/communication/template.js

@@ -0,0 +1,59 @@
+/**
+ * Modelo de template do motor compartilhado.
+ *
+ * O motor guarda e resolve templates. Ele **não contém nenhum**: nenhuma string
+ * de cobrança da SC, nenhum texto de assinatura da Dental. O catálogo é dado do
+ * consumidor, e é assim que "motor compartilhado" não vira "monolito central
+ * cheio de regra de negócio alheia" (adendo §14).
+ *
+ * O que o motor sabe é o que todo canal precisa que alguém saiba: qual template
+ * vale para este contexto, nesta versão, neste idioma, e se ele está aprovado.
+ */
+/**
+ * Especificidade do escopo — maior vence.
+ *
+ * Tenant+marca (3) > tenant (2) > marca do produto (1) > produto (0). Um
+ * escritório que personalizou o próprio texto não pode ser sobrescrito pelo
+ * padrão do produto só porque o padrão foi atualizado depois.
+ */
+function specificity(t) {
+    return (t.tenantId ? 2 : 0) + (t.brand ? 1 : 0);
+}
+/**
+ * Resolve o template mais específico e aprovado.
+ *
+ * Um candidato de escopo mais específico porém NÃO aprovado não silencia os
+ * menos específicos — cair para o padrão do produto é melhor que não enviar. Mas
+ * também não é escolhido: enviar um rascunho seria pior que os dois.
+ */
+export async function resolveTemplate(store, ctx, channel, eventType, locale) {
+    const all = await store.candidates(ctx, channel, eventType, locale);
+    if (all.length === 0) {
+        return { ok: false, reason: 'not_found', detail: `sem template para ${eventType}/${channel}` };
+    }
+    const approved = all.filter((t) => t.status === 'approved');
+    if (approved.length === 0) {
+        return {
+            ok: false,
+            reason: 'not_approved',
+            detail: `template de ${eventType}/${channel} existe mas não está aprovado`,
+        };
+    }
+    const best = approved.reduce((a, b) => (specificity(b) > specificity(a) ? b : a));
+    return { ok: true, template: best };
+}
+/**
+ * Ordena as variáveis do consumidor na ordem que o template declara.
+ *
+ * Devolve falha quando falta alguma, em vez de substituir por vazio. Um template
+ * de cobrança com o valor em branco — "consta em aberto o valor de ." — chega ao
+ * cliente parecendo defeito do escritório, e o WhatsApp recusa a mensagem de
+ * qualquer forma quando um parâmetro posicional vem vazio.
+ */
+export function orderVariables(template, values) {
+    const missing = template.variables.filter((name) => values[name] === undefined || values[name] === '');
+    if (missing.length > 0)
+        return { ok: false, missing: [...missing] };
+    return { ok: true, ordered: template.variables.map((name) => values[name]) };
+}
+//# sourceMappingURL=template.js.map

package/dist/communication/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/communication/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4DH;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,CAAiB;IACpC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,GAAyB,EACzB,OAAmB,EACnB,SAAiB,EACjB,MAAc;IAEd,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACpE,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,qBAAqB,SAAS,IAAI,OAAO,EAAE,EAAE,CAAC;IACjG,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,cAAc;YACtB,MAAM,EAAE,eAAe,SAAS,IAAI,OAAO,+BAA+B;SAC3E,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAwB,EACxB,MAA8B;IAE9B,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CACvC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAC5D,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;IACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAE,CAAC,EAAE,CAAC;AAChF,CAAC"}

package/dist/communication/webhook-subscription.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Diagnóstico da ASSINATURA de webhooks — por que o status não chega.
+ *
+ * ## O que este módulo responde
+ *
+ * Uma mensagem aceita pela Meta não produz `delivered` sozinha: o status volta
+ * por webhook, e o webhook depende de duas coisas que vivem em lugares
+ * DIFERENTES e são configuradas por caminhos diferentes:
+ *
+ *   1. **A WABA assina o app.** `POST {waba}/subscribed_apps` — feito pelo
+ *      Embedded Signup, no código (`subscribeAppToWaba`).
+ *   2. **O app assina o objeto e declara para onde entregar.**
+ *      `{app}/subscriptions` com `object=whatsapp_business_account`,
+ *      `callback_url`, `verify_token` e os `fields` (`messages`) — configurado
+ *      no painel do app, uma vez, e NUNCA automatizado nesta casa.
+ *
+ * Ter (1) e não ter (2) produz exatamente o sintoma observado em 2026-09-01: a
+ * Meta aceita a mensagem, devolve `wamid`, e não chama ninguém. Do lado de cá
+ * não há erro nenhum para ver — o silêncio é a única evidência, e silêncio não
+ * aponta causa.
+ *
+ * ## Por que é leitura pura
+ *
+ * Este módulo não corrige nada. Corrigir a assinatura do app é mutação externa
+ * que muda para onde a Meta entrega os eventos de TODAS as WABAs do app — não é
+ * coisa que uma rota de diagnóstico deva poder fazer por engano.
+ *
+ * ## Sobre o token de app
+ *
+ * `{app_id}|{app_secret}` é a forma que a Graph API aceita para chamadas em
+ * nome do app. O segredo entra na composição do token e **não sai deste
+ * módulo**: nem no retorno, nem em erro, nem em log. As respostas carregam só
+ * `callback_url` (que é público, é o nosso endpoint), os campos assinados e o
+ * estado — nunca o `verify_token`, que a Graph tampouco devolve.
+ */
+import type { GraphClientOptions } from './onboarding.js';
+/** Um app assinante de uma WABA, como a Meta o descreve. */
+export interface SubscribedApp {
+    id: string;
+    name?: string;
+}
+/** Uma assinatura de objeto no nível do APP. */
+export interface AppSubscription {
+    object: string;
+    callbackUrl?: string;
+    active?: boolean;
+    /** Campos assinados: `messages`, `message_template_status_update`, etc. */
+    fields: string[];
+}
+/** Vocabulário fechado do domínio. A mensagem do provider nunca sai daqui. */
+export type SubscriptionRejection = 'unauthorized' | 'not_found' | 'network' | 'provider_error';
+export type SubscriptionProbe<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: SubscriptionRejection;
+};
+/**
+ * Quais apps a WABA assina — `GET {waba}/subscribed_apps`.
+ *
+ * Usa o token de NEGÓCIO do tenant (o mesmo do despacho): é a WABA do cliente,
+ * e quem tem direito a lê-la é quem tem a credencial dela.
+ */
+export declare function readWabaSubscribedApps(input: {
+    wabaId: string;
+    accessToken: string;
+}, opts?: GraphClientOptions): Promise<SubscriptionProbe<SubscribedApp[]>>;
+/**
+ * O que o APP assina, e para onde entrega — `GET {app}/subscriptions`.
+ *
+ * Exige token de APP. O segredo é consumido aqui e não atravessa a fronteira:
+ * o retorno tem `callback_url`, campos e estado, nada mais.
+ */
+export declare function readAppSubscriptions(input: {
+    appId: string;
+    appSecret: string;
+}, opts?: GraphClientOptions): Promise<SubscriptionProbe<AppSubscription[]>>;
+/**
+ * Pede à Meta que ENTREGUE um evento de amostra no callback do app.
+ *
+ * `POST {app}/subscriptions_sample` — o mesmo botão "Testar" do painel de
+ * Webhooks, pela API. **Não manda mensagem de WhatsApp para ninguém**: a Meta
+ * monta um payload sintético do campo pedido e o entrega no `callback_url` já
+ * configurado, assinado como um evento real.
+ *
+ * ## Por que isto vale mais que olhar a configuração
+ *
+ * A leitura acima diz que a configuração ESTÁ certa. Não diz que a entrega
+ * ACONTECE. São afirmações diferentes, e a segunda é a que interessa quando o
+ * sintoma é silêncio: se a amostra chega, o caminho
+ * `Meta → nosso endpoint → assinatura` está provado e a causa é upstream — a
+ * Meta não está GERANDO status para este app. Se a amostra não chega, o
+ * problema é o caminho, e a configuração correta era uma pista falsa.
+ *
+ * É a única sonda que discrimina as duas sem gastar uma mensagem real.
+ *
+ * ## Não altera nada
+ *
+ * Não cria, não muda e não remove assinatura. O único efeito externo é uma
+ * requisição HTTP que a Meta faz ao nosso próprio endpoint público.
+ */
+export declare function sendWebhookTestEvent(input: {
+    appId: string;
+    appSecret: string;
+    object?: string;
+    field?: string;
+}, opts?: GraphClientOptions): Promise<SubscriptionProbe<{
+    requested: true;
+}>>;
+/**
+ * Configurações administrativas do app, como a Meta as tem hoje.
+ *
+ * ## Para que serve
+ *
+ * As URLs legais, os domínios e os e-mails do app são o que a análise da Meta
+ * confere primeiro — e são exatamente o tipo de campo que alguém "lembra" de ter
+ * configurado. Ler antes de mexer é o que separa corrigir de sobrescrever.
+ *
+ * ## O que NÃO vem aqui
+ *
+ * O modo do app (desenvolvimento × ativo) e o nível de acesso de cada permissão
+ * **não são expostos** por esta borda da Graph API. Devolver `null` para eles é
+ * dizer a verdade: quem precisar deles tem de olhar o painel. Inventar um campo
+ * derivado — "se tem X então está publicado" — produziria uma matriz de
+ * prontidão que parece completa e não é.
+ */
+export interface AppSettings {
+    id: string;
+    name?: string;
+    category?: string;
+    privacyPolicyUrl?: string;
+    termsOfServiceUrl?: string;
+    /** Instruções de exclusão. A Meta aceita URL OU callback; são campos distintos. */
+    dataDeletionInstructionsUrl?: string;
+    deauthCallbackUrl?: string;
+    appDomains: string[];
+    contactEmail?: string;
+    /** Onde a Meta manda aviso administrativo. Distinto do contato público. */
+    notificationEmail?: string;
+    iconUrl?: string;
+    link?: string;
+    /**
+     * Campos que esta credencial não conseguiu ler.
+     *
+     * Ausente da resposta ≠ ausente na Meta. A distinção decide se alguém precisa
+     * ir ao painel conferir — e sem ela um campo restrito viraria "não
+     * configurado" numa matriz de prontidão.
+     */
+    unreadableFields: string[];
+}
+export declare function readAppSettings(input: {
+    appId: string;
+    appSecret: string;
+}, opts?: GraphClientOptions): Promise<SubscriptionProbe<AppSettings>>;
+//# sourceMappingURL=webhook-subscription.d.ts.map

package/dist/communication/webhook-subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-subscription.d.ts","sourceRoot":"","sources":["../../src/communication/webhook-subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAEhG,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAqCxE;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC9C,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,aAAa,EAAE,CAAC,CAAC,CAiB7C;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC3C,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,eAAe,EAAE,CAAC,CAAC,CAiC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5E,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,CA+BjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAwBD,wBAAsB,eAAe,CACnC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC3C,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAuDzC"}