@tstdl/base 0.93.1 → 0.93.2

package/audit/audit.model.d.ts

@@ -1,15 +1,110 @@
-import { EntityWithoutMetadata, Json, Timestamp, Uuid } from '../orm/index.js';
+import { Embedded, EntityWithoutMetadata, Json, Timestamp, Uuid } from '../orm/index.js';
+import type { UndefinableJsonObject } from '../types/index.js';
 import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
-export declare class AuditEvent extends EntityWithoutMetadata {
+/**
+ * Represents the network details of the request that triggered the audit event.
+ */
+export declare class RequestDetails {
+    /**
+     * The IP address of the client.
+     * @example '192.168.1.100'
+     */
+    ipAddress: string | null;
+    /**
+     * The user agent string of the client.
+     * @example 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...'
+     */
+    userAgent: string | null;
+    /**
+     * The session ID associated with the request, if any.
+     */
+    sessionId: Uuid | null;
+}
+/**
+ * Represents the state of data before and after a change.
+ */
+export declare class ChangeDetails {
+    /**
+     * The state of the data before the change occurred.
+     */
+    before: Json<unknown> | null;
+    /**
+     * The state of the data after the change occurred.
+     */
+    after: Json<unknown> | null;
+}
+/**
+ * Represents a single audit event record in the database.
+ * This entity captures who did what, when, and to what, along with other contextual information.
+ *
+ * @template Details The type of the `details` JSON object, allowing for custom, action-specific data.
+ */
+export declare class AuditEvent<Details extends UndefinableJsonObject = UndefinableJsonObject> extends EntityWithoutMetadata {
+    /**
+     * The timestamp when the event occurred.
+     */
     timestamp: Timestamp;
-    correlationId?: Uuid;
+    /**
+     * The ID of the tenant in which the event occurred. Can be null for system-level events.
+     */
+    tenantId: Uuid | null;
+    /**
+     * A unique identifier to correlate multiple related audit events.
+     */
+    correlationId: Uuid | null;
+    /**
+     * The module or feature area where the event originated, in dot-separated format.
+     * @example 'user.authentication'
+     */
     module: string;
+    /**
+     * The specific action that was performed.
+     * @example 'login'
+     */
     action: string;
+    /**
+     * The outcome of the action.
+     */
     outcome: AuditOutcome;
+    /**
+     * The severity level of the event.
+     */
     severity: AuditSeverity;
-    actorId: string;
+    /**
+     * The unique identifier of the actor who performed the action.
+     */
+    actorId: Uuid;
+    /**
+     * The type of the actor.
+     */
     actorType: ActorType;
-    targetId: string;
+    /**
+     * The unique identifier of the user who is impersonating the actor, if applicable.
+     */
+    impersonatorId: Uuid | null;
+    /**
+     * The type of the impersonator, if applicable.
+     */
+    impersonatorType: ActorType | null;
+    /**
+     * The unique identifier of the primary resource or entity that was the target of the action.
+     */
+    targetId: Uuid;
+    /**
+     * The type of the target entity.
+     * @example 'User'
+     */
     targetType: string;
-    details?: Json<unknown>;
+    /**
+     * Network-related details for the request that triggered the event.
+     */
+    network: Embedded<RequestDetails> | null;
+    /**
+     * Details about data changes.
+     */
+    changes: Embedded<ChangeDetails> | null;
+    /**
+     * A flexible JSON object for storing additional, action-specific details.
+     */
+    details: Json<Details> | null;
 }

package/audit/audit.model.js

@@ -7,20 +7,134 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { EntityWithoutMetadata, Json, Table, Timestamp, Uuid } from '../orm/index.js';
+import { Embedded, EntityWithoutMetadata, Json, Table, Timestamp, Uuid } from '../orm/index.js';
 import { Enumeration, StringProperty } from '../schema/index.js';
 import { ActorType, AuditOutcome, AuditSeverity } from './types.js';
+/**
+ * Represents the network details of the request that triggered the audit event.
+ */
+export class RequestDetails {
+    /**
+     * The IP address of the client.
+     * @example '192.168.1.100'
+     */
+    ipAddress;
+    /**
+     * The user agent string of the client.
+     * @example 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...'
+     */
+    userAgent;
+    /**
+     * The session ID associated with the request, if any.
+     */
+    sessionId;
+}
+__decorate([
+    StringProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], RequestDetails.prototype, "ipAddress", void 0);
+__decorate([
+    StringProperty({ nullable: true }),
+    __metadata("design:type", Object)
+], RequestDetails.prototype, "userAgent", void 0);
+__decorate([
+    Uuid({ nullable: true }),
+    __metadata("design:type", Object)
+], RequestDetails.prototype, "sessionId", void 0);
+/**
+ * Represents the state of data before and after a change.
+ */
+export class ChangeDetails {
+    /**
+     * The state of the data before the change occurred.
+     */
+    before;
+    /**
+     * The state of the data after the change occurred.
+     */
+    after;
+}
+__decorate([
+    Json({ nullable: true }),
+    __metadata("design:type", Object)
+], ChangeDetails.prototype, "before", void 0);
+__decorate([
+    Json({ nullable: true }),
+    __metadata("design:type", Object)
+], ChangeDetails.prototype, "after", void 0);
+/**
+ * Represents a single audit event record in the database.
+ * This entity captures who did what, when, and to what, along with other contextual information.
+ *
+ * @template Details The type of the `details` JSON object, allowing for custom, action-specific data.
+ */
 let AuditEvent = class AuditEvent extends EntityWithoutMetadata {
+    /**
+     * The timestamp when the event occurred.
+     */
     timestamp;
+    /**
+     * The ID of the tenant in which the event occurred. Can be null for system-level events.
+     */
+    tenantId;
+    /**
+     * A unique identifier to correlate multiple related audit events.
+     */
     correlationId;
+    /**
+     * The module or feature area where the event originated, in dot-separated format.
+     * @example 'user.authentication'
+     */
     module;
+    /**
+     * The specific action that was performed.
+     * @example 'login'
+     */
     action;
+    /**
+     * The outcome of the action.
+     */
     outcome;
+    /**
+     * The severity level of the event.
+     */
     severity;
+    /**
+     * The unique identifier of the actor who performed the action.
+     */
     actorId;
+    /**
+     * The type of the actor.
+     */
     actorType;
+    /**
+     * The unique identifier of the user who is impersonating the actor, if applicable.
+     */
+    impersonatorId;
+    /**
+     * The type of the impersonator, if applicable.
+     */
+    impersonatorType;
+    /**
+     * The unique identifier of the primary resource or entity that was the target of the action.
+     */
     targetId;
+    /**
+     * The type of the target entity.
+     * @example 'User'
+     */
     targetType;
+    /**
+     * Network-related details for the request that triggered the event.
+     */
+    network;
+    /**
+     * Details about data changes.
+     */
+    changes;
+    /**
+     * A flexible JSON object for storing additional, action-specific details.
+     */
     details;
 };
 __decorate([
@@ -29,7 +143,11 @@ __decorate([
 ], AuditEvent.prototype, "timestamp", void 0);
 __decorate([
     Uuid({ nullable: true }),
-    __metadata("design:type", String)
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "tenantId", void 0);
+__decorate([
+    Uuid({ nullable: true }),
+    __metadata("design:type", Object)
 ], AuditEvent.prototype, "correlationId", void 0);
 __decorate([
     StringProperty(),
@@ -48,7 +166,7 @@ __decorate([
     __metadata("design:type", String)
 ], AuditEvent.prototype, "severity", void 0);
 __decorate([
-    StringProperty(),
+    Uuid(),
     __metadata("design:type", String)
 ], AuditEvent.prototype, "actorId", void 0);
 __decorate([
@@ -56,13 +174,29 @@ __decorate([
     __metadata("design:type", String)
 ], AuditEvent.prototype, "actorType", void 0);
 __decorate([
-    StringProperty(),
+    Uuid({ nullable: true }),
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "impersonatorId", void 0);
+__decorate([
+    Enumeration(ActorType, { nullable: true }),
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "impersonatorType", void 0);
+__decorate([
+    Uuid(),
     __metadata("design:type", String)
 ], AuditEvent.prototype, "targetId", void 0);
 __decorate([
     StringProperty(),
     __metadata("design:type", String)
 ], AuditEvent.prototype, "targetType", void 0);
+__decorate([
+    Embedded(RequestDetails),
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "network", void 0);
+__decorate([
+    Embedded(ChangeDetails),
+    __metadata("design:type", Object)
+], AuditEvent.prototype, "changes", void 0);
 __decorate([
     Json({ nullable: true }),
     __metadata("design:type", Object)

package/audit/auditor.d.ts

@@ -1,42 +1,118 @@
 import { type Resolvable, type resolveArgumentType } from '../injector/index.js';
-import type { UndefinableJsonObject } from '../types/index.js';
-import type { ActorType } from './types.js';
-import { AuditOutcome, AuditSeverity } from './types.js';
-export type AuditPayload = Partial<{
-    correlationId?: string;
-    outcome?: AuditOutcome;
-    severity?: AuditSeverity;
-    actorId?: string;
-    actorType?: ActorType;
-    targetId?: string;
-    targetType?: string;
-    details?: UndefinableJsonObject;
+import type { TypedOmit, UndefinableJsonObject } from '../types/index.js';
+import { AuditEvent } from './audit.model.js';
+export type AuditPayload = Partial<TypedOmit<AuditEvent, 'id' | 'timestamp' | 'module' | 'action' | 'details'> & {
+    details: UndefinableJsonObject;
 }>;
 export type AuditorArgument = string | string[] | {
+    /**
+     * The module or path of modules for the auditor.
+     */
     module?: string | string[];
+    /**
+     * Default context to apply to all events logged by this auditor instance.
+     */
     context?: Partial<AuditPayload>;
 };
-export declare class Auditor implements Resolvable<AuditorArgument> {
+type AuditEvents = Record<string, UndefinableJsonObject>;
+/**
+ * A service for logging audit events.
+ * It provides a structured way to record activities within the system.
+ * The Auditor can be forked to create sub-auditors for different modules or enriched with contextual data.
+ *
+ * @template Events A record mapping event action names to their specific `details` payload types.
+ */
+export declare class Auditor<Events extends AuditEvents = AuditEvents> implements Resolvable<AuditorArgument> {
     #private;
+    /**
+     * The module path for this auditor instance.
+     */
     readonly module: string[];
-    readonly context: Partial<Partial<{
-        correlationId?: string;
-        outcome?: AuditOutcome;
-        severity?: AuditSeverity;
-        actorId?: string;
-        actorType?: ActorType;
-        targetId?: string;
-        targetType?: string;
-        details?: UndefinableJsonObject;
+    /**
+     * The context that is automatically merged into every event logged by this auditor.
+     */
+    readonly context: Partial<Partial<TypedOmit<AuditEvent<UndefinableJsonObject>, "module" | "timestamp" | "id" | "details" | "action"> & {
+        details: UndefinableJsonObject;
     }>>;
+    /**
+     * A dot-separated string representation of the module path.
+     * @example ['user', 'authentication'] becomes 'user.authentication'
+     */
     get moduleString(): string;
     readonly [resolveArgumentType]: AuditorArgument;
-    fork(subModule: string | string[]): Auditor;
-    with(context: Partial<AuditPayload>): Auditor;
-    withCorrelation(): Auditor;
-    log(action: string, data?: AuditPayload): Promise<void>;
-    info(action: string, data: AuditPayload): Promise<void>;
-    warn(action: string, data: AuditPayload): Promise<void>;
-    error(action: string, data: AuditPayload): Promise<void>;
-    critical(action: string, data: AuditPayload): Promise<void>;
+    /**
+     * Creates a new `Auditor` instance for a submodule.
+     * The new auditor inherits the context of its parent and appends the submodule to its module path.
+     *
+     * @param subModule The name of the submodule or a path of submodules.
+     * @returns A new `Auditor` instance for the specified submodule.
+     * @template T The event map of the new Auditor instance.
+     */
+    fork<T extends AuditEvents = Events>(subModule: string | string[]): Auditor<T>;
+    /**
+     * Creates a new `Auditor` instance with additional context.
+     * The new context is merged with the existing context.
+     *
+     * @param context The additional context to apply.
+     * @returns A new `Auditor` instance with the merged context.
+     * @template T The event map of the new Auditor instance.
+     */
+    with<T extends AuditEvents = Events>(context: Partial<AuditPayload>): Auditor<T>;
+    /**
+     * Creates a new `Auditor` instance with a correlation ID in its context.
+     * If a correlation ID already exists in the context, it is preserved. Otherwise, a new UUID is generated.
+     *
+     * @returns A new `Auditor` instance with a correlation ID.
+     */
+    withCorrelation(): Auditor<Events>;
+    /**
+     * Logs a generic audit event.
+     *
+     * @param action The name of the action being logged. Must be a key of the `Events` type.
+     * @param data The payload containing details about the event.
+     */
+    log<E extends Extract<keyof Events, string>>(action: E, data?: AuditPayload & {
+        details: Events[E];
+    }): Promise<void>;
+    /**
+     * Logs an informational event.
+     * Automatically sets severity to `Info` and defaults outcome to `Success`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
+    info<E extends Extract<keyof Events, string>>(action: E, data: AuditPayload & {
+        details: Events[E];
+    }): Promise<void>;
+    /**
+     * Logs a warning event.
+     * Automatically sets severity to `Warn` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
+    warn<E extends Extract<keyof Events, string>>(action: E, data: AuditPayload & {
+        details: Events[E];
+    }): Promise<void>;
+    /**
+     * Logs an error event.
+     * Automatically sets severity to `Error` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
+    error<E extends Extract<keyof Events, string>>(action: E, data: AuditPayload & {
+        details: Events[E];
+    }): Promise<void>;
+    /**
+     * Logs a critical event.
+     * Automatically sets severity to `Critical` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
+    critical<E extends Extract<keyof Events, string>>(action: E, data: AuditPayload & {
+        details: Events[E];
+    }): Promise<void>;
 }
+export {};

package/audit/auditor.js

@@ -19,46 +19,103 @@ import { assertDefinedPass, isArray, isNotArray, isObject, isString } from '../u
 import { AuditEvent } from './audit.model.js';
 import { AuditOutcome, AuditSeverity } from './types.js';
 const { runInAuditorCreationContext, getCurrentAuditorCreationContext, isInAuditorCreationContext } = createContextProvider('AuditorCreation');
+/**
+ * A service for logging audit events.
+ * It provides a structured way to record activities within the system.
+ * The Auditor can be forked to create sub-auditors for different modules or enriched with contextual data.
+ *
+ * @template Events A record mapping event action names to their specific `details` payload types.
+ */
 let Auditor = Auditor_1 = class Auditor {
     #repository = injectRepository(AuditEvent);
     #argument = isInAuditorCreationContext() ? injectArgument(this, { optional: true }) : undefined;
     #creationContext = getCurrentAuditorCreationContext();
+    /**
+     * The module path for this auditor instance.
+     */
     module = this.#creationContext?.module ?? moduleFromArgument(this.#argument);
+    /**
+     * The context that is automatically merged into every event logged by this auditor.
+     */
     context = this.#creationContext?.context ?? ((isObject(this.#argument) && isNotArray(this.#argument)) ? (this.#argument.context ?? {}) : {});
+    /**
+     * A dot-separated string representation of the module path.
+     * @example ['user', 'authentication'] becomes 'user.authentication'
+     */
     get moduleString() {
         return this.module.join('.');
     }
+    /**
+     * Creates a new `Auditor` instance for a submodule.
+     * The new auditor inherits the context of its parent and appends the submodule to its module path.
+     *
+     * @param subModule The name of the submodule or a path of submodules.
+     * @returns A new `Auditor` instance for the specified submodule.
+     * @template T The event map of the new Auditor instance.
+     */
     fork(subModule) {
         return runInAuditorCreationContext({
             module: [...this.module, ...toArray(subModule)],
             context: this.context,
         }, () => new Auditor_1());
     }
+    /**
+     * Creates a new `Auditor` instance with additional context.
+     * The new context is merged with the existing context.
+     *
+     * @param context The additional context to apply.
+     * @returns A new `Auditor` instance with the merged context.
+     * @template T The event map of the new Auditor instance.
+     */
     with(context) {
         return runInAuditorCreationContext({
             module: this.module,
             context: { ...this.context, ...context, details: { ...this.context.details, ...context.details } },
         }, () => new Auditor_1());
     }
+    /**
+     * Creates a new `Auditor` instance with a correlation ID in its context.
+     * If a correlation ID already exists in the context, it is preserved. Otherwise, a new UUID is generated.
+     *
+     * @returns A new `Auditor` instance with a correlation ID.
+     */
     withCorrelation() {
         return this.with({ correlationId: this.context.correlationId ?? crypto.randomUUID() });
     }
+    /**
+     * Logs a generic audit event.
+     *
+     * @param action The name of the action being logged. Must be a key of the `Events` type.
+     * @param data The payload containing details about the event.
+     */
     async log(action, data) {
         const mergedData = { ...this.context, ...data, details: filterUndefinedFromRecord({ ...this.context.details, ...data?.details }) };
         await this.#repository.insert({
             timestamp: TRANSACTION_TIMESTAMP,
-            correlationId: mergedData.correlationId,
+            tenantId: mergedData.tenantId ?? null,
+            correlationId: mergedData.correlationId ?? null,
             module: this.moduleString,
             action: action,
             outcome: assertDefinedPass(mergedData.outcome, 'Audit outcome is required'),
             severity: assertDefinedPass(mergedData.severity, 'Audit severity is required'),
             actorId: assertDefinedPass(mergedData.actorId, 'Audit actorId is required'),
             actorType: assertDefinedPass(mergedData.actorType, 'Audit actorType is required'),
+            impersonatorId: mergedData.impersonatorId ?? null,
+            impersonatorType: mergedData.impersonatorType ?? null,
             targetId: assertDefinedPass(mergedData.targetId, 'Audit targetId is required'),
             targetType: assertDefinedPass(mergedData.targetType, 'Audit targetType is required'),
-            details: (objectKeys(mergedData.details).length > 0) ? mergedData.details : undefined,
+            network: mergedData.network ?? null,
+            changes: mergedData.changes ?? null,
+            details: (objectKeys(mergedData.details).length > 0) ? mergedData.details : null,
         });
     }
+    /**
+     * Logs an informational event.
+     * Automatically sets severity to `Info` and defaults outcome to `Success`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
     async info(action, data) {
         await this.log(action, {
             ...data,
@@ -66,6 +123,13 @@ let Auditor = Auditor_1 = class Auditor {
             outcome: data.outcome ?? AuditOutcome.Success,
         });
     }
+    /**
+     * Logs a warning event.
+     * Automatically sets severity to `Warn` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
     async warn(action, data) {
         await this.log(action, {
             ...data,
@@ -73,6 +137,13 @@ let Auditor = Auditor_1 = class Auditor {
             outcome: data.outcome ?? AuditOutcome.Failure,
         });
     }
+    /**
+     * Logs an error event.
+     * Automatically sets severity to `Error` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
     async error(action, data) {
         await this.log(action, {
             ...data,
@@ -80,6 +151,13 @@ let Auditor = Auditor_1 = class Auditor {
             outcome: data.outcome ?? AuditOutcome.Failure,
         });
     }
+    /**
+     * Logs a critical event.
+     * Automatically sets severity to `Critical` and defaults outcome to `Failure`.
+     *
+     * @param action The name of the action being logged.
+     * @param data The payload containing details about the event.
+     */
     async critical(action, data) {
         await this.log(action, {
             ...data,

package/audit/drizzle/0000_tiny_the_captain.sql

@@ -0,0 +1,25 @@
+CREATE TYPE "audit"."actor_type" AS ENUM('user', 'system', 'api-key');--> statement-breakpoint
+CREATE TYPE "audit"."audit_outcome" AS ENUM('pending', 'success', 'cancelled', 'failure', 'denied');--> statement-breakpoint
+CREATE TYPE "audit"."audit_severity" AS ENUM('info', 'warn', 'error', 'critical');--> statement-breakpoint
+CREATE TABLE "audit"."event" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"timestamp" timestamp with time zone NOT NULL,
+	"tenant_id" uuid,
+	"correlation_id" uuid,
+	"module" text NOT NULL,
+	"action" text NOT NULL,
+	"outcome" "audit"."audit_outcome" NOT NULL,
+	"severity" "audit"."audit_severity" NOT NULL,
+	"actor_id" uuid NOT NULL,
+	"actor_type" "audit"."actor_type" NOT NULL,
+	"impersonator_id" uuid,
+	"impersonator_type" "audit"."actor_type",
+	"target_id" uuid NOT NULL,
+	"target_type" text NOT NULL,
+	"network_ip_address" text,
+	"network_user_agent" text,
+	"network_session_id" uuid,
+	"changes_before" jsonb,
+	"changes_after" jsonb,
+	"details" jsonb
+);