@xeno-js/shared 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -2167,6 +2167,15 @@ interface Metadata {
      * @link https://github.com/xeno-js/xeno-js
      */
     readonly csrf: Optional<string>;
+    /**
+     * @description An optional CSRF cookie for preventing cross-site request forgery attacks.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly csrfCookie: Optional<string>;
     /** An optional origin for the request, which can be used for security and access control purposes.
      *
      * @author Xeno
@@ -2711,6 +2720,12 @@ declare const GuidHelper: Readonly<{
    * @link https://github.com/xeno-js/xeno-js
    */
 declare const HttpHelper: Readonly<{
+    /**
+      * @description A function that masks the IP address in the given headers object.
+      * @param ip The IP address to mask.
+      * @returns The masked IP address.
+      */
+    readonly maskIp: (ip: Optional<string>) => Optional<string>;
     /**
      * @description Normalizes HTTP headers by converting all header values to strings. If a header value is an array, it joins the array elements into a single string separated by commas. This method ensures that the headers are in a consistent format, which can be particularly useful when working with different HTTP client libraries that may represent headers in various ways. If the input headers are not defined or not an object, it returns an empty object.
      * @param headers The input headers to be normalized, which can be of any type. The method checks if the headers are defined and are an object before processing them.
@@ -3677,6 +3692,15 @@ interface NetworkContext {
      * @link https://github.com/xeno-js/xeno-js
      */
     readonly csrf: Optional<string>;
+    /**
+     * @description The CSRF cookie for the request, which can be used for preventing cross-site request forgery attacks.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly csrfCookie: Optional<string>;
     /**
      * @description The transport used for the request, which can be used for logging, monitoring, or applying specific middleware logic.
      *
@@ -4960,6 +4984,29 @@ interface ILoggerClient {
     track<T>(level: LogLevel, message: string, context: Optional<T>, error: Optional<unknown>): void;
 }
 
+/**
+ * @description LoggerContext defines the structure for logging-related information used in logging and monitoring. It includes identity, network, and tracing information, as well as optional messaging context for distributed tracing.
+ */
+interface LoggerContext {
+    identity: {
+        userId: Optional<string>;
+        tenantId: Optional<string>;
+    };
+    network: {
+        requestId: Optional<string>;
+        path: Optional<string>;
+        origin: Optional<string>;
+        clientIp: Optional<string>;
+    };
+    tracing: {
+        correlationId: Optional<string>;
+        spanId: Optional<string>;
+        startTime: Optional<number>;
+        parentSpanId: Optional<string>;
+    };
+    messaging?: Maybe<MessagingContext>;
+}
+
 /**
  *  @description Generic mapper interface defining a contract for mapping objects of type TSource to type TDestination. Mappers are used to convert data between different layers of the application, such as transforming DTOs to domain entities or vice versa. This interface defines a contract that all mappers must implement, ensuring consistency and maintainability of the code.
  *  @template TSource The type of the source object to be mapped.
@@ -5865,6 +5912,18 @@ declare class BaseLogger implements ILogger {
     private broadcast;
 }
 
+/**
+ * @description LoggerUtils provides utility functions for working with LoggerContext objects.
+ */
+declare const LoggerUtils: Readonly<{
+    /**
+     * @description toSafeContext converts a RequestContext object to a LoggerContext object, ensuring that only the necessary fields are included.
+     * @param ctx The RequestContext object to convert.
+     * @returns The converted LoggerContext object.
+     */
+    readonly toSafeContext: (ctx: Optional<RequestContext>) => LoggerContext;
+}>;
+
 declare const StorageHelper: Readonly<{
     readonly create: (opts: {
         type: Optional<"local" | "session" | "memory" | "cookie">;
@@ -6059,4 +6118,4 @@ declare class ZodValidatorService implements IValidatorService {
     validate<T>(key: string, data: T): Promise<ResultType<boolean>>;
 }
 
-export { AbortSignalHelper, type AbstractConstructor, type ApiResponseDto, AppError, type AsyncFactory, type AsyncResolver, type AuthClaims, type AuthConfig, type AuthPolicy, AxiosFactory, AxiosHttpClient, BaseLogger, type CacheClientConfig, type CacheConfig, CacheKeyBuilder, Command, type Constructor, type CookieOptions, DEFAULT_CONCURRENCY, DateHelper, type DbConfig, type Delegate, type Dictionary, ERROR_CODES, ERROR_CODE_MESSAGES, Entity, Enumerable, type ErrorCode, type ErrorResponseDto, type Factory, GUEST, Guards, type Guid, GuidHelper, type HttpBaseRequest, type HttpClientConfig, type HttpHeaders, HttpHelper, type HttpMethod, type HttpOptions, type HttpQueryValue, type HttpRequest, type HttpResponse, type HttpResponseType, type IAuthService, type IBaseAccessor, type IBaseAuthService, type IBaseMapper, type ICache, type ICacheKeyBuilder, type ICacheableOptions, type ICommand, type IConcurrencyService, type IConfigurationService, type IContextAccessor, type IController, IDEMPOTENCY_CONSTANTS, type IDisposable, type IEntity, type IExtendendService, type IFactory, type IGateKeeper, type IHandler, type IHttpClient, type IIdempotencyStore, type IIdentityAccessor, type ILogger, type ILoggerClient, type IMapper, type IMediator, type IMiddleware, type INetworkContextAccessor, type IPaginatedResult, type IPipelineBehavior, type IPolicyRegistry, type IQuery, type IReadDao, type IReadDataSource, type IRemoteDataSource, type IRepository, type IRequest, type IServiceExtractor, type IServiceResilience, type ISpecification, type IStorage, type IStrategy, type ITransactionState, type IUnitOfWork, type IValidatorService, type IValueObject, type IWriteDataSource, type Identity, InMemoryCache, type InjectionToken, type KeysOfType, LOG_LEVEL, LOG_LEVEL_NAMES, type LogLevel, MathHelper, type Maybe, type MessageSequence, type MessagingContext, type Metadata, type NetworkContext, type Nullable, type Optional, type Override, PAGINATION_DEFAULTS, PERMISSIONS, type Permission, PromiseHelper, type Provider, type ProxyConfig, Query, REQUEST_TYPE, RESILIENCE_DEFAULTS, ROLES, type RequestContext, type RequestType, type RequireKeys, type Resolver, type ResponseDto, Result, type ResultType, type Role, SORT_DIRECTION, STATUS_CODES, SanitizeHelper, type Session, type SetupAction, type SortDirection, type StatusCode, StorageHelper, StringHelper, type SuccessResponseDto, SupabaseAuthService, SupabaseClaimsMapper, SupabaseSessionMapper, TOKENS, type TracingContext, UniqueId, type UserContext, ValueObject, ZodUtils, ZodValidatorService };
+export { AbortSignalHelper, type AbstractConstructor, type ApiResponseDto, AppError, type AsyncFactory, type AsyncResolver, type AuthClaims, type AuthConfig, type AuthPolicy, AxiosFactory, AxiosHttpClient, BaseLogger, type CacheClientConfig, type CacheConfig, CacheKeyBuilder, Command, type Constructor, type CookieOptions, DEFAULT_CONCURRENCY, DateHelper, type DbConfig, type Delegate, type Dictionary, ERROR_CODES, ERROR_CODE_MESSAGES, Entity, Enumerable, type ErrorCode, type ErrorResponseDto, type Factory, GUEST, Guards, type Guid, GuidHelper, type HttpBaseRequest, type HttpClientConfig, type HttpHeaders, HttpHelper, type HttpMethod, type HttpOptions, type HttpQueryValue, type HttpRequest, type HttpResponse, type HttpResponseType, type IAuthService, type IBaseAccessor, type IBaseAuthService, type IBaseMapper, type ICache, type ICacheKeyBuilder, type ICacheableOptions, type ICommand, type IConcurrencyService, type IConfigurationService, type IContextAccessor, type IController, IDEMPOTENCY_CONSTANTS, type IDisposable, type IEntity, type IExtendendService, type IFactory, type IGateKeeper, type IHandler, type IHttpClient, type IIdempotencyStore, type IIdentityAccessor, type ILogger, type ILoggerClient, type IMapper, type IMediator, type IMiddleware, type INetworkContextAccessor, type IPaginatedResult, type IPipelineBehavior, type IPolicyRegistry, type IQuery, type IReadDao, type IReadDataSource, type IRemoteDataSource, type IRepository, type IRequest, type IServiceExtractor, type IServiceResilience, type ISpecification, type IStorage, type IStrategy, type ITransactionState, type IUnitOfWork, type IValidatorService, type IValueObject, type IWriteDataSource, type Identity, InMemoryCache, type InjectionToken, type KeysOfType, LOG_LEVEL, LOG_LEVEL_NAMES, type LogLevel, type LoggerContext, LoggerUtils, MathHelper, type Maybe, type MessageSequence, type MessagingContext, type Metadata, type NetworkContext, type Nullable, type Optional, type Override, PAGINATION_DEFAULTS, PERMISSIONS, type Permission, PromiseHelper, type Provider, type ProxyConfig, Query, REQUEST_TYPE, RESILIENCE_DEFAULTS, ROLES, type RequestContext, type RequestType, type RequireKeys, type Resolver, type ResponseDto, Result, type ResultType, type Role, SORT_DIRECTION, STATUS_CODES, SanitizeHelper, type Session, type SetupAction, type SortDirection, type StatusCode, StorageHelper, StringHelper, type SuccessResponseDto, SupabaseAuthService, SupabaseClaimsMapper, SupabaseSessionMapper, TOKENS, type TracingContext, UniqueId, type UserContext, ValueObject, ZodUtils, ZodValidatorService };

package/dist/index.d.ts

@@ -2167,6 +2167,15 @@ interface Metadata {
      * @link https://github.com/xeno-js/xeno-js
      */
     readonly csrf: Optional<string>;
+    /**
+     * @description An optional CSRF cookie for preventing cross-site request forgery attacks.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly csrfCookie: Optional<string>;
     /** An optional origin for the request, which can be used for security and access control purposes.
      *
      * @author Xeno
@@ -2711,6 +2720,12 @@ declare const GuidHelper: Readonly<{
    * @link https://github.com/xeno-js/xeno-js
    */
 declare const HttpHelper: Readonly<{
+    /**
+      * @description A function that masks the IP address in the given headers object.
+      * @param ip The IP address to mask.
+      * @returns The masked IP address.
+      */
+    readonly maskIp: (ip: Optional<string>) => Optional<string>;
     /**
      * @description Normalizes HTTP headers by converting all header values to strings. If a header value is an array, it joins the array elements into a single string separated by commas. This method ensures that the headers are in a consistent format, which can be particularly useful when working with different HTTP client libraries that may represent headers in various ways. If the input headers are not defined or not an object, it returns an empty object.
      * @param headers The input headers to be normalized, which can be of any type. The method checks if the headers are defined and are an object before processing them.
@@ -3677,6 +3692,15 @@ interface NetworkContext {
      * @link https://github.com/xeno-js/xeno-js
      */
     readonly csrf: Optional<string>;
+    /**
+     * @description The CSRF cookie for the request, which can be used for preventing cross-site request forgery attacks.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly csrfCookie: Optional<string>;
     /**
      * @description The transport used for the request, which can be used for logging, monitoring, or applying specific middleware logic.
      *
@@ -4960,6 +4984,29 @@ interface ILoggerClient {
     track<T>(level: LogLevel, message: string, context: Optional<T>, error: Optional<unknown>): void;
 }
 
+/**
+ * @description LoggerContext defines the structure for logging-related information used in logging and monitoring. It includes identity, network, and tracing information, as well as optional messaging context for distributed tracing.
+ */
+interface LoggerContext {
+    identity: {
+        userId: Optional<string>;
+        tenantId: Optional<string>;
+    };
+    network: {
+        requestId: Optional<string>;
+        path: Optional<string>;
+        origin: Optional<string>;
+        clientIp: Optional<string>;
+    };
+    tracing: {
+        correlationId: Optional<string>;
+        spanId: Optional<string>;
+        startTime: Optional<number>;
+        parentSpanId: Optional<string>;
+    };
+    messaging?: Maybe<MessagingContext>;
+}
+
 /**
  *  @description Generic mapper interface defining a contract for mapping objects of type TSource to type TDestination. Mappers are used to convert data between different layers of the application, such as transforming DTOs to domain entities or vice versa. This interface defines a contract that all mappers must implement, ensuring consistency and maintainability of the code.
  *  @template TSource The type of the source object to be mapped.
@@ -5865,6 +5912,18 @@ declare class BaseLogger implements ILogger {
     private broadcast;
 }
 
+/**
+ * @description LoggerUtils provides utility functions for working with LoggerContext objects.
+ */
+declare const LoggerUtils: Readonly<{
+    /**
+     * @description toSafeContext converts a RequestContext object to a LoggerContext object, ensuring that only the necessary fields are included.
+     * @param ctx The RequestContext object to convert.
+     * @returns The converted LoggerContext object.
+     */
+    readonly toSafeContext: (ctx: Optional<RequestContext>) => LoggerContext;
+}>;
+
 declare const StorageHelper: Readonly<{
     readonly create: (opts: {
         type: Optional<"local" | "session" | "memory" | "cookie">;
@@ -6059,4 +6118,4 @@ declare class ZodValidatorService implements IValidatorService {
     validate<T>(key: string, data: T): Promise<ResultType<boolean>>;
 }
 
-export { AbortSignalHelper, type AbstractConstructor, type ApiResponseDto, AppError, type AsyncFactory, type AsyncResolver, type AuthClaims, type AuthConfig, type AuthPolicy, AxiosFactory, AxiosHttpClient, BaseLogger, type CacheClientConfig, type CacheConfig, CacheKeyBuilder, Command, type Constructor, type CookieOptions, DEFAULT_CONCURRENCY, DateHelper, type DbConfig, type Delegate, type Dictionary, ERROR_CODES, ERROR_CODE_MESSAGES, Entity, Enumerable, type ErrorCode, type ErrorResponseDto, type Factory, GUEST, Guards, type Guid, GuidHelper, type HttpBaseRequest, type HttpClientConfig, type HttpHeaders, HttpHelper, type HttpMethod, type HttpOptions, type HttpQueryValue, type HttpRequest, type HttpResponse, type HttpResponseType, type IAuthService, type IBaseAccessor, type IBaseAuthService, type IBaseMapper, type ICache, type ICacheKeyBuilder, type ICacheableOptions, type ICommand, type IConcurrencyService, type IConfigurationService, type IContextAccessor, type IController, IDEMPOTENCY_CONSTANTS, type IDisposable, type IEntity, type IExtendendService, type IFactory, type IGateKeeper, type IHandler, type IHttpClient, type IIdempotencyStore, type IIdentityAccessor, type ILogger, type ILoggerClient, type IMapper, type IMediator, type IMiddleware, type INetworkContextAccessor, type IPaginatedResult, type IPipelineBehavior, type IPolicyRegistry, type IQuery, type IReadDao, type IReadDataSource, type IRemoteDataSource, type IRepository, type IRequest, type IServiceExtractor, type IServiceResilience, type ISpecification, type IStorage, type IStrategy, type ITransactionState, type IUnitOfWork, type IValidatorService, type IValueObject, type IWriteDataSource, type Identity, InMemoryCache, type InjectionToken, type KeysOfType, LOG_LEVEL, LOG_LEVEL_NAMES, type LogLevel, MathHelper, type Maybe, type MessageSequence, type MessagingContext, type Metadata, type NetworkContext, type Nullable, type Optional, type Override, PAGINATION_DEFAULTS, PERMISSIONS, type Permission, PromiseHelper, type Provider, type ProxyConfig, Query, REQUEST_TYPE, RESILIENCE_DEFAULTS, ROLES, type RequestContext, type RequestType, type RequireKeys, type Resolver, type ResponseDto, Result, type ResultType, type Role, SORT_DIRECTION, STATUS_CODES, SanitizeHelper, type Session, type SetupAction, type SortDirection, type StatusCode, StorageHelper, StringHelper, type SuccessResponseDto, SupabaseAuthService, SupabaseClaimsMapper, SupabaseSessionMapper, TOKENS, type TracingContext, UniqueId, type UserContext, ValueObject, ZodUtils, ZodValidatorService };
+export { AbortSignalHelper, type AbstractConstructor, type ApiResponseDto, AppError, type AsyncFactory, type AsyncResolver, type AuthClaims, type AuthConfig, type AuthPolicy, AxiosFactory, AxiosHttpClient, BaseLogger, type CacheClientConfig, type CacheConfig, CacheKeyBuilder, Command, type Constructor, type CookieOptions, DEFAULT_CONCURRENCY, DateHelper, type DbConfig, type Delegate, type Dictionary, ERROR_CODES, ERROR_CODE_MESSAGES, Entity, Enumerable, type ErrorCode, type ErrorResponseDto, type Factory, GUEST, Guards, type Guid, GuidHelper, type HttpBaseRequest, type HttpClientConfig, type HttpHeaders, HttpHelper, type HttpMethod, type HttpOptions, type HttpQueryValue, type HttpRequest, type HttpResponse, type HttpResponseType, type IAuthService, type IBaseAccessor, type IBaseAuthService, type IBaseMapper, type ICache, type ICacheKeyBuilder, type ICacheableOptions, type ICommand, type IConcurrencyService, type IConfigurationService, type IContextAccessor, type IController, IDEMPOTENCY_CONSTANTS, type IDisposable, type IEntity, type IExtendendService, type IFactory, type IGateKeeper, type IHandler, type IHttpClient, type IIdempotencyStore, type IIdentityAccessor, type ILogger, type ILoggerClient, type IMapper, type IMediator, type IMiddleware, type INetworkContextAccessor, type IPaginatedResult, type IPipelineBehavior, type IPolicyRegistry, type IQuery, type IReadDao, type IReadDataSource, type IRemoteDataSource, type IRepository, type IRequest, type IServiceExtractor, type IServiceResilience, type ISpecification, type IStorage, type IStrategy, type ITransactionState, type IUnitOfWork, type IValidatorService, type IValueObject, type IWriteDataSource, type Identity, InMemoryCache, type InjectionToken, type KeysOfType, LOG_LEVEL, LOG_LEVEL_NAMES, type LogLevel, type LoggerContext, LoggerUtils, MathHelper, type Maybe, type MessageSequence, type MessagingContext, type Metadata, type NetworkContext, type Nullable, type Optional, type Override, PAGINATION_DEFAULTS, PERMISSIONS, type Permission, PromiseHelper, type Provider, type ProxyConfig, Query, REQUEST_TYPE, RESILIENCE_DEFAULTS, ROLES, type RequestContext, type RequestType, type RequireKeys, type Resolver, type ResponseDto, Result, type ResultType, type Role, SORT_DIRECTION, STATUS_CODES, SanitizeHelper, type Session, type SetupAction, type SortDirection, type StatusCode, StorageHelper, StringHelper, type SuccessResponseDto, SupabaseAuthService, SupabaseClaimsMapper, SupabaseSessionMapper, TOKENS, type TracingContext, UniqueId, type UserContext, ValueObject, ZodUtils, ZodValidatorService };

package/dist/index.js

@@ -1548,6 +1548,29 @@ var GuidHelper = Object.freeze({
 
 // src/shared/utils/http.utils.ts
 var HttpHelper = Object.freeze({
+  /**
+    * @description A function that masks the IP address in the given headers object.
+    * @param ip The IP address to mask.
+    * @returns The masked IP address.
+    */
+  maskIp(ip) {
+    if (!Guards.isDefined(ip)) return void 0;
+    if (ip.includes(".")) {
+      const parts = ip.split(".");
+      if (parts.length === 4) {
+        parts[3] = "x";
+        return parts.join(".");
+      }
+    }
+    if (ip.includes(":")) {
+      const parts = ip.split(":");
+      if (parts.length > 0) {
+        parts[parts.length - 1] = "x";
+        return parts.join(":");
+      }
+    }
+    return ip;
+  },
   /**
    * @description Normalizes HTTP headers by converting all header values to strings. If a header value is an array, it joins the array elements into a single string separated by commas. This method ensures that the headers are in a consistent format, which can be particularly useful when working with different HTTP client libraries that may represent headers in various ways. If the input headers are not defined or not an object, it returns an empty object.
    * @param headers The input headers to be normalized, which can be of any type. The method checks if the headers are defined and are an object before processing them.
@@ -1998,6 +2021,36 @@ var Query = class {
   type = REQUEST_TYPE.QUERY;
 };
 
+// src/application/loggers/utils/logger-context.utils.ts
+var LoggerUtils = Object.freeze({
+  /**
+   * @description toSafeContext converts a RequestContext object to a LoggerContext object, ensuring that only the necessary fields are included.
+   * @param ctx The RequestContext object to convert.
+   * @returns The converted LoggerContext object.
+   */
+  toSafeContext(ctx) {
+    return {
+      identity: {
+        userId: ctx?.identity?.userId,
+        tenantId: ctx?.identity?.tenantId
+      },
+      network: {
+        requestId: ctx?.network?.requestId,
+        path: ctx?.network?.path,
+        origin: ctx?.network?.origin,
+        clientIp: HttpHelper.maskIp(ctx?.network?.clientIp)
+      },
+      tracing: {
+        correlationId: ctx?.tracing?.correlationId,
+        spanId: ctx?.tracing?.spanId,
+        startTime: ctx?.tracing?.startTime,
+        parentSpanId: ctx?.tracing.parentSpanId
+      },
+      messaging: ctx?.messaging
+    };
+  }
+});
+
 // src/application/loggers/base.logger.ts
 var BaseLogger = class {
   /**
@@ -2050,8 +2103,9 @@ var BaseLogger = class {
     if (level < this._minLevel) return;
     const logMessage = `[${LOG_LEVEL_NAMES[level]}] ${message}`;
     const context = this._requestContext.getContext();
+    const safeContext = LoggerUtils.toSafeContext(context);
     for (const logger of this._loggers) {
-      logger.track(level, logMessage, context, error);
+      logger.track(level, logMessage, safeContext, error);
     }
   }
 };
@@ -3075,6 +3129,7 @@ export {
   InMemoryCache,
   LOG_LEVEL,
   LOG_LEVEL_NAMES,
+  LoggerUtils,
   MathHelper,
   PAGINATION_DEFAULTS,
   PERMISSIONS,