@adatechnology/logger 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @adatechnology/logger
+
+## 0.0.2
+
+### Patch Changes
+
+- fix to use packages logger and use

package/README.md

@@ -0,0 +1,151 @@
+# Logger provider
+
+Pacote que expõe um provider de logs seguindo o padrão das outras libs do monorepo.
+
+Exporta `LoggerModule` e o token `LOGGER_PROVIDER`.
+
+## Exemplos de uso
+
+1. Uso padrão (Winston como implementação padrão):
+
+```ts
+import { Module } from "@nestjs/common";
+import { LoggerModule } from "@adatechnology/logger";
+
+@Module({
+  imports: [
+    // Opção 1: Configuração estática (forRoot)
+    LoggerModule.forRoot({
+      level: 'debug',
+      context: 'MyService',
+      isProduction: process.env.NODE_ENV === 'production',
+      colorize: true,
+    }),
+
+    // Opção 2: Configuração dinâmica (forRootAsync)
+    LoggerModule.forRootAsync({
+      useFactory: (configService: ConfigService) => ({
+        level: configService.get('LOG_LEVEL'),
+        isProduction: configService.get('NODE_ENV') === 'production',
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+2. Customizando o Winston e adicionando chaves sensíveis para ofuscar:
+
+```ts
+import { Module } from "@nestjs/common";
+import { LoggerModule } from "@adatechnology/logger";
+import { transports } from "winston";
+
+const loggerOptions = {
+  level: "debug",
+  transports: [new transports.Console()],
+};
+
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      loggerOptions,
+      // obfuscatorKeys aceita strings ou objetos { key, obfuscator }
+      obfuscatorKeys: [
+        "password",
+        {
+          key: "creditCard",
+          obfuscator: (v: any) =>
+            typeof v === "string" ? v.replace(/\d(?=\d{4})/g, "*") : "****",
+        },
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+3. Injetando o provider e usando nos serviços:
+
+```ts
+import { Inject, Injectable } from "@nestjs/common";
+import { LOGGER_PROVIDER } from "@adatechnology/logger";
+import type { LoggerProviderInterface } from "@adatechnology/logger";
+
+@Injectable()
+export class FooService {
+  constructor(
+    @Inject(LOGGER_PROVIDER) private readonly logger: LoggerProviderInterface,
+  ) {
+    this.logger.info({ message: "iniciando FooService" });
+  }
+}
+```
+
+Observação: o obfuscator padrão é aplicado recursivamente em objetos e aceita entradas do tipo string (nome do campo) ou objetos `{ key, obfuscator }` para permitir funções customizadas do usuário.
+
+Se quiser, eu adiciono um exemplo de teste unitário para validar o comportamento do obfuscator.
+
+## Padrão de Logging (Desenvolvimento)
+
+Este pacote implementa um formato de log padronizado para todo o monorepo, facilitando o rastreamento de chamadas entre múltiplas bibliotecas e serviços.
+
+### Formato Final
+`[App-name@version][lib-name:version][requestId][timestamp][source][libMethod][LEVEL] - message - {payload}`
+
+### Propriedades do Payload
+Ao realizar um log, você pode passar as seguintes propriedades para enriquecer o contexto:
+
+- `message`: A mensagem principal do log.
+- `context`: O contexto geral (ex: nome da classe da biblioteca).
+- `source`: O chamador original (breadcrumb). Ex: `HttpClientController.listPokemon`.
+- `lib`: Nome da biblioteca que está gerando o log. Ex: `@adatechnology/http-client`.
+- `libVersion`: Versão da biblioteca.
+- `libMethod`: O método interno da biblioteca sendo executado. Ex: `get`.
+- `meta`: Objeto com metadados adicionais (será exibido em uma única linha compacta).
+
+### Exemplo de Log de Biblioteca
+Para uma biblioteca que segue o padrão:
+
+```ts
+this.logger.info({
+  message: 'HTTP Request GET https://pokeapi.co/api/v2/pokemon',
+  context: 'HttpRedisClient',
+  lib: '@adatechnology/http-client',
+  libVersion: '0.0.2',
+  libMethod: 'get',
+  source: 'HttpClientController.listPokemon', // vindo do logContext da chamada
+  meta: { ... }
+});
+```
+
+Resultado visual:
+`[App-example@0.0.3][@adatechnology/http-client:0.0.2][req-id][2026-03-29...][HttpClientController.listPokemon][HttpRedisClient.get][INFO] - HTTP Request... - { headers: ... }`
+
+## Middleware e contexto automático
+
+O pacote oferece um middleware `RequestContextMiddleware` que injeta um `requestId` (a partir do header `x-request-id` ou gerando um UUID) e executa a request dentro de um contexto assíncrono (AsyncLocalStorage). Para usá-lo no NestJS:
+
+```ts
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { RequestContextMiddleware, LoggerModule } from '@adatechnology/logger';
+
+@Module({ imports: [LoggerModule.forRoot()] })
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RequestContextMiddleware).forRoutes('*');
+  }
+}
+```
+
+Com o middleware ativo, o logger automaticamente incluirá `requestId` nos metadados quando não for passado explicitamente.
+
+## Request-scoped provider
+
+Se desejar um provider por request (cada request recebe uma instância com `setContext` isolado), passe `requestScoped: true` ao `forRoot`:
+
+```ts
+LoggerModule.forRoot({ requestScoped: true })
+```
+

package/agents/skills/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: logger
+description: Patterns for @adatechnology/logger. Use when configuring Winston logging, managing Request-ID context (AsyncLocalStorage), or obfuscating sensitive data.
+---
+
+# 📝 Logger Standards
+
+## 🚀 Setup Example
+```typescript
+@Module({
+  imports: [
+    LoggerModule.forRoot({
+      level: 'info',
+      sensitiveKeys: ['password', 'token', 'clientSecret'],
+    }),
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Required to enable Request-ID tracking across async calls
+    consumer.apply(RequestContextMiddleware).forRoutes('*');
+  }
+}
+```
+
+## 🏗️ Usage Pattern
+```typescript
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(LOGGER_PROVIDER) private readonly logger: LoggerProviderInterface
+  ) {}
+
+  doWork() {
+    this.logger.info('Action performed', { userId: '123' });
+  }
+}
+```
+
+## 🔐 Obfuscation
+The logger automatically hides values for keys defined in `sensitiveKeys`.
+- **Default Keys**: `password`, `token`, `authorization`, `cookie`, `secret`.
+- **Custom Keys**: Add via `LoggerModule.forRoot()`.
+
+## 🛠️ Internal Mechanics
+- **Async Context**: Uses `AsyncLocalStorage` to store the Request-ID.
+- **Context Access**: Use `getContext()` to retrieve the current request state anywhere in the call stack.

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { DynamicModule, NestMiddleware } from '@nestjs/common';
+import { LoggerOptions } from 'winston';
+
+interface ObfuscatorKey {
+    key: string;
+    obfuscator: Obfuscator;
+}
+interface WinstonModuleConfig {
+    loggerOptions?: LoggerOptions;
+    obfuscator?: Obfuscator;
+    obfuscatorKeys?: Array<string | ObfuscatorKey>;
+}
+type Obfuscator = (value: unknown) => unknown;
+
+declare enum LoggerLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}
+interface LogPayload {
+    message: string;
+    context?: string;
+    meta?: Record<string, unknown>;
+}
+interface LoggerProviderInterface {
+    debug(payload: LogPayload): void;
+    info(payload: LogPayload): void;
+    warn(payload: LogPayload): void;
+    error(payload: LogPayload): void;
+    setContext?(context: string): void;
+}
+
+interface LoggerConfig extends WinstonModuleConfig {
+    /**
+     * Define se o provider do logger deve ser request-scoped
+     */
+    requestScoped?: boolean;
+    /**
+     * Nível de log padrão (string compatível com winston)
+     */
+    level?: LoggerLevel | string;
+    /**
+     * Contexto padrão para os logs
+     */
+    context?: string;
+    /**
+     * Define se o log deve ser formatado para produção (ex.: JSON)
+     */
+    isProduction?: boolean;
+    /**
+     * Define se deve colorir a saída (útil para desenvolvimento local)
+     */
+    colorize?: boolean;
+    /**
+     * Nome da aplicação para exibição nos logs
+     */
+    appName?: string;
+    /**
+     * Versão da aplicação para exibição nos logs
+     */
+    appVersion?: string;
+    /**
+     * Identificação da biblioteca/módulo que está gerando o log
+     */
+    lib?: string;
+    /**
+     * Versão da biblioteca/módulo que está gerando o log
+     */
+    libVersion?: string;
+}
+declare const DEFAULT_LOGGER_CONFIG: LoggerConfig;
+
+declare const LOGGER_PROVIDER = "LOGGER_PROVIDER";
+
+declare class LoggerModule {
+    static forRoot(config?: LoggerConfig): DynamicModule;
+    static forRootAsync(options: {
+        imports?: any[];
+        useFactory: (...args: any[]) => Promise<LoggerConfig> | LoggerConfig;
+        inject?: any[];
+    }): DynamicModule;
+}
+
+type RequestLike = {
+    headers?: Record<string, unknown> | undefined;
+    [key: string]: unknown;
+};
+type ResponseLike = {
+    [key: string]: unknown;
+};
+type NextFunctionLike = (err?: unknown) => void;
+
+declare class RequestContextMiddleware implements NestMiddleware {
+    use(req: RequestLike, _res: ResponseLike, next: NextFunctionLike): void;
+}
+
+type RequestContext = Record<string, unknown> | undefined;
+
+declare function getContext(): RequestContext;
+declare function runWithContext<T>(ctx: Record<string, unknown>, fn: () => T): T;
+
+export { DEFAULT_LOGGER_CONFIG, LOGGER_PROVIDER, type LogPayload, type LoggerConfig, LoggerLevel, LoggerModule, type LoggerProviderInterface, RequestContextMiddleware, getContext, runWithContext };