@vritti/api-sdk 0.0.7 → 0.0.9

package/dist/index.d.cts

@@ -1,9 +1,11 @@
 import * as _nestjs_common from '@nestjs/common';
-import { DynamicModule, OnModuleDestroy, OnModuleInit, Logger, CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
+import { DynamicModule, OnModuleDestroy, OnModuleInit, Logger, CanActivate, ExecutionContext, ExceptionFilter, ArgumentsHost, HttpException, HttpStatus, ModuleMetadata, Type, NestModule, MiddlewareConsumer, LoggerService as LoggerService$1, NestMiddleware, NestInterceptor, CallHandler } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Reflector } from '@nestjs/core';
 import { JwtService } from '@nestjs/jwt';
-import { FastifyRequest } from 'fastify';
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { Observable } from 'rxjs';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 /**
  * Global authentication configuration module
@@ -1299,32 +1301,6 @@ declare class CsrfGuard implements CanActivate {
     canActivate(context: ExecutionContext): Promise<boolean>;
 }
 
-/**
- * Global HTTP Exception Filter
- *
- * Standardizes all error responses in the format:
- * {
- *   errors: [{ field: string, message: string }],
- *   message?: string,
- *   statusCode: number,
- *   timestamp: string,
- *   path: string
- * }
- *
- * Handles:
- * - Validation errors (class-validator) - Converts to field-specific errors
- * - HTTP exceptions - Maps to standardized format
- * - Unknown errors - Returns generic 500 error
- */
-declare class HttpExceptionFilter implements ExceptionFilter {
-    private readonly logger;
-    catch(exception: unknown, host: ArgumentsHost): void;
-    /**
-     * Parse class-validator error messages into field-specific errors
-     */
-    private parseValidationErrors;
-}
-
 /**
  * Converts an HTTP status code to its corresponding title string.
  * Uses the HttpStatus enum to map status codes to human-readable titles.
@@ -1338,6 +1314,27 @@ declare class HttpExceptionFilter implements ExceptionFilter {
  * getHttpStatusTitle(500) // Returns: "Internal Server Error"
  */
 declare function getHttpStatusTitle(status: number): string;
