@ecdt/events-engine 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# @ecdt/events-engine
+
+Publicador de eventos para o coletor do motor de eventos. Não tem dependências nem usa API exclusiva do
+Node, então roda no servidor e no browser.
+
+---
+
+## Instalação
+
+```bash
+npm install @ecdt/events-engine
+```
+
+---
+
+## `criarMotorEventos(options)`
+
+Cria o publicador de um produtor, uma vez, na inicialização do serviço.
+
+```js
+const { criarMotorEventos } = require('@ecdt/events-engine');
+
+const motor = criarMotorEventos({ produtor: 'meu-servico' });
+
+motor.publicarEventoDaRequisicao(req, {
+  tipo: 'meu_evento',
+  payload: { campo: 'valor' },
+});
+```
+
+| Opção | Default | Descrição |
+|---|---|---|
+| `produtor` | `desconhecido` | Identificador de quem publica, no formato `^[a-z0-9-]+$` |
+| `url` | `MOTOR_EVENTOS_URL` | URL completa do coletor; a lib não monta caminho nenhum |
+| `cookieVisitante` | `MOTOR_EVENTOS_COOKIE_VISITANTE` | Nome do cookie que guarda o identificador anônimo |
+| `timeoutMs` | `2000` | Aborta a requisição |
+| `aoFalhar` | `console.error` | Recebe a mensagem quando a publicação não acontece |
+
+O produtor vai no header `x-ecdt-produtor` de toda publicação. Informe-o como constante no código:
+fora do formato, a lib avisa com `console.warn` e publica como `desconhecido`, sem lançar. Ele só se
+define na inicialização; a chamada não consegue trocá-lo.
+
+As demais opções valem de padrão para toda publicação, e a chamada prevalece sobre elas. As variáveis de
+ambiente são lidas a cada publicação, e só quando existe `process`; no browser, passe `url` na
+inicialização.
+
+O objeto devolvido expõe `produtor` (o valor efetivo, já validado), `publicarEvento` e
+`publicarEventoDaRequisicao`.
+
+---
+
+### `publicarEvento(options)`
+
+Envia um evento para o coletor, sem bloquear o fluxo que o gerou.
+
+```js
+motor.publicarEvento({
+  tipo: 'meu_evento',
+  autorizacao: req.headers.authorization,
+  payload: { campo: 'valor' },
+});
+```
+
+| Opção | Default | Descrição |
+|---|---|---|
+| `tipo` | — | Nome do evento, em `snake_case` |
+| `autorizacao` | — | Header `Authorization` da requisição que originou o evento |
+| `idVisitante` | — | Identificador anônimo, para quando não há token |
+| `payload` | `{}` | Campos do evento |
+| `url`, `timeoutMs`, `aoFalhar` | os da inicialização | Sobrescrevem o padrão só nesta chamada |
+
+A identidade do usuário sai do token, nunca do corpo: o coletor a resolve a partir do `Authorization`
+repassado. Quando não há token — rota pública, visitante anônimo — vale o `idVisitante`, que vai no
+corpo como `id_visitante`. Ele não é identidade autenticada, é um identificador de correlação, e por
+isso pode vir do corpo da requisição. Basta um dos dois.
+
+Sem `tipo`, ou sem nenhum dos dois identificadores, a função não faz nada; sem `url` ela ainda registra
+um `console.warn`, porque url ausente é configuração faltando e não um evento que não se aplica.
+
+**A função nunca lança e nunca devolve promise.** O evento é secundário ao fluxo que o gerou —
+falha de publicação não pode virar erro de quem chamou, e o retorno `undefined` impede que alguém
+consiga dar `await` e acoplar a latência do request ao coletor.
+
+---
+
+### `publicarEventoDaRequisicao(req, options)`
+
+O mesmo publish, montado a partir da requisição que gerou o evento. Resolve o token pelo header
+`Authorization` e o identificador anônimo pelo corpo (`id_visitante`) ou pelo cookie, nessa ordem.
+
+| Opção | Default | Descrição |
+|---|---|---|
+| `tipo`, `payload`, `url`, `timeoutMs`, `aoFalhar` | — | Idênticos ao `publicarEvento` |
+| `cookieVisitante` | o da inicialização | Nome do cookie que guarda o identificador anônimo |
+
+Sem `cookieVisitante` configurado, só o corpo alimenta o `id_visitante`. Também não lança em
+nenhuma hipótese, inclusive com `req` sem `headers` nem `body`.
+
+---
+
+## `lerCookie`, `idDoCookie` e `sanitizarId`
+
+Leitura do header `Cookie`, sem dependência de framework.
+
+```js
+const { idDoCookie } = require('@ecdt/events-engine');
+
+const idVisitante = idDoCookie(req.headers.cookie, 'nome_do_cookie');
+```
+
+| Função | Devolve |
+|---|---|
+| `lerCookie(cabecalho, nome)` | Valor cru do cookie, ou `null` |
+| `idDoCookie(cabecalho, nome, { maxLen })` | O identificador: aceita o cookie como string simples ou como JSON com campo `id`, decodifica o valor e corta em `maxLen` (100 por padrão) |
+| `sanitizarId(valor, maxLen)` | O mesmo corte e validação, para identificador que veio de outro lugar |
+
+O match do nome é exato, então `nome_antigo` não casa com `nome`. Nenhuma das três lança: entrada
+que não é string vira `null`.
+
+---
+
+## Migrando do `@ecdt/server-common`
+
+O publicador e as funções de cookie saíram do `@ecdt/server-common` na 2.0.0. As assinaturas das
+chamadas não mudaram; o que muda é criar o publicador antes, com o produtor.
+
+```diff
+-const { publicarEventoDaRequisicao } = require('@ecdt/server-common');
++const { criarMotorEventos } = require('@ecdt/events-engine');
++
++const { publicarEventoDaRequisicao } = criarMotorEventos({ produtor: 'meu-servico' });
+
+ publicarEventoDaRequisicao(req, { tipo, payload, cookieVisitante });
+```
+
+`lerCookie`, `idDoCookie` e `sanitizarId` só trocam de pacote no `require`.
+
+---
+
+## TypeScript
+
+O pacote publica os tipos em `src/index.d.ts`. As interfaces exportadas são `OpcoesDoMotor`,
+`MotorEventos`, `PublicarEventoOptions`, `PublicarEventoDaRequisicaoOptions` e `IdDoCookieOptions`.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@ecdt/events-engine",
+  "version": "1.0.0",
+  "description": "Publicador de eventos para o coletor do motor de eventos, sem dependencias e sem API exclusiva do Node",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

