@geekmidas/audit 0.0.8 → 0.2.0

package/README.md

@@ -0,0 +1,397 @@
+# @geekmidas/audit
+
+> Type-safe audit logging with database integration for tracking application events and user actions
+
+## Overview
+
+`@geekmidas/audit` provides a comprehensive solution for recording and persisting audit trails in your application. It supports type-safe audit actions, transactional writes, and flexible storage backends.
+
+## Features
+
+- **Type-safe Audit Actions**: Define audit types with TypeScript for compile-time safety
+- **Transactional Support**: Flush audits atomically within database transactions
+- **Flexible Storage**: Pluggable storage interface (Kysely, in-memory, cache)
+- **Actor Tracking**: Record who performed each action (users, services, systems)
+- **Rich Metadata**: Attach request context, entity references, and custom data
+- **Query Support**: Query audit logs with filters, pagination, and sorting
+
+## Installation
+
+```bash
+npm install @geekmidas/audit
+# or
+pnpm add @geekmidas/audit
+```
+
+## Quick Start
+
+### 1. Define Your Audit Actions
+
+```typescript
+import type { AuditableAction } from '@geekmidas/audit';
+
+// Define type-safe audit actions
+type AppAuditAction =
+  | AuditableAction<'user.created', { userId: string; email: string }>
+  | AuditableAction<'user.updated', { userId: string; changes: string[] }>
+  | AuditableAction<'order.placed', { orderId: string; total: number }>;
+```
+
+### 2. Set Up Storage
+
+**For Development/Testing (InMemoryAuditStorage):**
+
+```typescript
+import { InMemoryAuditStorage } from '@geekmidas/audit/memory';
+
+const storage = new InMemoryAuditStorage<AppAuditAction>();
+
+// Query stored records
+const records = await storage.query({ type: 'user.created' });
+
+// Clear all records (useful in tests)
+storage.clear();
+```
+
+**For Production (KyselyAuditStorage):**
+
+```typescript
+import { KyselyAuditStorage } from '@geekmidas/audit/kysely';
+
+// Define your database schema
+interface Database {
+  audit_logs: AuditLogTable;
+  // ... other tables
+}
+
+const storage = new KyselyAuditStorage<Database>({
+  db: kyselyDb,
+  tableName: 'audit_logs',
+});
+```
+
+### 3. Create an Auditor
+
+```typescript
+import { DefaultAuditor } from '@geekmidas/audit';
+
+const auditor = new DefaultAuditor<AppAuditAction>({
+  actor: { id: 'user-123', type: 'user' },
+  storage,
+  metadata: {
+    requestId: 'req-456',
+    endpoint: '/api/users',
+  },
+});
+```
+
+### 4. Record Audits
+
+```typescript
+// Type-safe audit calls - TypeScript enforces correct payload shapes
+auditor.audit('user.created', {
+  userId: '789',
+  email: 'test@example.com',
+}); // OK
+
+auditor.audit('user.created', {
+  orderId: '123', // Type error - wrong payload shape
+});
+
+// Flush to storage
+await auditor.flush();
+```
+
+## Transactional Audits
+
+Use `withAuditableTransaction` to ensure audits are atomic with your database operations:
+
+```typescript
+import { withAuditableTransaction } from '@geekmidas/audit/kysely';
+
+const result = await withAuditableTransaction(
+  db,
+  auditor,
+  async (trx) => {
+    // Database operations
+    const user = await trx
+      .insertInto('users')
+      .values({ name: 'John', email: 'john@example.com' })
+      .returningAll()
+      .executeTakeFirstOrThrow();
+
+    // Audit is recorded
+    auditor.audit('user.created', {
+      userId: user.id,
+      email: user.email,
+    });
+
+    return user;
+  },
+);
+// Audits are automatically flushed before transaction commits
+// If flush fails, the entire transaction rolls back
+```
+
+## API Reference
+
+### Core Types
+
+#### `AuditableAction<TType, TPayload>`
+
+Defines an auditable action with a type and payload:
+
+```typescript
+type UserAction = AuditableAction<'user.created', { userId: string }>;
+```
+
+#### `AuditRecord`
+
+Complete audit record with all metadata:
+
+```typescript
+interface AuditRecord<TPayload = unknown> {
+  id: string;
+  type: string;
+  operation: AuditOperation;
+  table?: string;
+  entityId?: string | Record<string, unknown>;
+  oldValues?: Record<string, unknown>;
+  newValues?: Record<string, unknown>;
+  payload?: TPayload;
+  timestamp: Date;
+  actor?: AuditActor;
+  metadata?: AuditMetadata;
+}
+```
+
+#### `AuditActor`
+
+Represents who performed the action:
+
+```typescript
+interface AuditActor {
+  id?: string;
+  type?: string;
+  [key: string]: unknown;
+}
+```
+
+#### `AuditMetadata`
+
+Request context and additional data:
+
+```typescript
+interface AuditMetadata {
+  requestId?: string;
+  endpoint?: string;
+  method?: string;
+  ip?: string;
+  userAgent?: string;
+  [key: string]: unknown;
+}
+```
+
+### `Auditor` Interface
+
+```typescript
+interface Auditor<TAuditAction, TTransaction> {
+  readonly actor: AuditActor;
+
+  // Type-safe audit recording
+  audit<TType extends ExtractAuditType<TAuditAction>>(
+    type: TType,
+    payload: ExtractAuditPayload<TAuditAction, TType>,
+    options?: AuditOptions,
+  ): void;
+
+  // Raw record insertion
+  record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void;
+
+  // Get collected records
+  getRecords(): AuditRecord[];
+
+  // Flush to storage
+  flush(trx?: TTransaction): Promise<void>;
+
+  // Clear without flushing
+  clear(): void;
+
+  // Add metadata to future records
+  addMetadata(metadata: AuditMetadata): void;
+
+  // Transaction management
+  setTransaction(trx: TTransaction): void;
+  getTransaction(): TTransaction | undefined;
+}
+```
+
+### `AuditStorage` Interface
+
+Implement this interface for custom storage backends:
+
+```typescript
+interface AuditStorage<TAuditAction> {
+  // Required: Write records
+  write(records: AuditRecord[], trx?: unknown): Promise<void>;
+
+  // Optional: Query records
+  query?(options: AuditQueryOptions): Promise<AuditRecord[]>;
+
+  // Optional: Count records
+  count?(options: Omit<AuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
+
+  // Optional: Get database for transactions
+  getDatabase?(): unknown;
+}
+```
+
+### `KyselyAuditStorage`
+
+Built-in Kysely storage implementation:
+
+```typescript
+const storage = new KyselyAuditStorage({
+  db: kyselyDb,
+  tableName: 'audit_logs',
+  databaseServiceName: 'database', // Optional: for automatic transaction injection
+  autoId: false, // Optional: let database generate IDs
+});
+
+// Query audits
+const audits = await storage.query({
+  type: 'user.created',
+  actorId: 'user-123',
+  from: new Date('2024-01-01'),
+  limit: 100,
+  orderBy: 'timestamp',
+  orderDirection: 'desc',
+});
+
+// Count audits
+const count = await storage.count({
+  type: ['user.created', 'user.updated'],
+  actorId: 'user-123',
+});
+```
+
+### `InMemoryAuditStorage`
+
+Convenience wrapper around `CacheAuditStorage` with `InMemoryCache`. Useful for testing and development:
+
+```typescript
+import { InMemoryAuditStorage } from '@geekmidas/audit/memory';
+
+const storage = new InMemoryAuditStorage<AppAuditAction>();
+
+// Query audits (same API as other storages)
+const audits = await storage.query({
+  type: 'user.created',
+  limit: 10,
+});
+
+// Get all records (for assertions in tests)
+const allRecords = await storage.getRecords();
+
+// Clear all records (reset for next test)
+await storage.clear();
+```
+
+### `CacheAuditStorage`
+
+Cache-based storage using any `@geekmidas/cache` implementation:
+
+```typescript
+import { CacheAuditStorage } from '@geekmidas/audit/cache';
+import { InMemoryCache } from '@geekmidas/cache/memory';
+import { UpstashCache } from '@geekmidas/cache/upstash';
+
+// With in-memory cache (development/testing)
+const storage = new CacheAuditStorage({
+  cache: new InMemoryCache(),
+  ttl: 86400, // 24 hours
+});
+
+// With Upstash Redis (production - distributed systems)
+const storage = new CacheAuditStorage({
+  cache: new UpstashCache({
+    url: process.env.UPSTASH_REDIS_URL,
+    token: process.env.UPSTASH_REDIS_TOKEN,
+  }),
+  prefix: 'audit', // Optional key prefix
+  ttl: 604800, // 7 days
+});
+
+// Query and count work the same as other storages
+const audits = await storage.query({ type: 'user.created' });
+const count = await storage.count({ actorId: 'user-123' });
+
+// Clear all records
+await storage.clear();
+```
+
+## Database Schema
+
+Create an `audit_logs` table for `KyselyAuditStorage`:
+
+```sql
+CREATE TABLE audit_logs (
+  id VARCHAR(21) PRIMARY KEY,  -- or use gen_random_uuid() with autoId: true
+  type VARCHAR(255) NOT NULL,
+  operation VARCHAR(20) NOT NULL,
+  "table" VARCHAR(255),
+  "entityId" VARCHAR(255),
+  "oldValues" JSONB,
+  "newValues" JSONB,
+  payload JSONB,
+  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  "actorId" VARCHAR(255),
+  "actorType" VARCHAR(50),
+  "actorData" JSONB,
+  metadata JSONB
+);
+
+-- Recommended indexes
+CREATE INDEX idx_audit_logs_type ON audit_logs(type);
+CREATE INDEX idx_audit_logs_timestamp ON audit_logs(timestamp);
+CREATE INDEX idx_audit_logs_actor_id ON audit_logs("actorId");
+CREATE INDEX idx_audit_logs_entity_id ON audit_logs("entityId");
+```
+
+## Integration with @geekmidas/constructs
+
+The audit package integrates seamlessly with `@geekmidas/constructs` endpoints:
+
+```typescript
+import { e } from '@geekmidas/constructs/endpoints';
+
+const endpoint = e
+  .post('/users')
+  .body(UserSchema)
+  .output(UserResponseSchema)
+  .audit([
+    {
+      type: 'user.created',
+      payload: (response) => ({
+        userId: response.id,
+        email: response.email,
+      }),
+    },
+  ])
+  .handle(async ({ body, auditor }) => {
+    // Audits are automatically recorded and flushed
+    return { id: '123', ...body };
+  });
+```
+
+## Best Practices
+
+1. **Define all audit actions upfront**: Create a union type of all possible audit actions for your application
+2. **Use transactions**: Wrap database operations and audits in transactions for consistency
+3. **Include entity references**: Use `entityId` and `table` options for easier querying
+4. **Add request context**: Include request IDs, endpoints, and IPs in metadata
+5. **Use meaningful types**: Name audit types with domain context (e.g., `order.shipped` not `update`)
+
+## License
+
+MIT

