@seidor-cloud-produtos/orbit-backend-lib 2.0.138 → 2.1.0

package/dist/clean-arch/application/logger/index.js

@@ -2,44 +2,82 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CategoryEnum = exports.ActorEnum = void 0;
 const types_1 = require("../../infra/environment/types");
+/**
+ * Identifica o tipo de ator que originou o log.
+ */
 var ActorEnum;
 (function (ActorEnum) {
     ActorEnum["SYSTEM"] = "system";
     ActorEnum["USER"] = "user";
 })(ActorEnum || (exports.ActorEnum = ActorEnum = {}));
+/**
+ * Categoriza o log em negócio ou técnico.
+ */
 var CategoryEnum;
 (function (CategoryEnum) {
     CategoryEnum["BUSINESS"] = "business";
     CategoryEnum["TECHNICAL"] = "technical";
 })(CategoryEnum || (exports.CategoryEnum = CategoryEnum = {}));
+/**
+ * Classe base para loggers.
+ *
+ * Responsável por:
+ * - Montar propriedades padrão (`actor`, `type`, `level`, `dateTime`).
+ * - Aplicar filtros por nível com apoio opcional de cache.
+ * - Delegar o envio para a implementação concreta (`register`).
+ */
 class LoggerGateway {
     cache;
     options;
     params;
-    constructor(cache, options, params) {
-        this.cache = cache;
-        this.options = options;
-        this.params = params;
+    constructor(props) {
+        this.cache = props?.cache;
+        this.options = props?.options;
+        this.params = props?.params;
     }
     static cacheKey = 'LOG_LEVEL';
+    /**
+     * Loga com nível `info`.
+     */
     async info(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.info }, input);
     }
+    /**
+     * Loga com nível `warn`.
+     */
     async warn(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.warn }, input);
     }
+    /**
+     * Loga com nível `error`.
+     */
     async error(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.error }, input);
     }
+    /**
+     * Loga com nível `debug`.
+     */
     async debug(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.debug }, input);
     }
