# @laqus/logsjs

> Essa biblioteca tem o Objetivo de simplificar o processo de "Logs", com LogLevels, Timestamps e Obscurecencia de Atributos, assim alinhados com os Logs do CloudWatch, juntamente com seus respectivos filtros;

Latest version **1.1.0** (published 2026-09-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install @laqus/logsjs
pnpm add @laqus/logsjs
yarn add @laqus/logsjs
bun add @laqus/logsjs
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-09-24 |
| First published | 2023-09-01 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 129.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | luismota, erick.braga, leovolpatto, danilo.rodrigues |

## Links

- npm: https://www.npmjs.com/package/@laqus/logsjs
- npm.io page: https://npm.io/package/@laqus/logsjs

## Dependencies (3)

- [husky](https://npm.io/package/husky.md) ^8.0.3
- [json-stringify-safe](https://npm.io/package/json-stringify-safe.md) ^5.0.1
- [@types/json-stringify-safe](https://npm.io/package/@types/json-stringify-safe.md) ^5.0.3

## Recent versions

- 1.1.0 (latest) — 2026-09-24
- 1.0.17 — 2026-09-22
- 1.0.16 — 2025-12-02
- 1.0.15 — 2025-12-02
- 1.0.14 — 2024-09-25
- 1.0.13 — 2023-12-21
- 1.0.12 — 2023-12-11
- 1.0.10 — 2023-12-08
- 1.0.6 — 2023-12-08
- 1.0.5 — 2023-09-28
- 1.0.4 — 2023-09-25
- 1.0.3 — 2023-09-25
- 1.0.2 — 2023-09-04
- 1.0.1 — 2023-09-01
- 1.0.0 — 2023-09-01

## README

# Laqus.LogsJS

Essa biblioteca tem o Objetivo de simplificar o processo de "Logs", com LogLevels, Timestamps e Obscurecencia de Atributos, assim alinhados com os Logs do CloudWatch, juntamente com seus respectivos filtros;

## Como instalar

```bash
    john@doe:~$ npm install @laqus/logsjs
```

## Variáveis de Ambiente

Para a utilização dessa biblioteca é necessário duas Variáveis de Ambiente

```bash
    LAQUS_APP_NAME = $LAQUS_APP_NAME | None
    LAQUS_LOG_LEVEL = Information | Debug | Warning | Error | Critical
```

- Para da variável `$LAQUS_APP_NAME` caso não seja passado valores para ela, o valor atribuito será `None`.

- A variável `$LAQUS_LOG_LEVEL` aceita o Enum acima, para que a aplicação saiba, qual tipo de LogLevel ela estará mostrando no stdout, caso seja passado um tipo Diferente, não será mostrado nada no stdout;

```javascript
    /* Example */
    require('dotenv/config')

    /* 
        # Example .env
        LAQUS_APP_NAME = Laqus_Emissoes
        LAQUS_LOG_LEVEL = Information
    */

    const { LaqusLogger } = require('@laqus/logsjs');
    const Logger = new LaqusLogger('Application/Test');

    Logger.info({ message: "text test" }); // Will show off
    Logger.warn({ message: "text test" }); // Will NOT show off

    /* OUTPUT
        > node index.js

        {
            "appName": "Laqus_Emissoes",
            "dateTime": "01-09-2023 13:04:42",
            "LogLevel": "Information",
            "text": "text test",
            "category": "Application/Test"
        }
    */
```
## Exemplo de utilização

```javascript
    require('dotenv/config')
    const { LaqusLogger } = require('@laqus/logsjs')
    const logger = new LaqusLogger('Application/Test')

    logger.info({
            message: 'blah blah blah',
            correlationId: '14ee059c-6e06-460f-b29b-c74f14789bbf',
            obscuredFields: null,
            data: {
                app: 'onboarding-api',
                context: 'cadastro',
                error: null,
                props: null,
                sourceClass: 'OnboardingController',
                sourceMethod: 'getAll'
            }
    });

    /* OUTPUT:  
        {
            "dateTime": "01-09-2023 11:28:10",
            "LogLevel": "INFO",
            "text": [
                {
                "teste": {
                    "a": [
                        {
                            "abc": "abc"
                        }
                    ]
                },
                "bool": "******",
                "abc": "abc"
                }
            ]
        }
    */
```

OBS: O atributo `dateTime` está formatado com o formato PT-BR, e com o timezone `America/Recife`.

---

# Audit Logs (NestJS)

Módulo para envio de logs de auditoria para o serviço central `laqus-audit-logs`. Funciona com interceptor do NestJS, capturando request/response automaticamente.

## Como importar

```typescript
    import { AuditLogModule, AuditLog } from '@laqus/logsjs/audit';
```

## Configuração no módulo principal

```typescript
    // app.module.ts
    import { Module } from '@nestjs/common';
    import { APP_INTERCEPTOR } from '@nestjs/core';
    import { AuditLogModule, AuditLogInterceptor } from '@laqus/logsjs/audit';

    @Module({
        imports: [
            AuditLogModule.forRoot({
                sourceMicroservice: 'meu-servico-lindo-maraviloso',
                serviceUrl: 'http://audit-api.laqus.io/api/v1',
                globalMaskedFields: ['password', 'token', 'secret'],
                debug: false
            })
        ],
        providers: [
            {
                provide: APP_INTERCEPTOR,
                useClass: AuditLogInterceptor
            }
        ]
    })
    export class AppModule {}
```

## Configuração com Async (usando ConfigService)

```typescript
    // app.module.ts
    import { Module } from '@nestjs/common';
    import { ConfigModule, ConfigService } from '@nestjs/config';
    import { APP_INTERCEPTOR } from '@nestjs/core';
    import { AuditLogModule, AuditLogInterceptor } from '@laqus/logsjs/audit';

    @Module({
        imports: [
            ConfigModule.forRoot(),
            AuditLogModule.forRootAsync({
                imports: [ConfigModule],
                useFactory: (config: ConfigService) => ({
                    sourceMicroservice: config.get('SERVICE_NAME'),
                    serviceUrl: config.get('AUDIT_SERVICE_URL'),
                    globalMaskedFields: ['password', 'token']
                }),
                inject: [ConfigService]
            })
        ],
        providers: [
            {
                provide: APP_INTERCEPTOR,
                useClass: AuditLogInterceptor
            }
        ]
    })
    export class AppModule {}
```

## Múltiplos interceptors globais

Se a app já usa outro `APP_INTERCEPTOR`, não tem problema. O NestJS aceita múltiplos:

```typescript
    @Module({
        imports: [
            AuditLogModule.forRoot({ ... })
        ],
        providers: [
            {
                provide: APP_INTERCEPTOR,
                useClass: LoggingInterceptor  // interceptor existente
            },
            {
                provide: APP_INTERCEPTOR,
                useClass: AuditLogInterceptor
            }
        ]
    })
    export class AppModule {}
```

## Usando só em controllers específicos

Se não quiser usar global, dá pra aplicar só onde precisar:

```typescript
    import { Controller, UseInterceptors } from '@nestjs/common';
    import { AuditLogInterceptor } from '@laqus/logsjs/audit';

    @Controller('users')
    @UseInterceptors(AuditLogInterceptor)
    export class UsersController { ... }
```

## Usando o decorator @AuditLog

O decorator marca quais endpoints devem gerar audit log. Endpoints sem o decorator não geram log.

```typescript
    // users.controller.ts
    import { Controller, Post, Get, Body, Param } from '@nestjs/common';
    import { AuditLog } from '@laqus/logsjs/audit';

    @Controller('users')
    export class UsersController {

        @Post()
        @AuditLog({
            context: 'UserManagement',
            domain: 'Users',
            action: 'CREATE',
            maskRequestFields: ['password', 'cpf']
        })
        private create(@Body() dto: CreateUserDto): any {
            return this.usersService.create(dto);
        }

        @Get(':id')  // sem @AuditLog = não gera log
        private findOne(@Param('id') id: string): any {
            return this.usersService.findOne(id);
        }
    }
```

## Target Object dinâmico

Para capturar o ID do objeto afetado dinamicamente:

```typescript
    @Delete(':id')
    @AuditLog({
        context: 'Gestao de usuários',
        domain: 'Users',
        action: 'DELETE',
        targetObject: (ctx) => `User:${ctx.params.id}`
    })
    remove(@Param('id') id: string) {
        return this.usersService.remove(id);
    }
```

## Extração de userId e tenantId

Por padrão, o interceptor tenta extrair `userId` e `tenantId` na seguinte ordem:

1. `req.userId` / `req.tenantId` (populado pelo guard)
2. `req.user.id` / `req.user.tenantId` (populado pelo guard)
3. Headers `x-user-id` / `x-tenant-id` (fallback)

Se o guard da app popula o `req.user`, não precisa configurar nada.

Para casos especiais, use extractors customizados:

```typescript
    AuditLogModule.forRoot({
        sourceMicroservice: 'meu-servico-maroto',
        serviceUrl: 'http://audit-api.laqus.io/api/v1',
        userIdExtractor: (req: any) => req.user?.id,
        tenantIdExtractor: (req: any) => req.user?.tenantId
    })
```

## Usando com Mensageria (SQS/RabbitMQ)

Para enviar logs via mensageria (mais performático), passe um adapter:

```typescript
    AuditLogModule.forRoot({
        sourceMicroservice: 'meu-servico',
        serviceUrl: 'http://audit-api.laqus.io/api/v1',
        messagingAdapter: laqusMensageriaAdapterExemplo,  // implementando IAuditLogMessagingAdapter
        exchange: 'platform-audit-logs-ex',
        queue: 'platform-audit-logs'
    })
```

O adapter precisa implementar:

```typescript
    interface IAuditLogMessagingAdapter {
        isReady(): boolean;
        publish(exchange: string, queue: string, message: string): Promise<void>;
    }
```

Se a mensagem for muito grande pro SQS (>200KB), o módulo faz fallback automático pra HTTP.

## Enviando audit logs manualmente

Para logs fora de controllers (jobs, consumers, etc):

```typescript
    import { Injectable } from '@nestjs/common';
    import { AuditLogClientService } from '@laqus/logsjs/audit';

    @Injectable()
    export class UmServicoQueDeveSerAuditavelService {
        constructor(private readonly auditClient: AuditLogClientService) {}

        private async doTheJob() {
            // fazer o que tem que ser feito

            await this.auditClient.log({
                userId: 'uuid-do-usuario',
                tenantId: 'uuid-do-tenant',
                context: 'BackgroundJobs',
                domain: 'Gestao de usuariso',
                action: 'Listar',
                targetObject: 'usurio:123',
                statusCode: 200,
                requestUrl: '/users',
                requestMethod: 'INTERNAL'
            });
        }
    }
```

## Opções do decorator @AuditLog

| Opção | Tipo | Descrição |
|-------|------|-----------|
| `context` | string | Contexto de negócio (ex: 'UserManagement') |
| `domain` | string | Domínio (ex: 'Users', 'Orders') |
| `action` | string | Ação (ex: 'CREATE', 'UPDATE', 'DELETE') |
| `targetObject` | string | function | ID do objeto afetado |
| `maskRequestFields` | string[] | Campos do request body pra mascarar |
| `maskResponseFields` | string[] | Campos do response body pra mascarar |
| `skipRequestBody` | boolean | Não logar request body |
| `skipResponseBody` | boolean | Não logar response body |
| `disabled` | boolean | Desabilita audit log pro endpoint |

## Opções do módulo

| Opção | Tipo | Default | Descrição |
|-------|------|---------|-----------|
| `sourceMicroservice` | string | - | Nome do microsserviço (obrigatório) |
| `serviceUrl` | string | - | URL do serviço de audit (obrigatório) |
| `messagingAdapter` | IAuditLogMessagingAdapter | - | Adapter pra mensageria |
| `exchange` | string | - | Exchange da mensageria |
| `queue` | string | - | Queue da mensageria |
| `globalMaskedFields` | string[] | [] | Campos mascarados em todos os logs |
| `maxResponseBodyBytes` | number | 50KB | Tamanho máximo do response body |
| `httpTimeoutMs` | number | 5000 | Timeout das requests HTTP |
| `debug` | boolean | false | Logs de debug |

---
_Source: https://npm.io/package/@laqus/logsjs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._