package/dist/{Auditor-D3me-qKX.d.mts → Auditor-_Dn2dp8d.d.mts}

@@ -117,7 +117,50 @@ interface AuditStorage<TAuditAction extends AuditableAction<string, unknown> = A
    * ```
    */
   databaseServiceName?: string;
+  /**
+   * Optional: Execute a callback within a database transaction.
+   * The auditor is registered with the transaction and audits are flushed
+   * before the transaction commits.
+   *
+   * This is database-agnostic - each storage implementation provides its own
+   * transaction handling based on the underlying database.
+   *
+   * If a database connection is provided, it should be used instead of the
+   * storage's internal connection. If the connection is already a transaction,
+   * it should be reused instead of creating a nested transaction.
+   *
+   * @param auditor - The auditor to register with the transaction
+   * @param callback - The callback to execute within the transaction
+   * @param db - Optional database connection (may already be a transaction)
+   * @returns The result of the callback
+   *
+   * @example
+   * ```typescript
+   * // KyselyAuditStorage implementation
+   * async withTransaction<T>(auditor, callback, db) {
+   *   const connection = db ?? this.db;
+   *   if (connection.isTransaction) {
+   *     // Reuse existing transaction
+   *     auditor.setTransaction(connection);
+   *     const result = await callback();
+   *     await auditor.flush(connection);
+   *     return result;
+   *   }
+   *   return connection.transaction().execute(async (trx) => {
+   *     auditor.setTransaction(trx);
+   *     const result = await callback();
+   *     await auditor.flush(trx);
+   *     return result;
+   *   });
+   * }
+   * ```
+   */
+  withTransaction?<T>(auditor: {
+    setTransaction(trx: unknown): void;
+    flush(trx?: unknown): Promise<void>;
+  }, callback: () => Promise<T>, db?: unknown): Promise<T>;
 }
+//# sourceMappingURL=storage.d.ts.map
 //#endregion
 //#region src/types.d.ts
 /**
@@ -376,6 +419,8 @@ interface Auditor<TAuditAction extends AuditableAction<string, unknown> = Audita
    */
   getTransaction(): TTransaction | undefined;
 }
+//# sourceMappingURL=Auditor.d.ts.map
+
 //#endregion
 export { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditQueryOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, ExtractStorageAuditAction, MappedAudit };
-//# sourceMappingURL=Auditor-D3me-qKX.d.mts.map
+//# sourceMappingURL=Auditor-_Dn2dp8d.d.mts.map

package/dist/Auditor-_Dn2dp8d.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Auditor-_Dn2dp8d.d.mts","names":[],"sources":["../src/storage.ts","../src/types.ts","../src/Auditor.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/{Auditor-QYUMGJCH.d.cts → Auditor-sW7YAJIA.d.cts}

@@ -117,7 +117,50 @@ interface AuditStorage<TAuditAction extends AuditableAction<string, unknown> = A
    * ```
    */
   databaseServiceName?: string;