+/**
+ * Global HTTP Exception Filter implementing RFC 7807 Problem Details
+ *
+ * Transforms all exceptions into a standardized RFC 7807 format:
+ * {
+ *   title: string,        // Human-readable status title
+ *   status: number,       // HTTP status code
+ *   detail: string,       // Detailed error description
+ *   errors: FieldError[]  // Field-specific error messages
+ * }
+ *
+ * Handles:
+ * - Custom field exceptions from @vritti/api-sdk (BaseFieldException)
+ * - Class-validator DTO validation errors
+ * - Standard NestJS HTTP exceptions
+ * - Unknown errors
+ */
+declare class HttpExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
 
 interface FieldError$1 {
     field?: string;
@@ -1769,4 +1766,405 @@ declare class BadGatewayException extends BaseFieldException {
     constructor(messageOrField: string | FieldError[], fieldMessageOrDetail?: string, detail?: string);
 }
 
-export { type ApiErrorResponse, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, CsrfGuard, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, HttpExceptionFilter, HttpModule, InternalServerErrorException, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, RequestTimeoutException, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, ValidationException, VrittiAuthGuard, getHttpStatusTitle };
+/**
+ * Supported log levels for the logging system.
+ */
+type LogLevel = 'error' | 'warn' | 'log' | 'debug' | 'verbose';
+/**
+ * Supported log output formats.
+ */
+type LogFormat = 'json' | 'text';
+/**
+ * Metadata that can be attached to log entries.
+ */
+interface LogMetadata {
+    correlationId?: string;
+    method?: string;
+    url?: string;
+    statusCode?: number;
+    duration?: number;
+    ip?: string;
+    userAgent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for the logger module.
+ */
+interface LoggerModuleOptions {
+    provider?: 'default' | 'winston';
+    level?: LogLevel;
+    format?: LogFormat;
+    enableFileLogger?: boolean;
+    filePath?: string;
+    maxFiles?: string;
+    enableCorrelationId?: boolean;
+    enableHttpLogger?: boolean;
+    httpLogger?: HttpLoggerOptions;
+    appName?: string;
+    environment?: string;
+    defaultMeta?: Record<string, unknown>;
+}
+/**
+ * Factory function for creating logger options asynchronously.
+ */
+interface LoggerOptionsFactory {
+    createLoggerOptions(): Promise<LoggerModuleOptions> | LoggerModuleOptions;
+}
+/**
+ * Async configuration options for the logger module.
+ */
+interface LoggerModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useExisting?: Type<LoggerOptionsFactory>;
+    useClass?: Type<LoggerOptionsFactory>;
+    useFactory?: (...args: unknown[]) => Promise<LoggerModuleOptions> | LoggerModuleOptions;
+    inject?: unknown[];
+}
+/**
+ * Context object for correlation tracking across async operations.
+ */
+interface CorrelationContext {
+    correlationId: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for HTTP request/response logger interceptor.
+ */
+interface HttpLoggerOptions {
+    enableRequestLog?: boolean;
+    enableResponseLog?: boolean;
+    enableRequestBodyLog?: boolean;
+    enableResponseBodyLog?: boolean;
+    slowRequestThreshold?: number;
+    excludedRoutes?: string[];
+    maskedHeaders?: string[];
+    maxBodySize?: number;
+}
+
+/**
+ * Logger Module
+ *
+ * Dynamic NestJS module providing unified logging infrastructure with:
+ * - Environment presets (development, staging, production, test)
+ * - Transparent switching between default NestJS Logger and Winston
+ * - Correlation ID tracking via middleware
+ * - HTTP request/response logging via interceptor
+ * - PII masking and file logging support
+ *
+ * @module logger/logger.module
+ */
+
+/**
+ * Dependency injection token for logger module options
+ */
+declare const LOGGER_MODULE_OPTIONS: unique symbol;
+/**
+ * Global logger module providing unified logging infrastructure.
+ *
+ * Features:
+ * - Environment presets (development, staging, production, test)
+ * - Single `LoggerService` interface for all logging needs
+ * - Transparent provider switching (default ↔ Winston)
+ * - Correlation ID tracking across async operations
+ * - HTTP request/response logging
+ * - PII masking for GDPR compliance
+ * - File-based logging with rotation
+ *
+ * @example
+ * ```typescript
+ * // Production environment with explicit config
+ * @Module({
+ *   imports: [
+ *     LoggerModule.forRoot({
+ *       environment: 'production',
+ *       appName: 'my-service'
+ *     })
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Development environment with custom override
+ * @Module({
+ *   imports: [
+ *     LoggerModule.forRoot({
+ *       environment: 'development',
+ *       level: 'verbose'  // Override preset's debug
+ *     })
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Use default NestJS logger
+ * @Module({
+ *   imports: [
+ *     LoggerModule.forRoot({
+ *       provider: 'default',
+ *       environment: 'development'
+ *     })
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Dynamic configuration with ConfigService
+ * @Module({
+ *   imports: [
+ *     LoggerModule.forRootAsync({
+ *       imports: [ConfigModule],
+ *       useFactory: (config: ConfigService) => ({
+ *         environment: config.get('NODE_ENV', 'development'),
+ *         provider: config.get('LOG_PROVIDER', 'winston'),
+ *         appName: config.get('APP_NAME')
+ *       }),
+ *       inject: [ConfigService]
+ *     })
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+declare class LoggerModule implements NestModule {
+    /**
+     * Configures the logger module with static options.
+     *
+     * Users must explicitly pass `environment` to select a preset.
+     * All preset values can be overridden by passing explicit options.
+     *
+     * @param options - Logger configuration options
+     * @returns Dynamic module configuration
+     *
+     * @example
+     * ```typescript
+     * // Production preset with app name
+     * LoggerModule.forRoot({
+     *   environment: 'production',
+     *   appName: 'my-service'
+     * })
+     *
+     * // Development preset with custom level
+     * LoggerModule.forRoot({
+     *   environment: 'development',
+     *   level: 'verbose',
+     *   enableFileLogger: true
+     * })
+     *
+     * // Use default NestJS logger
+     * LoggerModule.forRoot({
+     *   provider: 'default',
+     *   environment: 'development'
+     * })
+     * ```
+     */
+    static forRoot(options?: LoggerModuleOptions): DynamicModule;
+    /**
+     * Configures the logger module with async options.
+     *
+     * Supports dynamic configuration using:
+     * - `useFactory`: Factory function with dependency injection
+     * - `useClass`: Class implementing `LoggerOptionsFactory`
+     * - `useExisting`: Existing provider implementing `LoggerOptionsFactory`
+     *
+     * Options from the factory/class are merged with environment preset defaults.
+     *
+     * @param options - Async configuration options
+     * @returns Dynamic module configuration
+     *
+     * @example
+     * ```typescript
+     * // Factory with ConfigService
+     * LoggerModule.forRootAsync({
+     *   imports: [ConfigModule],
+     *   useFactory: (config: ConfigService) => ({
+     *     environment: config.get('NODE_ENV', 'development'),
+     *     provider: config.get('LOG_PROVIDER', 'winston'),
+     *     level: config.get('LOG_LEVEL'),
+     *     appName: config.get('APP_NAME'),
+     *   }),
+     *   inject: [ConfigService]
+     * })
+     *
+     * // Factory class
+     * @Injectable()
+     * class LoggerConfigService implements LoggerOptionsFactory {
+     *   createLoggerOptions(): LoggerModuleOptions {
+     *     return {
+     *       environment: 'production',
+     *       appName: 'my-service'
+     *     };
+     *   }
+     * }
+     *
+     * LoggerModule.forRootAsync({
+     *   useClass: LoggerConfigService
+     * })
+     * ```
+     */
+    static forRootAsync(options: LoggerModuleAsyncOptions): DynamicModule;
+    /**
+     * Configures middleware for the module.
+     * Middleware is registered globally in main.ts using Fastify hooks.
+     */
+    configure(consumer: MiddlewareConsumer): void;
+    /**
+     * Creates async providers for dynamic module configuration.
+     */
+    private static createAsyncProviders;
+    /**
+     * Creates the async options provider.
+     */
+    private static createAsyncOptionsProvider;
+}
+
+/**
+ * Unified Logger Service
+ *
+ * Single service that provides both default NestJS Logger and Winston logger implementations.
+ * Automatically delegates to the configured provider (default or winston).
+ * @module logger/logger.service
+ */
+
+/**
+ * Unified logger service implementing NestJS LoggerService interface.
+ * Supports both default NestJS Logger and Winston implementations via facade pattern.
+ */
+declare class LoggerService implements LoggerService$1 {
+    private readonly defaultLogger?;
+    private readonly activeLogger;
+    private readonly options;
+    private context?;
+    constructor(options?: LoggerModuleOptions, defaultLogger?: Logger | undefined);
+    /**
+     * Creates a Winston logger instance with inline configuration.
+     * Consolidates winston-config.factory.ts logic.
+     */
+    private createWinstonLogger;
+    log(message: any, context?: string): void;
+    error(message: any, trace?: string, context?: string): void;
+    warn(message: any, context?: string): void;
+    debug(message: any, context?: string): void;
+    verbose(message: any, context?: string): void;
+    setContext(context: string): void;
+    /**
+     * Unified internal logging method that handles both Winston and NestJS Logger.
+     */
+    private _log;
+    /**
+     * Logs with custom metadata (Winston only).
+     */
+    logWithMetadata(level: LogLevel, message: any, metadata?: LogMetadata, context?: string): void;
+    private formatMessage;
+    /**
+     * Enriches metadata with correlation context from AsyncLocalStorage.
+     * Inline from winston-logger.service.ts
+     */
+    private enrichMetadata;
+    child(context: string): LoggerService;
+}
+
+/**
+ * Correlation ID Middleware
+ *
+ * Generates unique correlation IDs for request tracking across async operations.
+ * Stores correlation ID in AsyncLocalStorage for access throughout the request lifecycle.
+ * @module logger/correlation-id.middleware
+ */
+
+/**
+ * Configuration options for the Correlation ID middleware.
+ */
+interface CorrelationIdMiddlewareOptions {
+    /**
+     * If true, adds the correlation ID to response headers.
+     * @default true
+     */
+    includeInResponse?: boolean;
+    /**
+     * The header name to use when adding correlation ID to response.
+     * @default 'x-correlation-id'
+     */
+    responseHeader?: string;
+}
+/**
+ * Correlation ID Middleware for Fastify/NestJS applications.
+ *
+ * Generates a unique correlation ID for each request,
+ * stores it in AsyncLocalStorage for access throughout the request lifecycle,
+ * and optionally adds it to response headers.
+ */
+declare class CorrelationIdMiddleware implements NestMiddleware {
+    private readonly includeInResponse;
+    private readonly responseHeader;
+    constructor(options?: CorrelationIdMiddlewareOptions);
+    /**
+     * Middleware handler for processing requests.
+     */
+    use(req: FastifyRequest, reply: FastifyReply, next: () => void): void;
+    /**
+     * Fastify hook handler for onRequest.
+     * This is an async function that returns a Promise, ensuring the AsyncLocalStorage
+     * context persists throughout the entire request lifecycle.
+     */
+    onRequest(req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}
+
+/**
+ * HTTP Logger Interceptor
+ *
+ * Automatically logs HTTP requests and responses with correlation tracking.
+ * @module logger/http-logger.interceptor
+ */
+
+/**
+ * HTTP Logger Interceptor for NestJS applications.
+ *
+ * Logs all HTTP requests and responses with metadata including
+ * correlation IDs, performance metrics, and error details.
+ */
+declare class HttpLoggerInterceptor implements NestInterceptor {
+    private readonly logger;
+    private readonly enableRequestLog;
+    private readonly enableResponseLog;
+    private readonly slowRequestThreshold;
+    constructor(logger: LoggerService, options?: HttpLoggerOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+    private logRequest;
+    private logResponse;
+    private logError;
+}
+
+/**
+ * Logging Utilities
+ *
+ * Consolidated utilities for correlation tracking, PII masking, and async context management.
+ * @module logging/utils
+ */
+
+/**
+ * Async local storage for correlation context tracking across async operations.
+ */
+declare const correlationStorage: AsyncLocalStorage<CorrelationContext>;
+/**
+ * Gets the current correlation context from async local storage.
+ */
+declare function getCorrelationContext(): CorrelationContext | undefined;
+/**
+ * Runs a callback within a correlation context.
+ */
+declare function runWithCorrelationContext<T>(context: CorrelationContext, callback: () => T): T;
+/**
+ * Updates the current correlation context with new values.
+ */
+declare function updateCorrelationContext(updates: Partial<CorrelationContext>): void;
+/**
+ * Default header name for setting correlation ID in responses.
+ */
+declare const DEFAULT_CORRELATION_HEADER = "x-correlation-id";
+/**
+ * Generates a new correlation ID using UUID v4.
+ * Always creates a fresh ID for each request.
+ */
+declare function generateCorrelationId(): string;
+/**
+ * Adds correlation ID to Fastify response headers.
+ */
+declare function addCorrelationIdToResponse(reply: FastifyReply, correlationId: string, headerName?: string): void;
+
+export { type ApiErrorResponse, AuthConfigModule, BadGatewayException, BadRequestException, BaseFieldException, ConflictException, type CorrelationContext, CorrelationIdMiddleware, CsrfGuard, DEFAULT_CORRELATION_HEADER, DatabaseModule, type DatabaseModuleOptions, type FieldError, ForbiddenException, GoneException, HttpExceptionFilter, HttpLoggerInterceptor, type HttpLoggerOptions, HttpModule, InternalServerErrorException, LOGGER_MODULE_OPTIONS, type LogFormat, type LogLevel, type LogMetadata, LoggerModule, type LoggerModuleAsyncOptions, type LoggerModuleOptions, type LoggerOptionsFactory, LoggerService, MethodNotAllowedException, NotAcceptableException, NotFoundException, NotImplementedException, Onboarding, PayloadTooLargeException, PrimaryBaseRepository, PrimaryDatabaseService, type PrimaryDbConfig, type ProblemDetails, Public, RequestTimeoutException, ServiceUnavailableException, Tenant, TenantBaseRepository, TenantContextService, TenantDatabaseService, type TenantInfo, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, ValidationException, VrittiAuthGuard, addCorrelationIdToResponse, correlationStorage, generateCorrelationId, getCorrelationContext, getHttpStatusTitle, runWithCorrelationContext, updateCorrelationContext };