+    /**
+     * Fluxo principal de logging.
+     *
+     * - Extrai params extras quando `lastArgIsParams` estiver habilitado.
+     * - Monta propriedades finais.
+     * - Checa se deve logar (nível/cache).
+     * - Delegada envio para `register`.
+     */
     async log(props, dataToLog) {
         try {
             let params = this.params;
             if (this.options?.lastArgIsParams && dataToLog instanceof Array) {
-                params = dataToLog[dataToLog.length - 1];
+                params = {
+                    ...(params || {}),
+                    ...dataToLog[dataToLog.length - 1],
+                };
                 dataToLog = dataToLog.slice(0, dataToLog.length - 1);
+                dataToLog = dataToLog.length === 1 ? dataToLog[0] : dataToLog;
             }
             const buildedProperties = this.buildProps(props, params);
             const isToLog = await this.isToLog(buildedProperties, dataToLog);
@@ -53,6 +91,9 @@ class LoggerGateway {
             console.log('Input', props, dataToLog);
         }
     }
+    /**
+     * Constrói a lista de níveis aceitos com base no nível configurado.
+     */
     static buildAcceptLogLevelValues(level) {
         const acceptValues = [types_1.LOG_LEVEL.error];
         if (level === types_1.LOG_LEVEL.warn) {
@@ -66,6 +107,13 @@ class LoggerGateway {
         }
         return acceptValues;
     }
+    /**
+     * Decide se o log deve ser emitido.
+     *
+     * - `error` sempre é emitido.
+     * - Sem cache, sempre emite.
+     * - Com cache, consulta o nível permitido por tipo/actor.
+     */
     async isToLog(props, dataToLog) {
         if (props.level === types_1.LOG_LEVEL.error || !this.cache) {
             return true;
@@ -94,6 +142,9 @@ class LoggerGateway {
         const acceptValues = LoggerGateway.buildAcceptLogLevelValues(cachedValue);
         return acceptValues.includes(props.level);
     }
+    /**
+     * Monta as propriedades finais do log.
+     */
     buildProps(props, params) {
         const defaultProps = this.buildDefaultProps(params);
         if (props) {
@@ -104,14 +155,25 @@ class LoggerGateway {
         }
         return defaultProps;
     }
+    /**
+     * Monta propriedades padrão.
+     */
     buildDefaultProps(params) {
         return {
             level: types_1.LOG_LEVEL.info,
             dateTime: new Date(),
-            actor: params?.actor || 'default',
-            type: params?.type || 'default',
+            actor: 'default',
+            type: 'default',
+            ...(params || {}),
         };
     }
+    /**
+     * Define o nível de log no cache para um filtro (type/actor).
+     *
+     * @param level Nível mínimo a ser aceito.
+     * @param filter Filtro de log por tipo e ator.
+     * @param ttl Tempo em segundos (default 4 dias).
+     */
     async setLevel(level, filter, ttl) {
         if (!this.cache) {
             return;

package/dist/clean-arch/application/logger/logger.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clean-arch/application/logger/logger.spec.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const types_1 = require("../../infra/environment/types");
+const logger_in_memory_1 = require("../../infra/logger/logger-in-memory");
+const base_audit_logger_1 = require("./base-audit-logger");
+const index_1 = tslib_1.__importStar(require("./index"));
+class TestLogger extends index_1.default {
+    registerMock = vi.fn().mockResolvedValue(undefined);
+    register(props, dataToLog) {
+        return this.registerMock(props, dataToLog);
+    }
+    async exposeIsToLog(props, dataToLog) {
+        return await this.isToLog(props, dataToLog);
+    }
+    exposeBuildProps(props, params) {
+        return this.buildProps(props, params);
+    }
+}
+class TestAuditLogger extends base_audit_logger_1.BaseAuditLogger {
+    exposeBuildParams(type, authorizerHeaders, trace) {
+        return this.buildParams(type, authorizerHeaders, trace);
+    }
+    async exposeInfo(payload, params) {
+        await this.info(payload, params);
+    }
+}
+describe('Logger base', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should build props and split params from the last argument', async () => {
+        const logger = new TestLogger({
+            options: {
+                lastArgIsParams: true,
+            },
+            params: {
+                actor: 'default-actor',
+                type: 'default-type',
+            },
+        });
+        await logger.log({ level: types_1.LOG_LEVEL.warn }, [
+            'payload',
+            { actor: 'custom-actor', type: 'custom-type' },
+        ]);
+        expect(logger.registerMock).toHaveBeenCalledWith(expect.objectContaining({
+            level: types_1.LOG_LEVEL.warn,
+            actor: 'custom-actor',
+            type: 'custom-type',
+            dateTime: expect.any(Date),
+        }), 'payload');
+    });
+    it('should evaluate log levels using the cache filters', async () => {
+        const cache = {
+            getKeys: vi
+                .fn()
+                .mockResolvedValue(['LOG_LEVEL:test-type:*', 'LOG_LEVEL:*:*']),
+            get: vi.fn().mockResolvedValue(types_1.LOG_LEVEL.info),
+            set: vi.fn(),
+        };
+        const logger = new TestLogger({
+            cache: cache,
+            params: {
+                actor: 'test-actor',
+                type: 'test-type',
+            },
+        });
+        await expect(logger.exposeIsToLog({
+            level: types_1.LOG_LEVEL.warn,
+            actor: 'test-actor',
+            type: 'test-type',
+            dateTime: new Date(),
+        }, ['payload'])).resolves.toBe(true);
+        await expect(logger.exposeIsToLog({
+            level: types_1.LOG_LEVEL.debug,
+            actor: 'test-actor',
+            type: 'test-type',
+            dateTime: new Date(),
+        }, [])).resolves.toBe(false);
+        await logger.setLevel(types_1.LOG_LEVEL.debug, {
+            logActor: 'user',
+            logType: 'partner',
+        });
+        expect(cache.set).toHaveBeenCalledWith('LOG_LEVEL:partner:user', types_1.LOG_LEVEL.debug, 345600);
+    });
+    it('should fallback to default props and swallow logging errors', async () => {
+        const consoleError = vi
+            .spyOn(console, 'error')
+            .mockImplementation(() => undefined);
+        const consoleLog = vi
+            .spyOn(console, 'log')
+            .mockImplementation(() => undefined);
+        const logger = new TestLogger();
+        logger.registerMock.mockRejectedValue(new Error('register failed'));
+        expect(logger.exposeBuildProps(undefined, undefined)).toEqual(expect.objectContaining({
+            level: types_1.LOG_LEVEL.info,
+            actor: 'default',
+            type: 'default',
+            dateTime: expect.any(Date),
+        }));
+        await expect(logger.log({ level: types_1.LOG_LEVEL.info }, 'payload')).resolves.toBeUndefined();
+        expect(consoleError).toHaveBeenCalledWith('Error in log', expect.any(Error));
+        expect(consoleLog).toHaveBeenCalledWith('Input', { level: types_1.LOG_LEVEL.info }, 'payload');
+    });
+    it('should prefer exact cached filters and expose the level helpers', async () => {
+        const cache = {
+            getKeys: vi
+                .fn()
+                .mockResolvedValue(['LOG_LEVEL:*:*', 'LOG_LEVEL:test-type:test-actor']),
+            get: vi.fn().mockImplementation(async (key) => {
+                return key === 'LOG_LEVEL:test-type:test-actor'
+                    ? types_1.LOG_LEVEL.debug
+                    : types_1.LOG_LEVEL.error;
+            }),
+            set: vi.fn(),
+        };
+        const logger = new TestLogger({
+            cache: cache,
+            params: {
+                actor: 'test-actor',
+                type: 'test-type',
+            },
+        });
+        await logger.info('info-payload');
+        await logger.warn('warn-payload');
+        await logger.error('error-payload');
+        await logger.debug('debug-payload');
+        expect(cache.get).toHaveBeenCalledWith('LOG_LEVEL:test-type:test-actor');
+        expect(logger.registerMock).toHaveBeenCalledTimes(4);
+        expect(logger.registerMock).toHaveBeenNthCalledWith(1, expect.objectContaining({ level: types_1.LOG_LEVEL.info }), ['info-payload']);
+        expect(logger.registerMock).toHaveBeenNthCalledWith(4, expect.objectContaining({ level: types_1.LOG_LEVEL.debug }), ['debug-payload']);
+    });
+    it('should skip setLevel when no cache is configured', async () => {
+        const logger = new TestLogger();
+        await expect(logger.setLevel(types_1.LOG_LEVEL.warn, {
+            logActor: 'user',
+            logType: 'partner',
+        })).resolves.toBeUndefined();
+    });
+});
+describe('LoggerInMemory', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should dispatch console calls according to the log level', () => {
+        const consoleInfo = vi
+            .spyOn(console, 'info')
+            .mockImplementation(() => undefined);
+        const consoleWarn = vi
+            .spyOn(console, 'warn')
+            .mockImplementation(() => undefined);
+        const consoleError = vi
+            .spyOn(console, 'error')
+            .mockImplementation(() => undefined);
+        const consoleDebug = vi
+            .spyOn(console, 'debug')
+            .mockImplementation(() => undefined);
+        const logger = new logger_in_memory_1.LoggerInMemory({
+            options: {
+                showProps: true,
+            },
+        });
+        logger['register']({ level: types_1.LOG_LEVEL.info }, 'payload');
+        logger['register']({ level: types_1.LOG_LEVEL.warn }, ['payload']);
+        logger['register']({ level: types_1.LOG_LEVEL.error }, 'payload');
+        logger['register']({ level: types_1.LOG_LEVEL.debug }, 'payload');
+        expect(consoleInfo).toHaveBeenCalledWith('payload', {
+            level: types_1.LOG_LEVEL.info,
+        });
+        expect(consoleWarn).toHaveBeenCalled();
+        expect(consoleError).toHaveBeenCalled();
+        expect(consoleDebug).toHaveBeenCalled();
+    });
+});
+describe('Audit loggers', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should build audit params and delegate info logs', async () => {
+        const gateway = {
+            info: vi.fn().mockResolvedValue(undefined),
+        };
+        const logger = new TestAuditLogger(gateway);
+        const trace = { ids: [] };
+        const params = logger.exposeBuildParams('partner-created', {
+            entityId: 'user-id',
+            tenantId: 'tenant-id',
+            traceId: 'trace-id',
+        }, trace);
+        expect(params).toEqual({
+            type: 'partner-created',
+            trace: {
+                ids: ['trace-id'],
+            },
+            actor: 'user-id',
+            tenantId: 'tenant-id',
+            actorType: index_1.ActorEnum.USER,
+            category: index_1.CategoryEnum.BUSINESS,
+            expirationHours: 43800,
+        });
+        await logger.exposeInfo({ id: '1' }, params);
+        expect(gateway.info).toHaveBeenCalledWith({ payload: { id: '1' } }, params);
+    });
+});

