@cargolift-cdi/lib-common

Biblioteca de utilitários comuns para serviços NestJS do ecossistema Middleware Cargolift, com foco em logs estruturados, autenticação/autorização e padronização de erros.

📌 Objetivo

Este repositório centraliza componentes reutilizáveis usados pelos serviços do middleware para reduzir duplicidade e garantir padrões técnicos consistentes entre APIs e workers.

No contexto do monorepo middleware, a lib-common entrega uma base para:

• Observabilidade e rastreabilidade ponta a ponta (correlation id, trace, warns).
• Tratamento uniforme de exceções HTTP e erros de domínio.
• Autenticação JWT e autorização por role/cliente para endpoints NestJS.
• Utilitários de payload com sanitização de dados sensíveis.

✨ Funcionalidades

• Logger contextual com AsyncLocalStorage: contexto isolado por requisição/mensagem com API simples para enriquecer logs.
• Middleware HTTP de logging: captura request/response com duração, origem e payload sanitizado.
• Filtro global de exceções (HTTPExceptionsFilter): resposta padronizada e log estruturado para erros 4xx/5xx.
• Módulo de autenticação (AuthModule): verificação JWT RS256 via OpenID/JWKS + AuthGuard com validação de roles.
• Pacote de erros de domínio/aplicação: classes de erro tipadas com metadados (code, source, retryable, cause, data).
• Utilitário de payload (PayloadUtil): normalização, extração de envelope/payload e mascaramento de campos sensíveis.

Diferenciais técnicos:

• Compatível com arquitetura orientada a eventos e serviços HTTP.
• Uso de padrões consistentes para source, trace e classificação de erro.
• Pronto para integração com stack de observabilidade do middleware.

🔍 Detalhamento

Logging e contexto

O LoggerContextService implementa o LoggerService do NestJS usando pino e mantém o contexto por fluxo assíncrono com AsyncLocalStorage.

Principais recursos:

• Métodos: log, info, debug, warn, error, clientError, businessError, businessWarn.
• Contexto: setContextRequest, setContextRabbitMQ, setExternalReference, setBusinessKey, setLogContext, updateSource.
• Helpers exportados: runWithLoggerContext, getLoggerContext, updateLoggerContext, clearLoggerContext.

Exemplo de uso (App Logger global)

import { Inject, Injectable, Module } from '@nestjs/common';
import { AppLoggerModule, APP_LOGGER, LoggerContextService } from '@cargolift-cdi/lib-common';

@Module({
  imports: [
    AppLoggerModule.forRoot({
      application: { name: 'middleware-api', function: 'service' },
    }),
  ],
})
export class AppModule {}

@Injectable()
export class ExampleService {
  constructor(@Inject(APP_LOGGER) private readonly logger: LoggerContextService) {}

  execute() {
    this.logger.log('Serviço executado');
  }
}

Autenticação e autorização

AuthModule exporta JwtVerifierService e AuthGuard.

O AuthGuard:

• valida token Bearer RS256,
• popula request.user,
• resolve client id via @ApiClient() ou claims,
• valida roles via @RequireRoles().

Exemplo de uso

import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthGuard, RequireRoles, ApiClient, TokenJWT } from '@cargolift-cdi/lib-common';

@Controller('orders')
@UseGuards(AuthGuard)
export class OrdersController {
  @Get(':entity')
  @ApiClient('api.middleware')
  @RequireRoles(':entity')
  list(@TokenJWT() jwt: any) {
    return { subject: jwt?.sub };
  }
}

Erros e exceções HTTP

BaseError e suas especializações (BusinessError, ApplicationError, MiddlewareError, ClientError e versões transitórias) padronizam semântica de erro no domínio.

Para APIs HTTP, use HTTPExceptionsFilter como filtro global para resposta uniforme e logs consistentes.

Exemplo de uso

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { HTTPExceptionsFilter, LoggerModule } from '@cargolift-cdi/lib-common';

@Module({
  imports: [LoggerModule],
  providers: [{ provide: APP_FILTER, useClass: HTTPExceptionsFilter }],
})
export class AppModule {}

Utilitário de payload

PayloadUtil oferece:

• normalize(payload): converte string JSON/objeto para estrutura utilizável.
• sanitize(payload): mascara campos sensíveis.
• extract(rawPayload): separa envelope e payload quando houver wrapper.

🛠 Tecnologias e Dependências

Dependência interna:

• @cargolift-cdi/types (workspace:*)

🚀 Instalação

Pré-requisitos

• Node.js: 18+
• pnpm: recomendado no monorepo
• NestJS: peer dependency @nestjs/common@^11.1.6

Instalar no monorepo (workspace)

pnpm --filter @cargolift-cdi/lib-common install

Consumir em outro pacote do monorepo

pnpm add @cargolift-cdi/lib-common

Variáveis de ambiente

💡 Como Usar

Quickstart

import {
  LoggerModule,
  HTTPLoggerMiddleware,
  HTTPExceptionsFilter,
  AuthModule,
  PayloadUtil,
} from '@cargolift-cdi/lib-common';

// Importe LoggerModule/AuthModule no seu AppModule.
// Registre HTTPLoggerMiddleware no consumer de middlewares.
// Registre HTTPExceptionsFilter como APP_FILTER.

const sanitized = PayloadUtil.sanitize({ authorization: 'Bearer abc', value: 1 });
// => { authorization: '[REDACTED]', value: 1 }

📁 Estrutura do Projeto

src/
├── auth/                 # AuthModule, guard, decorators e verificação JWT
├── errors/               # BaseError, erros tipados e utilitários de classificação
├── logger/               # LoggerContextService, módulos de logger e AsyncLocalStorage
├── nestjs/
│   ├── filters/          # HTTPExceptionsFilter
│   └── middleware/       # HTTPLoggerMiddleware
├── util/                 # PayloadUtil
├── __tests__/            # Testes unitários
└── index.ts              # Export público da biblioteca

🧪 Testes

pnpm --filter @cargolift-cdi/lib-common test

Build local:

pnpm --filter @cargolift-cdi/lib-common build

🤝 Contribuindo

• Siga os padrões do monorepo middleware.
• Priorize mudanças pequenas e focadas.
• Inclua/atualize testes quando alterar comportamento.

📄 Licença

MIT © Cargolift CDI