package/src/cookie.js

@@ -0,0 +1,43 @@
+const TAMANHO_MAXIMO_PADRAO = 100;
+
+function sanitizarId(valor, maxLen = TAMANHO_MAXIMO_PADRAO) {
+    if (typeof valor !== "string") return null;
+
+    const limpo = valor.trim();
+    return limpo ? limpo.slice(0, maxLen) : null;
+}
+
+function lerCookie(cabecalho, nome) {
+    if (typeof cabecalho !== "string" || typeof nome !== "string") return null;
+
+    for (const parte of cabecalho.split(";")) {
+        const separador = parte.indexOf("=");
+        if (separador === -1) continue;
+        if (parte.slice(0, separador).trim() !== nome) continue;
+        return parte.slice(separador + 1).trim();
+    }
+
+    return null;
+}
+
+function idDoCookie(cabecalho, nome, { maxLen = TAMANHO_MAXIMO_PADRAO } = {}) {
+    const bruto = lerCookie(cabecalho, nome);
+    if (!bruto) return null;
+
+    let valor = bruto;
+    try {
+        valor = decodeURIComponent(bruto);
+    } catch (_erroDeEncoding) {
+        valor = bruto;
+    }
+
+    try {
+        const conteudo = JSON.parse(valor);
+        const id = conteudo && typeof conteudo === "object" ? conteudo.id : conteudo;
+        return sanitizarId(typeof id === "string" ? id : String(id ?? ""), maxLen);
+    } catch (_naoEhJson) {
+        return sanitizarId(valor, maxLen);
+    }
+}
+
+module.exports = { lerCookie, idDoCookie, sanitizarId };

