@ecdt/server-common 1.6.0 → 1.7.0

package/README.md

@@ -176,14 +176,19 @@ publicarEvento({
 |---|---|---|
 | `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` | `process.env.MOTOR_EVENTOS_URL` | URL completa do coletor; a função não monta caminho nenhum |
 | `timeoutMs` | `2000` | Aborta a requisição |
 | `aoFalhar` | `console.error` | Recebe a mensagem quando a publicação não acontece |
 
-A identidade sai do token, nunca do corpo: o coletor resolve o usuário a partir do `Authorization`
-repassado. Sem `tipo` ou sem `autorizacao` 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 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: forjá-lo
+não atribui nada à conta de ninguém, 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
@@ -191,6 +196,51 @@ consiga dar `await` e acoplar a latência do request ao motor.
 
 ---
 
+### `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.
+
+```js
+const { publicarEventoDaRequisicao } = require('@ecdt/server-common');
+
+publicarEventoDaRequisicao(req, {
+  tipo: 'meu_evento',
+  payload: { campo: 'valor' },
+});
+```
+
+| Opção | Default | Descrição |
+|---|---|---|
+| `tipo`, `payload`, `url`, `timeoutMs`, `aoFalhar` | — | Idênticos ao `publicarEvento` |
+| `cookieVisitante` | `process.env.MOTOR_EVENTOS_COOKIE_VISITANTE` | 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` no servidor, sem dependência de framework.
+
+```js
+const { idDoCookie } = require('@ecdt/server-common');
+
+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`.
+
+---
+
 ## Instalação
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -138,7 +138,8 @@ export declare function renderMetrics(
 
 export interface PublicarEventoOptions {
   tipo: string;
-  autorizacao: string;
+  autorizacao?: string;
+  idVisitante?: string;
   payload?: Record<string, unknown>;
   url?: string;
   timeoutMs?: number;
@@ -146,3 +147,27 @@ export interface PublicarEventoOptions {
 }
 
 export declare function publicarEvento(options?: PublicarEventoOptions): void;
+
+export interface PublicarEventoDaRequisicaoOptions
+  extends Omit<PublicarEventoOptions, 'autorizacao' | 'idVisitante'> {
+  cookieVisitante?: string;
+}
+
+export declare function publicarEventoDaRequisicao(
+  req: unknown,
+  options?: PublicarEventoDaRequisicaoOptions
+): void;
+
+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

@@ -3,7 +3,8 @@ const { devMktTokenSanitaze } = require("./services/tokenService.js");
 const { expressCors } = require("./services/corsService.js");
 const { setupGracefulShutdown } = require("./services/shutdownService.js");
 const { setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics } = require("./services/redMetricsService.js");
-const { publicarEvento } = require("./services/motorEventosService.js");
+const { publicarEvento, publicarEventoDaRequisicao } = require("./services/motorEventosService.js");
+const { lerCookie, idDoCookie, sanitizarId } = require("./services/cookieService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -12,4 +13,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento, publicarEventoDaRequisicao, lerCookie, idDoCookie, sanitizarId }

package/src/services/cookieService.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/services/motorEventosService.js

@@ -1,3 +1,5 @@
+const { idDoCookie, sanitizarId } = require("./cookieService.js");
+
 const TIMEOUT_PADRAO_MS = 2000;
 
 function urlConfigurada(url) {
@@ -11,9 +13,14 @@ function urlConfigurada(url) {
     return configurada.trim();
 }
 
+function textoNaoVazio(valor) {
+    return typeof valor === "string" && valor.trim() !== "" ? valor.trim() : null;
+}
+
 function publicarEvento({
     tipo,
     autorizacao,
+    idVisitante,
     payload,
     url,
     timeoutMs = TIMEOUT_PADRAO_MS,
@@ -21,19 +28,30 @@ function publicarEvento({
 } = {}) {
     try {
         const destino = urlConfigurada(url);
+        const visitante = textoNaoVazio(idVisitante);
 
-        if (!destino || !tipo || !autorizacao) {
+        if (!destino || !tipo || (!autorizacao && !visitante)) {
             return;
         }
 
+        const cabecalhos = { "Content-Type": "application/json" };
+        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: { "Content-Type": "application/json", Authorization: autorizacao },
-            body: JSON.stringify({
-                tipo,
-                dt_evento: new Date().toISOString(),
-                payload: payload ?? {},
-            }),
+            headers: cabecalhos,
+            body: JSON.stringify(corpo),
             signal: AbortSignal.timeout(timeoutMs),
         })
             .then((resposta) => {
@@ -53,4 +71,33 @@ function publicarEvento({
     }
 }
 
-module.exports = { publicarEvento };
+/**
+ * Publica o evento a partir da requisicao que o gerou: tira o token do header
+ * Authorization e o identificador anonimo do corpo ou do cookie, nessa ordem.
+ * Nunca lanca, nem quando `req` nao tem headers nem corpo — o evento e
+ * secundario ao fluxo, e boa parte das chamadas acontece depois de uma escrita
+ * ja efetivada.
+ */
+function publicarEventoDaRequisicao(req, {
+    tipo,
+    payload,
+    cookieVisitante = process.env.MOTOR_EVENTOS_COOKIE_VISITANTE,
+    ...resto
+} = {}) {
+    try {
+        const doCorpo = sanitizarId(req?.body?.id_visitante);
+        const doCookie = cookieVisitante ? idDoCookie(req?.headers?.cookie, cookieVisitante) : null;
+
+        publicarEvento({
+            tipo,
+            payload,
+            autorizacao: req?.headers?.authorization,
+            idVisitante: doCorpo ?? doCookie,
+            ...resto,
+        });
+    } catch (erro) {
+        console.error(`motorEventos: ${tipo} nao publicado (${erro?.message})`);
+    }
+}
+
+module.exports = { publicarEvento, publicarEventoDaRequisicao };

package/test/cookieService.test.js

@@ -0,0 +1,59 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { lerCookie, idDoCookie, sanitizarId } = require('../src/services/cookieService.js');
+
+const comCookie = (nome, valor) => `_ga=GA1.1.9; ${nome}=${encodeURIComponent(valor)}; outro=x`;
+
+describe('sanitizarId', () => {
+    test('devolve null para vazio, espaco em branco ou valor que nao e string', () => {
+        assert.equal(sanitizarId(''), null);
+        assert.equal(sanitizarId('   '), null);
+        assert.equal(sanitizarId(undefined), null);
+        assert.equal(sanitizarId(42), null);
+    });
+
+    test('corta no tamanho maximo', () => {
+        assert.equal(sanitizarId('a'.repeat(300)).length, 100);
+        assert.equal(sanitizarId('a'.repeat(300), 10).length, 10);
+    });
+});
+
+describe('lerCookie', () => {
+    test('acha o cookie no meio do header', () => {
+        assert.equal(lerCookie('a=1; alvo=valor; b=2', 'alvo'), 'valor');
+    });
+
+    test('nao casa com cookie de nome parecido', () => {
+        assert.equal(lerCookie('alvo_antigo=valor', 'alvo'), null);
+    });
+
+    test('devolve null sem header, sem o cookie ou com header que nao e string', () => {
+        assert.equal(lerCookie(undefined, 'alvo'), null);
+        assert.equal(lerCookie('a=1', 'alvo'), null);
+        assert.equal(lerCookie({}, 'alvo'), null);
+        assert.equal(lerCookie('a=1', undefined), null);
+    });
+});
+
+describe('idDoCookie', () => {
+    test('extrai o id quando o cookie guarda JSON', () => {
+        assert.equal(idDoCookie(comCookie('trk', '{"id":"visitante-1"}'), 'trk'), 'visitante-1');
+    });
+
+    test('aceita o cookie como string simples', () => {
+        assert.equal(idDoCookie(comCookie('trk', 'visitante-2'), 'trk'), 'visitante-2');
+    });
+
+    test('devolve null quando o JSON nao tem id', () => {
+        assert.equal(idDoCookie(comCookie('trk', '{"outro":"x"}'), 'trk'), null);
+    });
+
+    test('devolve null quando o cookie nao existe', () => {
+        assert.equal(idDoCookie('a=1', 'trk'), null);
+    });
+
+    test('respeita o maxLen', () => {
+        assert.equal(idDoCookie(comCookie('trk', 'a'.repeat(300)), 'trk', { maxLen: 5 }).length, 5);
+    });
+});

package/test/motorEventosService.test.js

@@ -1,7 +1,10 @@
 const { test, describe, beforeEach, afterEach } = require('node:test');
 const assert = require('node:assert/strict');
 
-const { publicarEvento } = require('../src/services/motorEventosService.js');
+const {
+    publicarEvento,
+    publicarEventoDaRequisicao,
+} = require('../src/services/motorEventosService.js');
 
 const URL = 'http://coletor.interno/eventos';
 
@@ -101,9 +104,10 @@ describe('publicarEvento', () => {
         assert.equal(avisos.length, 2);
     });
 
-    test('nao publica sem tipo ou sem autorizacao', async () => {
+    test('nao publica sem tipo, nem sem identidade nenhuma', async () => {
         publicarEvento({ autorizacao: 'Bearer jwt', url: URL, aoFalhar });
         publicarEvento({ tipo: 'meu_evento', url: URL, aoFalhar });
+        publicarEvento({ tipo: 'meu_evento', url: URL, idVisitante: '   ', aoFalhar });
         await esperarMicrotasks();
 
         assert.equal(chamadas.length, 0);
@@ -111,6 +115,36 @@ describe('publicarEvento', () => {
         assert.deepEqual(avisos, []);
     });
 
+    test('publica so com idVisitante, sem header de autorizacao', async () => {
+        publicarEvento({ tipo: 'meu_evento', idVisitante: 'visitante-1', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 1);
+        assert.equal(chamadas[0].opcoes.headers.Authorization, undefined);
+        assert.equal(JSON.parse(chamadas[0].opcoes.body).id_visitante, 'visitante-1');
+    });
+
+    test('manda os dois quando tem token e visitante', async () => {
+        publicarEvento({
+            tipo: 'meu_evento',
+            autorizacao: 'Bearer jwt',
+            idVisitante: 'visitante-1',
+            url: URL,
+            aoFalhar,
+        });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].opcoes.headers.Authorization, 'Bearer jwt');
+        assert.equal(JSON.parse(chamadas[0].opcoes.body).id_visitante, 'visitante-1');
+    });
+
+    test('omite id_visitante do corpo quando nao ha visitante', async () => {
+        publicarEvento({ tipo: 'meu_evento', autorizacao: 'Bearer jwt', url: URL, aoFalhar });
+        await esperarMicrotasks();
+
+        assert.ok(!('id_visitante' in JSON.parse(chamadas[0].opcoes.body)));
+    });
+
     test('nao quebra quando chamado sem argumento nenhum', () => {
         delete process.env.MOTOR_EVENTOS_URL;
 
@@ -163,3 +197,114 @@ describe('publicarEvento', () => {
         assert.equal(retorno, undefined);
     });
 });
+
+describe('publicarEventoDaRequisicao', () => {
+    let fetchOriginal;
+    let warnOriginal;
+    let errorOriginal;
+    let urlOriginal;
+    let cookieOriginal;
+    let chamadas;
+
+    beforeEach(() => {
+        fetchOriginal = global.fetch;
+        warnOriginal = console.warn;
+        errorOriginal = console.error;
+        urlOriginal = process.env.MOTOR_EVENTOS_URL;
+        cookieOriginal = process.env.MOTOR_EVENTOS_COOKIE_VISITANTE;
+        chamadas = [];
+        console.warn = () => {};
+        console.error = () => {};
+        process.env.MOTOR_EVENTOS_URL = URL;
+        global.fetch = (url, opcoes) => {
+            chamadas.push({ url, opcoes });
+            return Promise.resolve({ ok: true, status: 201 });
+        };
+    });
+
+    afterEach(() => {
+        global.fetch = fetchOriginal;
+        console.warn = warnOriginal;
+        console.error = errorOriginal;
+        for (const [chave, valor] of [
+            ['MOTOR_EVENTOS_URL', urlOriginal],
+            ['MOTOR_EVENTOS_COOKIE_VISITANTE', cookieOriginal],
+        ]) {
+            if (valor === undefined) delete process.env[chave];
+            else process.env[chave] = valor;
+        }
+    });
+
+    const corpoEnviado = () => JSON.parse(chamadas[0].opcoes.body);
+
+    test('tira o token do header da requisicao', async () => {
+        publicarEventoDaRequisicao(
+            { headers: { authorization: 'Bearer jwt' }, body: {} },
+            { tipo: 'meu_evento', payload: { campo: 'valor' } }
+        );
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].opcoes.headers.Authorization, 'Bearer jwt');
+        assert.deepEqual(corpoEnviado().payload, { campo: 'valor' });
+    });
+
+    test('tira o visitante do cookie quando nao ha token', async () => {
+        publicarEventoDaRequisicao(
+            { headers: { cookie: 'trk=%7B%22id%22%3A%22visitante-1%22%7D' }, body: {} },
+            { tipo: 'meu_evento', cookieVisitante: 'trk' }
+        );
+        await esperarMicrotasks();
+
+        assert.equal(corpoEnviado().id_visitante, 'visitante-1');
+        assert.equal(chamadas[0].opcoes.headers.Authorization, undefined);
+    });
+
+    test('o corpo tem precedencia sobre o cookie', async () => {
+        publicarEventoDaRequisicao(
+            {
+                headers: { cookie: 'trk=%7B%22id%22%3A%22do-cookie%22%7D' },
+                body: { id_visitante: 'do-corpo' },
+            },
+            { tipo: 'meu_evento', cookieVisitante: 'trk' }
+        );
+        await esperarMicrotasks();
+
+        assert.equal(corpoEnviado().id_visitante, 'do-corpo');
+    });
+
+    test('cai na MOTOR_EVENTOS_COOKIE_VISITANTE quando o nome nao e passado', async () => {
+        process.env.MOTOR_EVENTOS_COOKIE_VISITANTE = 'trk';
+
+        publicarEventoDaRequisicao(
+            { headers: { cookie: 'trk=visitante-2' }, body: {} },
+            { tipo: 'meu_evento' }
+        );
+        await esperarMicrotasks();
+
+        assert.equal(corpoEnviado().id_visitante, 'visitante-2');
+    });
+
+    test('nao publica quando a requisicao nao traz identidade nenhuma', async () => {
+        delete process.env.MOTOR_EVENTOS_COOKIE_VISITANTE;
+
+        publicarEventoDaRequisicao({ headers: {}, body: {} }, { tipo: 'meu_evento' });
+        await esperarMicrotasks();
+
+        assert.equal(chamadas.length, 0);
+    });
+
+    test('nao quebra com requisicao sem headers, sem corpo, ou sem argumento nenhum', () => {
+        assert.doesNotThrow(() => publicarEventoDaRequisicao({}, { tipo: 'meu_evento' }));
+        assert.doesNotThrow(() => publicarEventoDaRequisicao());
+    });
+
+    test('repassa as demais opcoes para o publicarEvento', async () => {
+        publicarEventoDaRequisicao(
+            { headers: { authorization: 'Bearer jwt' }, body: {} },
+            { tipo: 'meu_evento', url: 'http://outro.interno/eventos' }
+        );
+        await esperarMicrotasks();
+
+        assert.equal(chamadas[0].url, 'http://outro.interno/eventos');
+    });
+});