+  /**
+   * Optional: Execute a callback within a database transaction.
+   * The auditor is registered with the transaction and audits are flushed
+   * before the transaction commits.
+   *
+   * This is database-agnostic - each storage implementation provides its own
+   * transaction handling based on the underlying database.
+   *
+   * If a database connection is provided, it should be used instead of the
+   * storage's internal connection. If the connection is already a transaction,
+   * it should be reused instead of creating a nested transaction.
+   *
+   * @param auditor - The auditor to register with the transaction
+   * @param callback - The callback to execute within the transaction
+   * @param db - Optional database connection (may already be a transaction)
+   * @returns The result of the callback
+   *
+   * @example
+   * ```typescript
+   * // KyselyAuditStorage implementation
+   * async withTransaction<T>(auditor, callback, db) {
+   *   const connection = db ?? this.db;
+   *   if (connection.isTransaction) {
+   *     // Reuse existing transaction
+   *     auditor.setTransaction(connection);
+   *     const result = await callback();
+   *     await auditor.flush(connection);
+   *     return result;
+   *   }
+   *   return connection.transaction().execute(async (trx) => {
+   *     auditor.setTransaction(trx);
+   *     const result = await callback();
+   *     await auditor.flush(trx);
+   *     return result;
+   *   });
+   * }
+   * ```
+   */
+  withTransaction?<T>(auditor: {
+    setTransaction(trx: unknown): void;
+    flush(trx?: unknown): Promise<void>;
+  }, callback: () => Promise<T>, db?: unknown): Promise<T>;
 }
+//# sourceMappingURL=storage.d.ts.map
 //#endregion
 //#region src/types.d.ts
 /**
@@ -376,6 +419,8 @@ interface Auditor<TAuditAction extends AuditableAction<string, unknown> = Audita
    */
   getTransaction(): TTransaction | undefined;
 }
+//# sourceMappingURL=Auditor.d.ts.map
+
 //#endregion
 export { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditQueryOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, ExtractStorageAuditAction, MappedAudit };
-//# sourceMappingURL=Auditor-QYUMGJCH.d.cts.map
+//# sourceMappingURL=Auditor-sW7YAJIA.d.cts.map

package/dist/Auditor-sW7YAJIA.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Auditor-sW7YAJIA.d.cts","names":[],"sources":["../src/storage.ts","../src/types.ts","../src/Auditor.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/Auditor.d.cts

@@ -1,2 +1,2 @@
-import { Auditor } from "./Auditor-QYUMGJCH.cjs";
+import { Auditor } from "./Auditor-sW7YAJIA.cjs";
 export { Auditor };

package/dist/Auditor.d.mts

@@ -1,2 +1,2 @@
-import { Auditor } from "./Auditor-D3me-qKX.mjs";
+import { Auditor } from "./Auditor-_Dn2dp8d.mjs";
 export { Auditor };

