@oconde/radar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Conde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,149 @@
+# Protocolo Radar v1
+
+Este documento descreve o envio de eventos ao Radar para quem escreve um SDK em outra linguagem. A fonte da verdade dos tipos é `src/protocol/index.ts`.
+
+## Envio
+
+```
+POST https://radar-ingest.oconde.dev/api/v1/events
+Authorization: Bearer rk_<40 caracteres>
+Content-Type: application/json
+Content-Encoding: gzip            (opcional)
+```
+
+Limites: corpo de até 1 MB depois de descompactado, até 500 eventos por lote.
+
+## Tipos
+
+```ts
+export const PROTOCOL_VERSION = 1;
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export type EventBatch = {
+  v: 1;
+  sdk: { name: string; version: string };
+  environment?: string;
+  release?: string;
+  dropped?: number;
+  events: RadarEvent[];
+};
+
+export type RadarEvent = LogEvent | ErrorEvent;
+
+export type LogEvent = {
+  type: 'log';
+  ts: number;
+  level: LogLevel;
+  message: string;
+  requestId?: string;
+  attrs?: Record<string, unknown>;
+  request?: RequestInfo;
+  user?: UserInfo;
+};
+
+export type ErrorEvent = {
+  type: 'error';
+  ts: number;
+  level: 'error' | 'fatal';
+  handled: boolean;
+  requestId?: string;
+  exception: ExceptionInfo;
+  request?: RequestInfo;
+  user?: UserInfo;
+  runtime?: RuntimeInfo;
+  attrs?: Record<string, unknown>;
+};
+
+export type ExceptionInfo = {
+  type: string;
+  message: string;
+  frames: StackFrame[];
+  cause?: ExceptionInfo;
+};
+
+export type StackFrame = {
+  fn?: string;
+  file: string;
+  line?: number;
+  col?: number;
+  inApp: boolean;
+  context?: { pre: string[]; line: string; post: string[] };
+};
+
+export type RequestInfo = {
+  method: string;
+  url: string;
+  route?: string;
+  params?: Record<string, string>;
+  query?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  body?: unknown;
+  ip?: string;
+  userAgent?: string;
+  status?: number;
+  durationMs?: number;
+};
+
+export type UserInfo = { id?: string; email?: string; name?: string };
+
+export type RuntimeInfo = {
+  name: 'node';
+  version: string;
+  host?: string;
+  pid?: number;
+  memoryMb?: number;
+  uptimeS?: number;
+};
+
+export type IngestResponse = { accepted: number; dropped: number };
+
+export type IngestErrorCode =
+  | 'invalid_key'
+  | 'account_disabled'
+  | 'payload_too_large'
+  | 'invalid_batch'
+  | 'quota_exceeded'
+  | 'rate_limited';
+
+export type IngestError = { error: { code: IngestErrorCode; message: string } };
+```
+
+- `ts` em milissegundos desde a época. Se estiver mais de 24 h longe do relógio do servidor, vale a hora de recebimento.
+- `message` do log é a chave do evento. Convenção: mensagem estável (`webhook.olx.lead`, `http.request`, `api listening`) e o que varia vai em `attrs`. A regra de ausência compara a `message` exata.
+- `dropped` é quantos eventos o SDK descartou desde o último lote aceito (fila cheia); o servidor soma em `usage_daily.dropped` e a tela do projeto mostra.
+
+## Respostas
+
+| Status | Corpo | Quando | O SDK faz |
+|---|---|---|---|
+| 202 | `IngestResponse` | lote aceito, mesmo que parcialmente: eventos inválidos ou de `type` desconhecido entram em `dropped` | segue |
+| 400 | `invalid_batch` | o envelope não é um `EventBatch` (sem `v: 1`, sem `events`) | descarta o lote, avisa uma vez |
+| 401 | `invalid_key` | chave ausente, inexistente ou revogada | pausa os envios por 10 min, descarta a fila, avisa uma vez |
+| 403 | `account_disabled` | conta desativada | igual ao 401 |
+| 413 | `payload_too_large` | acima de 1 MB ou 500 eventos | descarta o lote |
+| 429 | `quota_exceeded` / `rate_limited`, com `Retry-After` em segundos | cota do dia ou excesso de requisições | devolve o lote à fila e espera o `Retry-After` |
+| 5xx / rede | — | servidor fora | devolve o lote à fila e tenta com espera crescente |
+
+## Compatibilidade
+
+O v1 só cresce: campo opcional novo pode; mudar o significado, tornar obrigatório ou remover não pode. O servidor ignora campos desconhecidos. Mudança que quebra vira `/api/v2/events`, com o v1 mantido.
+
+
+## Limites recomendados no SDK
+
+O servidor corta o que passar destes limites; o SDK deve cortar antes de enviar.
+
+| Item | Limite |
+|---|---|
+| `message` | 2000 caracteres |
+| strings em `attrs`, `query`, `body` | 2000 caracteres |
+| `attrs` serializado | 16 KB |
+| `body` serializado | 16 KB |
+| headers | 50 |
+| frames por exceção | 50 |
+| frames com `context` | 10 do próprio app, 5 linhas antes e depois, 300 caracteres por linha |
+| cadeia de `cause` | 5 níveis |
+| profundidade de objetos | 6 |
+| itens por array | 50 |
+| `requestId` | 128 caracteres |

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @oconde/radar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK do [Radar](https://radar.oconde.dev) para Node.js e NestJS: logs, erros com trecho de código e contexto de requisição. Sem dependências em runtime.
+
+## Instalação
+
+```bash
+npm install @oconde/radar
+```
+
+Node 20 ou mais novo. Funciona em ESM e CommonJS, do NestJS 10 em diante.
+
+## NestJS
+
+```ts
+import { Module } from '@nestjs/common';
+import { RadarModule } from '@oconde/radar/nest';
+
+@Module({
+  imports: [RadarModule.forRoot({ key: process.env.RADAR_KEY, release: process.env.GIT_SHA })],
+})
+export class AppModule {}
+```
+
+Com `ConfigService`:
+
+```ts
+RadarModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({ key: config.get('RADAR_KEY') }),
+});
+```
+
+O módulo registra sozinho o contexto por requisição, um log `http.request` por requisição e a captura dos erros 5xx lançados nos handlers. Chame `app.enableShutdownHooks()` para o Radar enviar a fila ao desligar.
+
+Nos services, nada precisa ser injetado:
+
+```ts
+import { radar } from '@oconde/radar';
+
+radar.info('webhook.olx.lead', { leadId });
+```
+
+Quem prefere injeção usa `RadarService`, que tem os mesmos métodos.
+
+Erros lançados em guards e pipes não passam pelo interceptor. Se o app não tem filtro de exceção próprio, registre o do Radar:
+
+```ts
+import { APP_FILTER } from '@nestjs/core';
+import { RadarExceptionFilter } from '@oconde/radar/nest';
+
+providers: [{ provide: APP_FILTER, useClass: RadarExceptionFilter }];
+```
+
+Se já tem, acrescente no `catch` dele: `if (status >= 500) radar.captureError(exception)`. O mesmo erro nunca é enviado duas vezes.
+
+## Express
+
+```ts
+import { radar } from '@oconde/radar';
+
+radar.init({ key: process.env.RADAR_KEY });
+app.use(radar.middleware());
+```
+
+## API
+
+| Função | O que faz |
+|---|---|
+| `radar.init(options)` | configura uma vez; chamadas seguintes são ignoradas |
+| `radar.debug/info/warn/error(message, data?)` | log com `data` como atributos; dentro de uma requisição sai com o `requestId` e o usuário |
+| `radar.logRequest(title, data?, { level?, redact? }?)` | log com a requisição atual inteira: método, URL, rota, params, query, headers, body, IP |
+| `radar.captureError(error, data?)` | erro com stack, trecho de código, requisição, usuário e runtime |
+| `radar.setUser({ id, email, name })` | usuário da requisição atual |
+| `radar.track(name, fn, data?)` | mede `fn`, registra sucesso ou falha com `durationMs`, captura e relança o erro |
+| `radar.middleware()` | middleware Express de contexto (`x-request-id`) |
+| `radar.flush(timeoutMs?)` / `radar.close(timeoutMs?)` | envia a fila; `close` também desliga |
+| `radar.settings` | opções em uso (só leitura); `radar.settings.console` diz se o Radar já imprime no stdout, útil para um logger próprio não duplicar linhas |
+
+Mensagens de log são chaves estáveis (`webhook.olx.lead`); o que varia vai em `data`.
+
+## Opções
+
+| Opção | Padrão | |
+|---|---|---|
+| `key` | — | sem chave nada é enviado |
+| `endpoint` | `https://radar-ingest.oconde.dev` | |
+| `environment` | `NODE_ENV` ou `production` | |
+| `release` | — | ex.: o SHA do commit |
+| `console` | `false` | imprime cada log como JSON no stdout, mesmo sem chave |
+| `minLevel` | `info` | |
+| `redact` | `mask` | `none` guarda tokens e senhas inteiros |
+| `requestDetail` | `full` | `route` manda da requisição só o método e a rota (`/students/:studentId`), com status e duração: sem URL concreta, query, params, headers, corpo, IP nem user agent. Para apps com dado sensível (saúde, LGPD) |
+| `logRequests` | `true` | log `http.request` automático |
+| `ignorePaths` | `['/healthz', '/health']` | |
+| `captureUnhandled` | `true` | `uncaughtException` e `unhandledRejection`; o processo cai como cairia sem o Radar |
+| `debug` | `false` | mostra problemas internos do SDK |
+
+## Dados sensíveis
+
+Com `redact: 'mask'` (padrão), o SDK mascara antes de enviar:
+
+- headers e chaves (no corpo, na query, nos parâmetros da rota, no caminho da URL e nos atributos) cujo nome tenha uma destas palavras: `password`, `senha`, `secret`, `token`, `auth`, `authorization`, `cookie`, `apikey`, `api key`, `private key`, `access key`, `signature`, `jwt`, `session`, `credential`, `cpf`, `card`, `cvv`, `cvc`, `pin`, `otp`, além da chave `key` sozinha e dos headers `x-…-key`, `x-…-secret` e `x-…-token`. A comparação é por palavra: `cardio` e `passos` não são mascarados;
+- qualquer valor com cara de credencial (`Bearer …`, `Basic …`, JWT), seja qual for a chave.
+
+Tokens e chaves saem como `Bearer eyJh…5x9Q #a1b2c3d4`: dá para ver se veio, qual era e se dois valores são iguais. Senhas, CPF, cartão, CVV, PIN e OTP saem só como `••• #a1b2c3d4`, sem nenhum pedaço do valor. A impressão digital é um HMAC com chave derivada da chave do projeto, então não dá para descobrir o valor por força bruta sem ela.
+
+`redact: 'none'` (no `init` ou por chamada de `logRequest`) guarda os valores inteiros.
+
+## Trecho de código nos erros
+
+O SDK lê os source maps sozinho. Em projetos TypeScript, ligue no `tsconfig`:
+
+```json
+{ "compilerOptions": { "sourceMap": true, "inlineSources": true } }
+```
+
+Com `inlineSources`, o código vai dentro do `.map` e a imagem de produção não precisa conter `src/`.
+
+## Garantias
+
+Nenhuma função lança erro para o app (exceto `track`, que relança o erro de `fn`). A fila fica em memória (até 1000 eventos), é enviada a cada 2 s ou 100 eventos e tenta de novo com espera crescente se o Radar estiver fora. O SDK não registra `SIGTERM`.
+
+Formato dos dados enviados: [PROTOCOL.md](PROTOCOL.md).

package/dist/client-DbNex6tj.d.cts

@@ -0,0 +1,104 @@
+import { UserInfo, LogLevel } from './protocol/index.cjs';
+
+type HeaderValue = string | string[] | number | undefined;
+type RequestLike = {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    route?: {
+        path?: unknown;
+    };
+    params?: Record<string, unknown>;
+    query?: unknown;
+    headers: Record<string, HeaderValue>;
+    body?: unknown;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+};
+type ResponseLike = {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    once(event: 'finish', listener: () => void): unknown;
+};
+type RadarContext = {
+    requestId: string;
+    startedAt: number;
+    req?: RequestLike;
+    route?: string;
+    user?: UserInfo;
+};
+
+type RadarMiddleware = (req: RequestLike, res: ResponseLike, next: (error?: unknown) => void) => void;
+
+type RedactMode = 'mask' | 'none';
+type RequestDetail = 'full' | 'route';
+type RadarOptions = {
+    key?: string;
+    endpoint?: string;
+    environment?: string;
+    release?: string;
+    enabled?: boolean;
+    console?: boolean;
+    minLevel?: LogLevel;
+    redact?: RedactMode;
+    requestDetail?: RequestDetail;
+    logRequests?: boolean;
+    ignorePaths?: string[];
+    captureUnhandled?: boolean;
+    debug?: boolean;
+};
+type ResolvedOptions = {
+    key: string | undefined;
+    endpoint: string;
+    environment: string;
+    release: string | undefined;
+    enabled: boolean;
+    console: boolean;
+    minLevel: LogLevel;
+    redact: RedactMode;
+    requestDetail: RequestDetail;
+    logRequests: boolean;
+    ignorePaths: string[];
+    captureUnhandled: boolean;
+    debug: boolean;
+};
+
+type Attributes = Record<string, unknown>;
+type LogRequestOptions = {
+    level?: LogLevel;
+    redact?: RedactMode;
+};
+declare class RadarClient {
+    private options;
+    private transport;
+    private initialized;
+    private closed;
+    private readonly captured;
+    get isEnabled(): boolean;
+    get settings(): Readonly<ResolvedOptions>;
+    init(options?: RadarOptions): void;
+    debug(message: string, data?: Attributes): void;
+    info(message: string, data?: Attributes): void;
+    warn(message: string, data?: Attributes): void;
+    error(message: string, data?: Attributes): void;
+    logRequest(title: string, data?: Attributes, options?: LogRequestOptions): void;
+    captureError(error: unknown, data?: Attributes): void;
+    captureUnhandled(error: unknown, level: 'error' | 'fatal'): void;
+    setUser(user: UserInfo): void;
+    track<T>(name: string, fn: () => T | Promise<T>, data?: Attributes): Promise<T>;
+    middleware(): RadarMiddleware;
+    shouldLogRequest(req: RequestLike): boolean;
+    logHttpRequest(context: RadarContext, status: number): void;
+    flush(timeoutMs?: number): Promise<void>;
+    close(timeoutMs?: number): Promise<void>;
+    private emitLog;
+    private emitError;
+    private print;
+    private safely;
+    private debugWarn;
+    private writeWarning;
+}
+
+export { type Attributes as A, type LogRequestOptions as L, RadarClient as R, type RadarMiddleware as a, type RadarOptions as b, type RedactMode as c, type RequestLike as d, type ResponseLike as e };

package/dist/client-ZpQHpeAu.d.ts

@@ -0,0 +1,104 @@
+import { UserInfo, LogLevel } from './protocol/index.js';
+
+type HeaderValue = string | string[] | number | undefined;
+type RequestLike = {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    route?: {
+        path?: unknown;
+    };
+    params?: Record<string, unknown>;
+    query?: unknown;
+    headers: Record<string, HeaderValue>;
+    body?: unknown;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+};
+type ResponseLike = {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    once(event: 'finish', listener: () => void): unknown;
+};
+type RadarContext = {
+    requestId: string;
+    startedAt: number;
+    req?: RequestLike;
+    route?: string;
+    user?: UserInfo;
+};
+
+type RadarMiddleware = (req: RequestLike, res: ResponseLike, next: (error?: unknown) => void) => void;
+
+type RedactMode = 'mask' | 'none';
+type RequestDetail = 'full' | 'route';
+type RadarOptions = {
+    key?: string;
+    endpoint?: string;
+    environment?: string;
+    release?: string;
+    enabled?: boolean;
+    console?: boolean;
+    minLevel?: LogLevel;
+    redact?: RedactMode;
+    requestDetail?: RequestDetail;
+    logRequests?: boolean;
+    ignorePaths?: string[];
+    captureUnhandled?: boolean;
+    debug?: boolean;
+};
+type ResolvedOptions = {
+    key: string | undefined;
+    endpoint: string;
+    environment: string;
+    release: string | undefined;
+    enabled: boolean;
+    console: boolean;
+    minLevel: LogLevel;
+    redact: RedactMode;
+    requestDetail: RequestDetail;
+    logRequests: boolean;
+    ignorePaths: string[];
+    captureUnhandled: boolean;
+    debug: boolean;
+};
+
+type Attributes = Record<string, unknown>;
+type LogRequestOptions = {
+    level?: LogLevel;
+    redact?: RedactMode;
+};
+declare class RadarClient {
+    private options;
+    private transport;
+    private initialized;
+    private closed;
+    private readonly captured;
+    get isEnabled(): boolean;
+    get settings(): Readonly<ResolvedOptions>;
+    init(options?: RadarOptions): void;
+    debug(message: string, data?: Attributes): void;
+    info(message: string, data?: Attributes): void;
+    warn(message: string, data?: Attributes): void;
+    error(message: string, data?: Attributes): void;
+    logRequest(title: string, data?: Attributes, options?: LogRequestOptions): void;
+    captureError(error: unknown, data?: Attributes): void;
+    captureUnhandled(error: unknown, level: 'error' | 'fatal'): void;
+    setUser(user: UserInfo): void;
+    track<T>(name: string, fn: () => T | Promise<T>, data?: Attributes): Promise<T>;
+    middleware(): RadarMiddleware;
+    shouldLogRequest(req: RequestLike): boolean;
+    logHttpRequest(context: RadarContext, status: number): void;
+    flush(timeoutMs?: number): Promise<void>;
+    close(timeoutMs?: number): Promise<void>;
+    private emitLog;
+    private emitError;
+    private print;
+    private safely;
+    private debugWarn;
+    private writeWarning;
+}
+
+export { type Attributes as A, type LogRequestOptions as L, RadarClient as R, type RadarMiddleware as a, type RadarOptions as b, type RedactMode as c, type RequestLike as d, type ResponseLike as e };