package/src/index.d.ts

@@ -0,0 +1,51 @@
+export interface OpcoesDoMotor {
+  /** Identificador de quem publica, no formato `^[a-z0-9-]+$`. Ausente ou fora do formato vira `desconhecido`. */
+  produtor?: string;
+  /** URL completa do coletor. Default: env `MOTOR_EVENTOS_URL`, lida a cada publicação. */
+  url?: string;
+  /** Nome do cookie com o identificador anônimo. Default: env `MOTOR_EVENTOS_COOKIE_VISITANTE`. */
+  cookieVisitante?: string;
+  /** Tempo máximo de cada publicação. Default: 2000. */
+  timeoutMs?: number;
+  /** Recebe a mensagem quando a publicação não acontece. Default: `console.error`. */
+  aoFalhar?: (mensagem: string) => void;
+}
+
+export interface PublicarEventoOptions {
+  tipo: string;
+  autorizacao?: string;
+  idVisitante?: string;
+  payload?: Record<string, unknown>;
+  url?: string;
+  timeoutMs?: number;
+  aoFalhar?: (mensagem: string) => void;
+}
+
+export interface PublicarEventoDaRequisicaoOptions
+  extends Omit<PublicarEventoOptions, 'autorizacao' | 'idVisitante'> {
+  cookieVisitante?: string;
+}
+
+export interface MotorEventos {
+  /** O produtor efetivo, já validado. */
+  readonly produtor: string;
+  publicarEvento(options?: PublicarEventoOptions): void;
+  publicarEventoDaRequisicao(req: unknown, options?: PublicarEventoDaRequisicaoOptions): void;
+}
+
+/** Opções da inicialização viram padrão de toda publicação; o produtor só se define aqui. */
+export declare function criarMotorEventos(options?: OpcoesDoMotor): MotorEventos;
+
+export interface IdDoCookieOptions {
+  maxLen?: number;
+}
+
+export declare function lerCookie(cabecalho: unknown, nome: string): string | null;
+
+export declare function idDoCookie(
+  cabecalho: unknown,
+  nome: string,
+  options?: IdDoCookieOptions
+): string | null;
+
+export declare function sanitizarId(valor: unknown, maxLen?: number): string | null;

package/src/index.js

@@ -0,0 +1,4 @@
+const { criarMotorEventos } = require("./publicador.js");
+const { lerCookie, idDoCookie, sanitizarId } = require("./cookie.js");
+
+module.exports = { criarMotorEventos, lerCookie, idDoCookie, sanitizarId };

package/src/publicador.js