package/dist/DefaultAuditor-BAVnNmRh.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultAuditor-BAVnNmRh.mjs","names":["config: DefaultAuditorConfig","type: TType","payload: ExtractAuditPayload<TAuditAction, TType>","options?: AuditOptions","record: AuditRecord","record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>","fullRecord: AuditRecord","trx?: TTransaction","trx: TTransaction","metadata: AuditMetadata"],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport type { Auditor } from './Auditor';\nimport type { AuditStorage } from './storage';\nimport type {\n  AuditActor,\n  AuditMetadata,\n  AuditOptions,\n  AuditRecord,\n  AuditableAction,\n  ExtractAuditPayload,\n  ExtractAuditType,\n} from './types';\n\n/**\n * Configuration for DefaultAuditor.\n */\nexport interface DefaultAuditorConfig {\n  /** The actor performing audits (set at construction, immutable) */\n  actor: AuditActor;\n  /** Storage backend for persisting audits */\n  storage: AuditStorage;\n  /** Optional metadata to attach to all audits */\n  metadata?: AuditMetadata;\n  /** Optional custom ID generator (defaults to nanoid) */\n  generateId?: () => string;\n}\n\n/**\n * Default implementation of the Auditor interface.\n * Collects audit records in memory and flushes to storage.\n *\n * @template TAuditAction - Union of all allowed audit action types\n * @template TTransaction - Transaction type (e.g., Kysely Transaction)\n *\n * @example\n * ```typescript\n * const auditor = new DefaultAuditor<AppAuditAction>({\n *   actor: { id: 'user-123', type: 'user' },\n *   storage: auditStorage,\n *   metadata: { requestId: 'req-456', endpoint: '/users' },\n * });\n *\n * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });\n *\n * // Flush inside transaction\n * await auditor.flush(trx);\n * ```\n */\nexport class DefaultAuditor<\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n  TTransaction = unknown,\n> implements Auditor<TAuditAction, TTransaction>\n{\n  readonly actor: AuditActor;\n  private readonly storage: AuditStorage;\n  private metadata?: AuditMetadata;\n  private readonly generateId: () => string;\n  private records: AuditRecord[] = [];\n  private transaction?: TTransaction;\n\n  constructor(config: DefaultAuditorConfig) {\n    this.actor = config.actor;\n    this.storage = config.storage;\n    this.metadata = config.metadata;\n    this.generateId = config.generateId ?? (() => nanoid());\n  }\n\n  audit<TType extends ExtractAuditType<TAuditAction>>(\n    type: TType,\n    payload: ExtractAuditPayload<TAuditAction, TType>,\n    options?: AuditOptions,\n  ): void {\n    const record: AuditRecord = {\n      id: this.generateId(),\n      type,\n      operation: options?.operation ?? 'CUSTOM',\n      table: options?.table,\n      entityId: options?.entityId,\n      oldValues: options?.oldValues,\n      newValues: options?.newValues,\n      payload,\n      timestamp: new Date(),\n      actor: this.actor,\n      metadata: this.metadata,\n    };\n\n    this.records.push(record);\n  }\n\n  record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {\n    const fullRecord: AuditRecord = {\n      ...record,\n      id: this.generateId(),\n      timestamp: new Date(),\n      actor: this.actor,\n      metadata: this.metadata\n        ? { ...this.metadata, ...record.metadata }\n        : record.metadata,\n    };\n\n    this.records.push(fullRecord);\n  }\n\n  getRecords(): AuditRecord[] {\n    return [...this.records];\n  }\n\n  async flush(trx?: TTransaction): Promise<void> {\n    if (this.records.length === 0) {\n      return;\n    }\n\n    const recordsToFlush = [...this.records];\n    this.records = [];\n\n    // Use explicitly passed transaction, or fall back to stored transaction\n    const transactionToUse = trx ?? this.transaction;\n    await this.storage.write(recordsToFlush, transactionToUse);\n  }\n\n  setTransaction(trx: TTransaction): void {\n    this.transaction = trx;\n  }\n\n  getTransaction(): TTransaction | undefined {\n    return this.transaction;\n  }\n\n  clear(): void {\n    this.records = [];\n  }\n\n  addMetadata(metadata: AuditMetadata): void {\n    this.metadata = this.metadata\n      ? { ...this.metadata, ...metadata }\n      : metadata;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,iBAAb,MAOA;CACE,AAAS;CACT,AAAiB;CACjB,AAAQ;CACR,AAAiB;CACjB,AAAQ,UAAyB,CAAE;CACnC,AAAQ;CAER,YAAYA,QAA8B;AACxC,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,WAAW,OAAO;AACvB,OAAK,aAAa,OAAO,eAAe,MAAM,QAAQ;CACvD;CAED,MACEC,MACAC,SACAC,SACM;EACN,MAAMC,SAAsB;GAC1B,IAAI,KAAK,YAAY;GACrB;GACA,WAAW,SAAS,aAAa;GACjC,OAAO,SAAS;GAChB,UAAU,SAAS;GACnB,WAAW,SAAS;GACpB,WAAW,SAAS;GACpB;GACA,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK;EAChB;AAED,OAAK,QAAQ,KAAK,OAAO;CAC1B;CAED,OAAOC,QAA+D;EACpE,MAAMC,aAA0B;GAC9B,GAAG;GACH,IAAI,KAAK,YAAY;GACrB,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK,WACX;IAAE,GAAG,KAAK;IAAU,GAAG,OAAO;GAAU,IACxC,OAAO;EACZ;AAED,OAAK,QAAQ,KAAK,WAAW;CAC9B;CAED,aAA4B;AAC1B,SAAO,CAAC,GAAG,KAAK,OAAQ;CACzB;CAED,MAAM,MAAMC,KAAmC;AAC7C,MAAI,KAAK,QAAQ,WAAW,EAC1B;EAGF,MAAM,iBAAiB,CAAC,GAAG,KAAK,OAAQ;AACxC,OAAK,UAAU,CAAE;EAGjB,MAAM,mBAAmB,OAAO,KAAK;AACrC,QAAM,KAAK,QAAQ,MAAM,gBAAgB,iBAAiB;CAC3D;CAED,eAAeC,KAAyB;AACtC,OAAK,cAAc;CACpB;CAED,iBAA2C;AACzC,SAAO,KAAK;CACb;CAED,QAAc;AACZ,OAAK,UAAU,CAAE;CAClB;CAED,YAAYC,UAA+B;AACzC,OAAK,WAAW,KAAK,WACjB;GAAE,GAAG,KAAK;GAAU,GAAG;EAAU,IACjC;CACL;AACF"}
+{"version":3,"file":"DefaultAuditor-BAVnNmRh.mjs","names":["config: DefaultAuditorConfig","type: TType","payload: ExtractAuditPayload<TAuditAction, TType>","options?: AuditOptions","record: AuditRecord","record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>","fullRecord: AuditRecord","trx?: TTransaction","trx: TTransaction","metadata: AuditMetadata"],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport type { Auditor } from './Auditor';\nimport type { AuditStorage } from './storage';\nimport type {\n\tAuditActor,\n\tAuditableAction,\n\tAuditMetadata,\n\tAuditOptions,\n\tAuditRecord,\n\tExtractAuditPayload,\n\tExtractAuditType,\n} from './types';\n\n/**\n * Configuration for DefaultAuditor.\n */\nexport interface DefaultAuditorConfig {\n\t/** The actor performing audits (set at construction, immutable) */\n\tactor: AuditActor;\n\t/** Storage backend for persisting audits */\n\tstorage: AuditStorage;\n\t/** Optional metadata to attach to all audits */\n\tmetadata?: AuditMetadata;\n\t/** Optional custom ID generator (defaults to nanoid) */\n\tgenerateId?: () => string;\n}\n\n/**\n * Default implementation of the Auditor interface.\n * Collects audit records in memory and flushes to storage.\n *\n * @template TAuditAction - Union of all allowed audit action types\n * @template TTransaction - Transaction type (e.g., Kysely Transaction)\n *\n * @example\n * ```typescript\n * const auditor = new DefaultAuditor<AppAuditAction>({\n *   actor: { id: 'user-123', type: 'user' },\n *   storage: auditStorage,\n *   metadata: { requestId: 'req-456', endpoint: '/users' },\n * });\n *\n * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });\n *\n * // Flush inside transaction\n * await auditor.flush(trx);\n * ```\n */\nexport class DefaultAuditor<\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n\tTTransaction = unknown,\n> implements Auditor<TAuditAction, TTransaction>\n{\n\treadonly actor: AuditActor;\n\tprivate readonly storage: AuditStorage;\n\tprivate metadata?: AuditMetadata;\n\tprivate readonly generateId: () => string;\n\tprivate records: AuditRecord[] = [];\n\tprivate transaction?: TTransaction;\n\n\tconstructor(config: DefaultAuditorConfig) {\n\t\tthis.actor = config.actor;\n\t\tthis.storage = config.storage;\n\t\tthis.metadata = config.metadata;\n\t\tthis.generateId = config.generateId ?? (() => nanoid());\n\t}\n\n\taudit<TType extends ExtractAuditType<TAuditAction>>(\n\t\ttype: TType,\n\t\tpayload: ExtractAuditPayload<TAuditAction, TType>,\n\t\toptions?: AuditOptions,\n\t): void {\n\t\tconst record: AuditRecord = {\n\t\t\tid: this.generateId(),\n\t\t\ttype,\n\t\t\toperation: options?.operation ?? 'CUSTOM',\n\t\t\ttable: options?.table,\n\t\t\tentityId: options?.entityId,\n\t\t\toldValues: options?.oldValues,\n\t\t\tnewValues: options?.newValues,\n\t\t\tpayload,\n\t\t\ttimestamp: new Date(),\n\t\t\tactor: this.actor,\n\t\t\tmetadata: this.metadata,\n\t\t};\n\n\t\tthis.records.push(record);\n\t}\n\n\trecord(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {\n\t\tconst fullRecord: AuditRecord = {\n\t\t\t...record,\n\t\t\tid: this.generateId(),\n\t\t\ttimestamp: new Date(),\n\t\t\tactor: this.actor,\n\t\t\tmetadata: this.metadata\n\t\t\t\t? { ...this.metadata, ...record.metadata }\n\t\t\t\t: record.metadata,\n\t\t};\n\n\t\tthis.records.push(fullRecord);\n\t}\n\n\tgetRecords(): AuditRecord[] {\n\t\treturn [...this.records];\n\t}\n\n\tasync flush(trx?: TTransaction): Promise<void> {\n\t\tif (this.records.length === 0) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst recordsToFlush = [...this.records];\n\t\tthis.records = [];\n\n\t\t// Use explicitly passed transaction, or fall back to stored transaction\n\t\tconst transactionToUse = trx ?? this.transaction;\n\t\tawait this.storage.write(recordsToFlush, transactionToUse);\n\t}\n\n\tsetTransaction(trx: TTransaction): void {\n\t\tthis.transaction = trx;\n\t}\n\n\tgetTransaction(): TTransaction | undefined {\n\t\treturn this.transaction;\n\t}\n\n\tclear(): void {\n\t\tthis.records = [];\n\t}\n\n\taddMetadata(metadata: AuditMetadata): void {\n\t\tthis.metadata = this.metadata\n\t\t\t? { ...this.metadata, ...metadata }\n\t\t\t: metadata;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,iBAAb,MAOA;CACC,AAAS;CACT,AAAiB;CACjB,AAAQ;CACR,AAAiB;CACjB,AAAQ,UAAyB,CAAE;CACnC,AAAQ;CAER,YAAYA,QAA8B;AACzC,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,WAAW,OAAO;AACvB,OAAK,aAAa,OAAO,eAAe,MAAM,QAAQ;CACtD;CAED,MACCC,MACAC,SACAC,SACO;EACP,MAAMC,SAAsB;GAC3B,IAAI,KAAK,YAAY;GACrB;GACA,WAAW,SAAS,aAAa;GACjC,OAAO,SAAS;GAChB,UAAU,SAAS;GACnB,WAAW,SAAS;GACpB,WAAW,SAAS;GACpB;GACA,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK;EACf;AAED,OAAK,QAAQ,KAAK,OAAO;CACzB;CAED,OAAOC,QAA+D;EACrE,MAAMC,aAA0B;GAC/B,GAAG;GACH,IAAI,KAAK,YAAY;GACrB,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK,WACZ;IAAE,GAAG,KAAK;IAAU,GAAG,OAAO;GAAU,IACxC,OAAO;EACV;AAED,OAAK,QAAQ,KAAK,WAAW;CAC7B;CAED,aAA4B;AAC3B,SAAO,CAAC,GAAG,KAAK,OAAQ;CACxB;CAED,MAAM,MAAMC,KAAmC;AAC9C,MAAI,KAAK,QAAQ,WAAW,EAC3B;EAGD,MAAM,iBAAiB,CAAC,GAAG,KAAK,OAAQ;AACxC,OAAK,UAAU,CAAE;EAGjB,MAAM,mBAAmB,OAAO,KAAK;AACrC,QAAM,KAAK,QAAQ,MAAM,gBAAgB,iBAAiB;CAC1D;CAED,eAAeC,KAAyB;AACvC,OAAK,cAAc;CACnB;CAED,iBAA2C;AAC1C,SAAO,KAAK;CACZ;CAED,QAAc;AACb,OAAK,UAAU,CAAE;CACjB;CAED,YAAYC,UAA+B;AAC1C,OAAK,WAAW,KAAK,WAClB;GAAE,GAAG,KAAK;GAAU,GAAG;EAAU,IACjC;CACH;AACD"}

package/dist/{DefaultAuditor-BTuMMiWh.d.cts → DefaultAuditor-BSYMwojG.d.cts}

@@ -1,4 +1,4 @@
-import { AuditActor, AuditMetadata, AuditOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType } from "./Auditor-QYUMGJCH.cjs";
+import { AuditActor, AuditMetadata, AuditOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType } from "./Auditor-sW7YAJIA.cjs";
 
 //#region src/DefaultAuditor.d.ts
 
@@ -53,6 +53,7 @@ declare class DefaultAuditor<TAuditAction extends AuditableAction<string, unknow
   clear(): void;
   addMetadata(metadata: AuditMetadata): void;
 }
+//# sourceMappingURL=DefaultAuditor.d.ts.map
 //#endregion
 export { DefaultAuditor, DefaultAuditorConfig };
-//# sourceMappingURL=DefaultAuditor-BTuMMiWh.d.cts.map
+//# sourceMappingURL=DefaultAuditor-BSYMwojG.d.cts.map

package/dist/DefaultAuditor-BSYMwojG.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultAuditor-BSYMwojG.d.cts","names":[],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":[],"mappings":";;;;AAgBA;;;AAIU,UAJO,oBAAA,CAIP;EAAY;EAEG,KAAA,EAJjB,UAIiB;EA0BZ;EAAc,OAAA,EA5BjB,YA4BiB;EAAA;EACU,QAAoB,CAAA,EA3B7C,aA2B6C;EAAe;EAKvC,UAAE,CAAA,EAAA,GAAA,GAAA,MAAA;;;;;;;;;;;;;;;;;;;AAAf;;;;cANP,oCACS,mCAAmC,qEAK5C,QAAQ,cAAc;kBAElB;;;;;;sBAOI;sBAOA,iBAAiB,qBAC9B,gBACG,oBAAoB,cAAc,kBACjC;iBAmBI,KAAK;gBAcN;cAII,eAAe;sBAab;oBAIF;;wBAQI"}

package/dist/{DefaultAuditor-C1FWrJg6.d.mts → DefaultAuditor-CYE-uAry.d.mts}

@@ -1,4 +1,4 @@
-import { AuditActor, AuditMetadata, AuditOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType } from "./Auditor-D3me-qKX.mjs";
+import { AuditActor, AuditMetadata, AuditOptions, AuditRecord, AuditStorage, AuditableAction, Auditor, ExtractAuditPayload, ExtractAuditType } from "./Auditor-_Dn2dp8d.mjs";
 
 //#region src/DefaultAuditor.d.ts
 
@@ -53,6 +53,7 @@ declare class DefaultAuditor<TAuditAction extends AuditableAction<string, unknow
   clear(): void;
   addMetadata(metadata: AuditMetadata): void;
 }
+//# sourceMappingURL=DefaultAuditor.d.ts.map
 //#endregion
 export { DefaultAuditor, DefaultAuditorConfig };
-//# sourceMappingURL=DefaultAuditor-C1FWrJg6.d.mts.map
+//# sourceMappingURL=DefaultAuditor-CYE-uAry.d.mts.map

package/dist/DefaultAuditor-CYE-uAry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultAuditor-CYE-uAry.d.mts","names":[],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":[],"mappings":";;;;AAgBA;;;AAIU,UAJO,oBAAA,CAIP;EAAY;EAEG,KAAA,EAJjB,UAIiB;EA0BZ;EAAc,OAAA,EA5BjB,YA4BiB;EAAA;EACU,QAAoB,CAAA,EA3B7C,aA2B6C;EAAe;EAKvC,UAAE,CAAA,EAAA,GAAA,GAAA,MAAA;;;;;;;;;;;;;;;;;;;AAAf;;;;cANP,oCACS,mCAAmC,qEAK5C,QAAQ,cAAc;kBAElB;;;;;;sBAOI;sBAOA,iBAAiB,qBAC9B,gBACG,oBAAoB,cAAc,kBACjC;iBAmBI,KAAK;gBAcN;cAII,eAAe;sBAab;oBAIF;;wBAQI"}