package/dist/clean-arch/application/queue/handler.d.ts

@@ -1,7 +1,35 @@
+/**
+ * Classe base para consumidores de fila.
+ *
+ * A ideia é estender esta classe e implementar o método `handle`.
+ * A lib usa os metadados abaixo para controlar concorrência e timeout.
+ */
 export default abstract class Handler {
+    /**
+     * Quantas mensagens podem ser processadas em paralelo.
+     *
+     * No RabbitMQ (`AmqpQueue.on`), este valor é aplicado como `prefetch`.
+     * Nos runners de ScaledJob, ele é usado como limite por execução.
+     */
     protected simultaneity: number;
+    /**
+     * Timeout por mensagem, em segundos.
+     *
+     * Quando definido, alguns runners competem o `handle` contra um timeout.
+     */
     protected timeoutPerMessageSeconds: number | undefined;
+    /**
+     * Retorna o nível de concorrência configurado para o handler.
+     */
     getSimultaneity(): number;
+    /**
+     * Retorna o timeout por mensagem, em segundos, se definido.
+     */
     getTimeoutPerMessageSeconds(): number | undefined;
+    /**
+     * Processa uma única mensagem.
+     *
+     * @param message Mensagem já desserializada (normalmente um objeto JSON).
+     */
     abstract handle(message: any): Promise<void>;
 }