@@ -0,0 +1,149 @@
+const { idDoCookie, sanitizarId } = require("./cookie.js");
+
+const TIMEOUT_PADRAO_MS = 2000;
+const PRODUTOR_PADRAO = "desconhecido";
+const FORMATO_DO_PRODUTOR = /^[a-z0-9-]+$/;
+const CABECALHO_DO_PRODUTOR = "x-ecdt-produtor";
+
+function lerAmbiente(nome) {
+    return typeof process !== "undefined" ? process.env?.[nome] : undefined;
+}
+
+function resolverProdutor(produtor) {
+    if (produtor === undefined || produtor === null) {
+        return PRODUTOR_PADRAO;
+    }
+
+    if (typeof produtor === "string" && FORMATO_DO_PRODUTOR.test(produtor)) {
+        return produtor;
+    }
+
+    console.warn(`motorEventos: produtor fora do formato ${FORMATO_DO_PRODUTOR}, publicando como ${PRODUTOR_PADRAO}`);
+    return PRODUTOR_PADRAO;
+}
+
+function urlConfigurada(url) {
+    const configurada = url ?? lerAmbiente("MOTOR_EVENTOS_URL");
+
+    if (typeof configurada !== "string" || configurada.trim() === "") {
+        console.warn("motorEventos: url do coletor ausente, evento nao publicado");
+        return null;
+    }
+
+    return configurada.trim();
+}
+
+function textoNaoVazio(valor) {
+    return typeof valor === "string" && valor.trim() !== "" ? valor.trim() : null;
+}
+
+function semIndefinidos(opcoes) {
+    return Object.fromEntries(Object.entries(opcoes ?? {}).filter(([, valor]) => valor !== undefined));
+}
+
+function publicarEvento(produtor, {
+    tipo,
+    autorizacao,
+    idVisitante,
+    payload,
+    url,
+    timeoutMs = TIMEOUT_PADRAO_MS,
+    aoFalhar = (mensagem) => console.error(mensagem),
+} = {}) {
+    try {
+        const destino = urlConfigurada(url);
+        const visitante = textoNaoVazio(idVisitante);
+
+        if (!destino || !tipo || (!autorizacao && !visitante)) {
+            return;
+        }
+
+        const cabecalhos = {
+            "Content-Type": "application/json",
+            [CABECALHO_DO_PRODUTOR]: produtor,
+        };
+        if (autorizacao) {
+            cabecalhos.Authorization = autorizacao;
+        }
+
+        const corpo = {
+            tipo,
+            dt_evento: new Date().toISOString(),
+            payload: payload ?? {},
+        };
+        if (visitante) {
+            corpo.id_visitante = visitante;
+        }
+
+        fetch(destino, {
+            method: "POST",
+            headers: cabecalhos,
+            body: JSON.stringify(corpo),
+            signal: AbortSignal.timeout(timeoutMs),
+        })
+            .then((resposta) => {
+                if (!resposta.ok) {
+                    aoFalhar(`motorEventos: ${tipo} recusado com status ${resposta.status}`);
+                }
+            })
+            .catch((erro) => {
+                aoFalhar(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+            });
+    } catch (erro) {
+        try {
+            aoFalhar(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+        } catch (_erroNoCallback) {
+            /* empty */
+        }
+    }
+}
+
+/**
+ * Tira o token do header Authorization e o visitante do corpo ou do cookie, nessa ordem; nunca lanca.
+ */
+function publicarEventoDaRequisicao(produtor, req, {
+    tipo,
+    payload,
+    cookieVisitante = lerAmbiente("MOTOR_EVENTOS_COOKIE_VISITANTE"),
+    ...resto
+} = {}) {
+    try {
+        const doCorpo = sanitizarId(req?.body?.id_visitante);
+        const doCookie = cookieVisitante ? idDoCookie(req?.headers?.cookie, cookieVisitante) : null;
+
+        publicarEvento(produtor, {
+            tipo,
+            payload,
+            autorizacao: req?.headers?.authorization,
+            idVisitante: doCorpo ?? doCookie,
+            ...resto,
+        });
+    } catch (erro) {
+        console.error(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+    }
+}
+
+/**
+ * Opcoes da inicializacao viram padrao de toda publicacao; o produtor so se define aqui.
+ *
+ * @param {object} [opcoes]
+ * @param {string} [opcoes.produtor] Identificador de quem publica, no formato ^[a-z0-9-]+$. Ausente ou fora do formato vira "desconhecido".
+ * @param {string} [opcoes.url] URL completa do coletor.
+ * @param {string} [opcoes.cookieVisitante] Nome do cookie com o identificador anonimo.
+ * @param {number} [opcoes.timeoutMs] Tempo maximo de cada publicacao.
+ * @param {(mensagem: string) => void} [opcoes.aoFalhar] Recebe a mensagem quando a publicacao nao acontece.
+ */
+function criarMotorEventos({ produtor, url, cookieVisitante, timeoutMs, aoFalhar } = {}) {
+    const identificador = resolverProdutor(produtor);
+    const padroes = semIndefinidos({ url, cookieVisitante, timeoutMs, aoFalhar });
+    const comPadroes = (opcoes) => ({ ...padroes, ...semIndefinidos(opcoes) });
+
+    return {
+        produtor: identificador,
+        publicarEvento: (opcoes) => publicarEvento(identificador, comPadroes(opcoes)),
+        publicarEventoDaRequisicao: (req, opcoes) =>
+            publicarEventoDaRequisicao(identificador, req, comPadroes(opcoes)),
+    };
+}
+
+module.exports = { criarMotorEventos };