@adatechnology/notification-contracts

Tipos, schemas zod e portas do trio de notificações. Sem comportamento de runtime — o módulo valida com ele, os drivers implementam as portas dele, o frontend tipa as chamadas com ele, e mudança de contrato quebra todos em compile-time em vez de em produção.

Única dependência: zod.

Instalação

bun add @adatechnology/notification-contracts

O que traz

DeliveryAttemptResult é união discriminada

type DeliveryAttemptResult =
  | { outcome: 'sent'; providerMessageId?: string }
  | { outcome: 'retriable'; errorCode: string; message: string }
  | { outcome: 'permanent'; errorCode: string; message: string }
  | { outcome: 'invalid-target'; errorCode: string; message: string }

Quem classifica é o driver, nunca o módulo: só ele conhece o vocabulário de erro do provedor. invalid-target é separado de permanent porque tem consequência própria — o device é desativado ou o e-mail entra na lista de supressão, em vez de a fila insistir para sempre num token morto.

Invariantes

• companyId nunca entra em schema de corpo. Vem do contexto autenticado do host.
• Nenhum tipo de HTTP aqui. Rota é assunto do @adatechnology/module-http; este pacote é domínio. Um contracts que conhece a palavra "rota" acaba amarrado ao transporte.
• Nenhuma porta valida token. O host resolve identidade e entrega pronta (security.md §2).
• Alvo de entrega (telefone, e-mail) nunca aparece cru em log — ver maskTarget/hashTarget no módulo.

Modelo padrão de e-mail (notification.standard-email)

Moldura única de todo e-mail do sistema (canal email, locale pt-BR). Identidade (logo e nome), assinante e rodapé são marcação do modelo, com variáveis — a empresa edita o HTML, não o código.

• Variáveis do sistema (HTML montado e escapado pelo sistema, usadas só pelo nome): STANDARD_EMAIL_SYSTEM_HTML_VARIABLES (logoEmpresa, corpoMensagem, listaAnexos, faixaResposta, marcasRodape). O resto é texto, escapado por valor.
• Obrigatórias: STANDARD_EMAIL_REQUIRED_VARIABLES (corpo, logo, nome da empresa, assinante, rodapé da plataforma, marcas). Modelo sem uma delas é inutilizável.
• Nenhuma variável em atributo ou style — findUnsafeEmailHtml recusa.
• assessStandardEmailTemplate(html) → { usable, missing, unsafe }; renderStandardEmail renderiza com texto puro (htmlToPlainText) e tooLarge acima de STANDARD_EMAIL_HTML_MAX_BYTES. STANDARD_EMAIL_BUILTIN_TEMPLATE é o embutido (source: 'builtin', version: 0).
• Regras genéricas de e-mail HTML (reusáveis fora do padrão): findUnsafeEmailHtml (regras event, placeholder_in_tag, scheme, tag), htmlToPlainText, escapeEmailHtml, interpolateEmailHtml, buildInitials, renderEmailLogoHtml, renderEmailMarksHtml, STANDARD_EMAIL_THEME.

Licença

MIT © Ada Technology