package/dist/DefaultAuditor-JbZ_BQfh.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultAuditor-JbZ_BQfh.cjs","names":["config: DefaultAuditorConfig","type: TType","payload: ExtractAuditPayload<TAuditAction, TType>","options?: AuditOptions","record: AuditRecord","record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>","fullRecord: AuditRecord","trx?: TTransaction","trx: TTransaction","metadata: AuditMetadata"],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport type { Auditor } from './Auditor';\nimport type { AuditStorage } from './storage';\nimport type {\n  AuditActor,\n  AuditMetadata,\n  AuditOptions,\n  AuditRecord,\n  AuditableAction,\n  ExtractAuditPayload,\n  ExtractAuditType,\n} from './types';\n\n/**\n * Configuration for DefaultAuditor.\n */\nexport interface DefaultAuditorConfig {\n  /** The actor performing audits (set at construction, immutable) */\n  actor: AuditActor;\n  /** Storage backend for persisting audits */\n  storage: AuditStorage;\n  /** Optional metadata to attach to all audits */\n  metadata?: AuditMetadata;\n  /** Optional custom ID generator (defaults to nanoid) */\n  generateId?: () => string;\n}\n\n/**\n * Default implementation of the Auditor interface.\n * Collects audit records in memory and flushes to storage.\n *\n * @template TAuditAction - Union of all allowed audit action types\n * @template TTransaction - Transaction type (e.g., Kysely Transaction)\n *\n * @example\n * ```typescript\n * const auditor = new DefaultAuditor<AppAuditAction>({\n *   actor: { id: 'user-123', type: 'user' },\n *   storage: auditStorage,\n *   metadata: { requestId: 'req-456', endpoint: '/users' },\n * });\n *\n * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });\n *\n * // Flush inside transaction\n * await auditor.flush(trx);\n * ```\n */\nexport class DefaultAuditor<\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n  TTransaction = unknown,\n> implements Auditor<TAuditAction, TTransaction>\n{\n  readonly actor: AuditActor;\n  private readonly storage: AuditStorage;\n  private metadata?: AuditMetadata;\n  private readonly generateId: () => string;\n  private records: AuditRecord[] = [];\n  private transaction?: TTransaction;\n\n  constructor(config: DefaultAuditorConfig) {\n    this.actor = config.actor;\n    this.storage = config.storage;\n    this.metadata = config.metadata;\n    this.generateId = config.generateId ?? (() => nanoid());\n  }\n\n  audit<TType extends ExtractAuditType<TAuditAction>>(\n    type: TType,\n    payload: ExtractAuditPayload<TAuditAction, TType>,\n    options?: AuditOptions,\n  ): void {\n    const record: AuditRecord = {\n      id: this.generateId(),\n      type,\n      operation: options?.operation ?? 'CUSTOM',\n      table: options?.table,\n      entityId: options?.entityId,\n      oldValues: options?.oldValues,\n      newValues: options?.newValues,\n      payload,\n      timestamp: new Date(),\n      actor: this.actor,\n      metadata: this.metadata,\n    };\n\n    this.records.push(record);\n  }\n\n  record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {\n    const fullRecord: AuditRecord = {\n      ...record,\n      id: this.generateId(),\n      timestamp: new Date(),\n      actor: this.actor,\n      metadata: this.metadata\n        ? { ...this.metadata, ...record.metadata }\n        : record.metadata,\n    };\n\n    this.records.push(fullRecord);\n  }\n\n  getRecords(): AuditRecord[] {\n    return [...this.records];\n  }\n\n  async flush(trx?: TTransaction): Promise<void> {\n    if (this.records.length === 0) {\n      return;\n    }\n\n    const recordsToFlush = [...this.records];\n    this.records = [];\n\n    // Use explicitly passed transaction, or fall back to stored transaction\n    const transactionToUse = trx ?? this.transaction;\n    await this.storage.write(recordsToFlush, transactionToUse);\n  }\n\n  setTransaction(trx: TTransaction): void {\n    this.transaction = trx;\n  }\n\n  getTransaction(): TTransaction | undefined {\n    return this.transaction;\n  }\n\n  clear(): void {\n    this.records = [];\n  }\n\n  addMetadata(metadata: AuditMetadata): void {\n    this.metadata = this.metadata\n      ? { ...this.metadata, ...metadata }\n      : metadata;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,iBAAb,MAOA;CACE,AAAS;CACT,AAAiB;CACjB,AAAQ;CACR,AAAiB;CACjB,AAAQ,UAAyB,CAAE;CACnC,AAAQ;CAER,YAAYA,QAA8B;AACxC,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,WAAW,OAAO;AACvB,OAAK,aAAa,OAAO,eAAe,MAAM,oBAAQ;CACvD;CAED,MACEC,MACAC,SACAC,SACM;EACN,MAAMC,SAAsB;GAC1B,IAAI,KAAK,YAAY;GACrB;GACA,WAAW,SAAS,aAAa;GACjC,OAAO,SAAS;GAChB,UAAU,SAAS;GACnB,WAAW,SAAS;GACpB,WAAW,SAAS;GACpB;GACA,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK;EAChB;AAED,OAAK,QAAQ,KAAK,OAAO;CAC1B;CAED,OAAOC,QAA+D;EACpE,MAAMC,aAA0B;GAC9B,GAAG;GACH,IAAI,KAAK,YAAY;GACrB,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK,WACX;IAAE,GAAG,KAAK;IAAU,GAAG,OAAO;GAAU,IACxC,OAAO;EACZ;AAED,OAAK,QAAQ,KAAK,WAAW;CAC9B;CAED,aAA4B;AAC1B,SAAO,CAAC,GAAG,KAAK,OAAQ;CACzB;CAED,MAAM,MAAMC,KAAmC;AAC7C,MAAI,KAAK,QAAQ,WAAW,EAC1B;EAGF,MAAM,iBAAiB,CAAC,GAAG,KAAK,OAAQ;AACxC,OAAK,UAAU,CAAE;EAGjB,MAAM,mBAAmB,OAAO,KAAK;AACrC,QAAM,KAAK,QAAQ,MAAM,gBAAgB,iBAAiB;CAC3D;CAED,eAAeC,KAAyB;AACtC,OAAK,cAAc;CACpB;CAED,iBAA2C;AACzC,SAAO,KAAK;CACb;CAED,QAAc;AACZ,OAAK,UAAU,CAAE;CAClB;CAED,YAAYC,UAA+B;AACzC,OAAK,WAAW,KAAK,WACjB;GAAE,GAAG,KAAK;GAAU,GAAG;EAAU,IACjC;CACL;AACF"}
+{"version":3,"file":"DefaultAuditor-JbZ_BQfh.cjs","names":["config: DefaultAuditorConfig","type: TType","payload: ExtractAuditPayload<TAuditAction, TType>","options?: AuditOptions","record: AuditRecord","record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>","fullRecord: AuditRecord","trx?: TTransaction","trx: TTransaction","metadata: AuditMetadata"],"sources":["../src/DefaultAuditor.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport type { Auditor } from './Auditor';\nimport type { AuditStorage } from './storage';\nimport type {\n\tAuditActor,\n\tAuditableAction,\n\tAuditMetadata,\n\tAuditOptions,\n\tAuditRecord,\n\tExtractAuditPayload,\n\tExtractAuditType,\n} from './types';\n\n/**\n * Configuration for DefaultAuditor.\n */\nexport interface DefaultAuditorConfig {\n\t/** The actor performing audits (set at construction, immutable) */\n\tactor: AuditActor;\n\t/** Storage backend for persisting audits */\n\tstorage: AuditStorage;\n\t/** Optional metadata to attach to all audits */\n\tmetadata?: AuditMetadata;\n\t/** Optional custom ID generator (defaults to nanoid) */\n\tgenerateId?: () => string;\n}\n\n/**\n * Default implementation of the Auditor interface.\n * Collects audit records in memory and flushes to storage.\n *\n * @template TAuditAction - Union of all allowed audit action types\n * @template TTransaction - Transaction type (e.g., Kysely Transaction)\n *\n * @example\n * ```typescript\n * const auditor = new DefaultAuditor<AppAuditAction>({\n *   actor: { id: 'user-123', type: 'user' },\n *   storage: auditStorage,\n *   metadata: { requestId: 'req-456', endpoint: '/users' },\n * });\n *\n * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });\n *\n * // Flush inside transaction\n * await auditor.flush(trx);\n * ```\n */\nexport class DefaultAuditor<\n\tTAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n\t\tstring,\n\t\tunknown\n\t>,\n\tTTransaction = unknown,\n> implements Auditor<TAuditAction, TTransaction>\n{\n\treadonly actor: AuditActor;\n\tprivate readonly storage: AuditStorage;\n\tprivate metadata?: AuditMetadata;\n\tprivate readonly generateId: () => string;\n\tprivate records: AuditRecord[] = [];\n\tprivate transaction?: TTransaction;\n\n\tconstructor(config: DefaultAuditorConfig) {\n\t\tthis.actor = config.actor;\n\t\tthis.storage = config.storage;\n\t\tthis.metadata = config.metadata;\n\t\tthis.generateId = config.generateId ?? (() => nanoid());\n\t}\n\n\taudit<TType extends ExtractAuditType<TAuditAction>>(\n\t\ttype: TType,\n\t\tpayload: ExtractAuditPayload<TAuditAction, TType>,\n\t\toptions?: AuditOptions,\n\t): void {\n\t\tconst record: AuditRecord = {\n\t\t\tid: this.generateId(),\n\t\t\ttype,\n\t\t\toperation: options?.operation ?? 'CUSTOM',\n\t\t\ttable: options?.table,\n\t\t\tentityId: options?.entityId,\n\t\t\toldValues: options?.oldValues,\n\t\t\tnewValues: options?.newValues,\n\t\t\tpayload,\n\t\t\ttimestamp: new Date(),\n\t\t\tactor: this.actor,\n\t\t\tmetadata: this.metadata,\n\t\t};\n\n\t\tthis.records.push(record);\n\t}\n\n\trecord(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {\n\t\tconst fullRecord: AuditRecord = {\n\t\t\t...record,\n\t\t\tid: this.generateId(),\n\t\t\ttimestamp: new Date(),\n\t\t\tactor: this.actor,\n\t\t\tmetadata: this.metadata\n\t\t\t\t? { ...this.metadata, ...record.metadata }\n\t\t\t\t: record.metadata,\n\t\t};\n\n\t\tthis.records.push(fullRecord);\n\t}\n\n\tgetRecords(): AuditRecord[] {\n\t\treturn [...this.records];\n\t}\n\n\tasync flush(trx?: TTransaction): Promise<void> {\n\t\tif (this.records.length === 0) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst recordsToFlush = [...this.records];\n\t\tthis.records = [];\n\n\t\t// Use explicitly passed transaction, or fall back to stored transaction\n\t\tconst transactionToUse = trx ?? this.transaction;\n\t\tawait this.storage.write(recordsToFlush, transactionToUse);\n\t}\n\n\tsetTransaction(trx: TTransaction): void {\n\t\tthis.transaction = trx;\n\t}\n\n\tgetTransaction(): TTransaction | undefined {\n\t\treturn this.transaction;\n\t}\n\n\tclear(): void {\n\t\tthis.records = [];\n\t}\n\n\taddMetadata(metadata: AuditMetadata): void {\n\t\tthis.metadata = this.metadata\n\t\t\t? { ...this.metadata, ...metadata }\n\t\t\t: metadata;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,iBAAb,MAOA;CACC,AAAS;CACT,AAAiB;CACjB,AAAQ;CACR,AAAiB;CACjB,AAAQ,UAAyB,CAAE;CACnC,AAAQ;CAER,YAAYA,QAA8B;AACzC,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,WAAW,OAAO;AACvB,OAAK,aAAa,OAAO,eAAe,MAAM,oBAAQ;CACtD;CAED,MACCC,MACAC,SACAC,SACO;EACP,MAAMC,SAAsB;GAC3B,IAAI,KAAK,YAAY;GACrB;GACA,WAAW,SAAS,aAAa;GACjC,OAAO,SAAS;GAChB,UAAU,SAAS;GACnB,WAAW,SAAS;GACpB,WAAW,SAAS;GACpB;GACA,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK;EACf;AAED,OAAK,QAAQ,KAAK,OAAO;CACzB;CAED,OAAOC,QAA+D;EACrE,MAAMC,aAA0B;GAC/B,GAAG;GACH,IAAI,KAAK,YAAY;GACrB,2BAAW,IAAI;GACf,OAAO,KAAK;GACZ,UAAU,KAAK,WACZ;IAAE,GAAG,KAAK;IAAU,GAAG,OAAO;GAAU,IACxC,OAAO;EACV;AAED,OAAK,QAAQ,KAAK,WAAW;CAC7B;CAED,aAA4B;AAC3B,SAAO,CAAC,GAAG,KAAK,OAAQ;CACxB;CAED,MAAM,MAAMC,KAAmC;AAC9C,MAAI,KAAK,QAAQ,WAAW,EAC3B;EAGD,MAAM,iBAAiB,CAAC,GAAG,KAAK,OAAQ;AACxC,OAAK,UAAU,CAAE;EAGjB,MAAM,mBAAmB,OAAO,KAAK;AACrC,QAAM,KAAK,QAAQ,MAAM,gBAAgB,iBAAiB;CAC1D;CAED,eAAeC,KAAyB;AACvC,OAAK,cAAc;CACnB;CAED,iBAA2C;AAC1C,SAAO,KAAK;CACZ;CAED,QAAc;AACb,OAAK,UAAU,CAAE;CACjB;CAED,YAAYC,UAA+B;AAC1C,OAAK,WAAW,KAAK,WAClB;GAAE,GAAG,KAAK;GAAU,GAAG;EAAU,IACjC;CACH;AACD"}

package/dist/DefaultAuditor.d.cts

@@ -1,3 +1,3 @@
-import "./Auditor-QYUMGJCH.cjs";
-import { DefaultAuditor, DefaultAuditorConfig } from "./DefaultAuditor-BTuMMiWh.cjs";
+import "./Auditor-sW7YAJIA.cjs";
+import { DefaultAuditor, DefaultAuditorConfig } from "./DefaultAuditor-BSYMwojG.cjs";
 export { DefaultAuditor, DefaultAuditorConfig };