package/dist/clean-arch/application/queue/handler.js

@@ -1,11 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Classe base para consumidores de fila.
+ *
+ * A ideia é estender esta classe e implementar o método `handle`.
+ * A lib usa os metadados abaixo para controlar concorrência e timeout.
+ */
 class Handler {
+    /**
+     * Quantas mensagens podem ser processadas em paralelo.
+     *
+     * No RabbitMQ (`AmqpQueue.on`), este valor é aplicado como `prefetch`.
+     * Nos runners de ScaledJob, ele é usado como limite por execução.
+     */
     simultaneity = 1;
+    /**
+     * Timeout por mensagem, em segundos.
+     *
+     * Quando definido, alguns runners competem o `handle` contra um timeout.
+     */
     timeoutPerMessageSeconds = undefined;
+    /**
+     * Retorna o nível de concorrência configurado para o handler.
+     */
     getSimultaneity() {
         return this.simultaneity;
     }
+    /**
+     * Retorna o timeout por mensagem, em segundos, se definido.
+     */
     getTimeoutPerMessageSeconds() {
         return this.timeoutPerMessageSeconds;
     }

package/dist/clean-arch/application/queue/messages-in-memory.d.ts

@@ -1,4 +1,10 @@
 import DomainEvent from '../../domain/events/domain-event';
+/**
+ * Representa uma publicação que falhou e foi guardada em memória.
+ *
+ * A implementação AMQP usa esta estrutura para re-publicar mensagens
+ * após reconexões.
+ */
 export type MessagesInMemory = {
     exchangeName: string;
     domainEvent: DomainEvent;

package/dist/clean-arch/application/queue/queue-connection.d.ts

@@ -1,6 +1,28 @@
 import Queue from './queue';
+/**
+ * Contrato de conexão com a infraestrutura de filas.
+ *
+ * Estende o contrato de `Queue` com ciclo de vida (`connect`/`close`)
+ * e com a capacidade opcional de declarar topologia (`createConsumers`).
+ */
 export default interface QueueConnection extends Queue {
+    /**
+     * Abre a conexão com o provedor de fila.
+     *
+     * @param props Parâmetros de conexão (ex.: vHost no RabbitMQ).
+     */
     connect(props: unknown): Promise<any>;
+    /**
+     * Encerra a conexão atual.
+     */
     close(): Promise<void>;
+    /**
+     * Declara a topologia necessária para um consumidor.
+     *
+     * Este método é opcional porque algumas implementações não precisam
+     * (ou não conseguem) declarar topologia programaticamente.
+     * @deprecated Use createQueues() instead.
+     */
     createConsumers?<T>(queueName: string, configs: T | any): Promise<void>;
+    createQueues?<T>(queueName: string, configs: T | any): Promise<void>;
 }

package/dist/clean-arch/application/queue/queue.d.ts

@@ -1,7 +1,46 @@
 import DomainEvent from '../../domain/events/domain-event';
 import Handler from './handler';
+/**
+ * Contrato mínimo de uma implementação de fila.
+ *
+ * A interface foi pensada para suportar tanto consumo contínuo (`on`)
+ * quanto publicação baseada em eventos de domínio (`publish`).
+ */
 export default interface Queue {
+    /**
+     * Inicia o consumo contínuo de uma fila.
+     *
+     * @param queueName Nome da fila (e, por convenção, também o routing key).
+     * @param callback Handler responsável por processar cada mensagem.
+     */
     on(queueName: string, callback: Handler): Promise<void>;
+    /**
+     * Publica um evento de domínio em um exchange.
+     *
+     * Em implementações AMQP, o `domainEvent.name` costuma ser usado como
+     * routing key e como nome da fila por convenção.
+     *
+     * @param exchangeName Nome do exchange de destino.
+     * @param domainEvent Evento a ser publicado.
+     * @param configs Configurações específicas da implementação (ex.: TTL).
+     */
     publish(exchangeName: string, domainEvent: DomainEvent, configs?: Record<string, any>): Promise<void>;
+    /**
+     * Publica um evento de domínio em um exchange e aguarda a confirmação do broker.
+     *
+     * @param exchangeName Nome do exchange de destino.
+     * @param domainEvent Evento a ser publicado.
+     * @param configs Configurações específicas da implementação.
+     */
+    publishWaitForConfirms(exchangeName: string, domainEvent: DomainEvent, configs?: Record<string, any>): Promise<boolean>;
+    /**
+     * Faz polling (pull) de uma mensagem.
+     *
+     * Este método é opcional porque nem toda implementação precisa suportar
+     * o modelo de consumo por polling.
+     *
+     * @param queueName Nome da fila.
+     * @param options Opções específicas da implementação (ex.: `noAck` no AMQP).
+     */
     get?(queueName: string, options?: any): Promise<unknown>;
 }

package/dist/clean-arch/domain/entities/entity.d.ts

@@ -6,4 +6,7 @@ export declare abstract class Entity<Props> {
     set id(id: UniqueEntityId);
     protected constructor(props: Props, id?: UniqueEntityId);
     equals(entity: Entity<any>): boolean;
+    private serializeValue;
+    toObject(): Record<string, unknown>;
+    toEventDispatchObject(): Record<string, unknown>;
 }

package/dist/clean-arch/domain/entities/entity.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Entity = void 0;
 const unique_entity_id_1 = require("./unique-entity-id");
+const watched_list_1 = require("./watched-list");
 class Entity {
     _id;
     props;
@@ -24,5 +25,39 @@ class Entity {
         }
         return false;
     }
+    serializeValue(value) {
+        if (value instanceof Entity) {
+            return value.toObject();
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (value instanceof unique_entity_id_1.UniqueEntityId) {
+            return value.toString();
+        }
+        if (value instanceof watched_list_1.WatchedList) {
+            return value.toObject();
+        }
+        if (Array.isArray(value)) {
+            return value.map(item => this.serializeValue(item));
+        }
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                key,
+                this.serializeValue(item),
+            ]));
+        }
+        return value;
+    }
+    toObject() {
+        const object = this.serializeValue(this.props);
+        return {
+            ...object,
+            id: this.id.toString(),
+        };
+    }
+    toEventDispatchObject() {
+        return this.toObject();
+    }
 }
 exports.Entity = Entity;

package/dist/clean-arch/domain/entities/entity.spec.d.ts

@@ -0,0 +1 @@
+export {};