@geekmidas/audit 0.0.1

package/src/Auditor.ts

@@ -0,0 +1,157 @@
+import type {
+  AuditableAction,
+  AuditActor,
+  AuditMetadata,
+  AuditOptions,
+  AuditRecord,
+  ExtractAuditPayload,
+  ExtractAuditType,
+} from './types';
+
+/**
+ * Interface for audit collection and flushing.
+ * Generic over audit action types for full type safety.
+ *
+ * @template TAuditAction - Union of all allowed audit action types
+ * @template TTransaction - Transaction type (e.g., Kysely Transaction)
+ *
+ * @example
+ * ```typescript
+ * type AppAuditAction =
+ *   | AuditableAction<'user.created', { userId: string; email: string }>
+ *   | AuditableAction<'user.updated', { userId: string; changes: string[] }>;
+ *
+ * // In endpoint handler
+ * const auditor: Auditor<AppAuditAction> = ...;
+ *
+ * // Type-safe audit calls
+ * auditor.audit('user.created', { userId: '123', email: 'test@example.com' }); // ✅
+ * auditor.audit('user.created', { orderId: '123' }); // ❌ Type error
+ * auditor.audit('unknown.type', {}); // ❌ Type error
+ * ```
+ */
+export interface Auditor<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TTransaction = unknown,
+> {
+  /**
+   * The actor for all audits in this context.
+   * Set at construction time, immutable throughout the request.
+   */
+  readonly actor: AuditActor;
+
+  /**
+   * Record a type-safe audit entry.
+   * The payload type is inferred from the audit type.
+   *
+   * @param type - The audit type (must be a valid type from TAuditAction)
+   * @param payload - The audit payload (shape enforced by type)
+   * @param options - Optional audit metadata
+   *
+   * @example
+   * ```typescript
+   * auditor.audit('user.created', {
+   *   userId: '123',
+   *   email: 'test@example.com',
+   * });
+   *
+   * auditor.audit('order.placed', {
+   *   orderId: 'order-456',
+   *   total: 99.99,
+   * }, {
+   *   entityId: 'order-456',
+   *   table: 'orders',
+   * });
+   * ```
+   */
+  audit<TType extends ExtractAuditType<TAuditAction>>(
+    type: TType,
+    payload: ExtractAuditPayload<TAuditAction, TType>,
+    options?: AuditOptions,
+  ): void;
+
+  /**
+   * Record a raw audit record.
+   * Use this when you need full control over the audit structure,
+   * bypassing type safety.
+   *
+   * @param record - The audit record (id, timestamp, actor added automatically)
+   */
+  record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void;
+
+  /**
+   * Get all collected audit records.
+   * Useful for inspection or custom processing.
+   */
+  getRecords(): AuditRecord[];
+
+  /**
+   * Flush all collected audits to storage.
+   * Called automatically by the endpoint adaptor inside the transaction.
+   *
+   * @param trx - Optional transaction context for atomic writes
+   */
+  flush(trx?: TTransaction): Promise<void>;
+
+  /**
+   * Clear all collected audit records without flushing.
+   * Use with caution - collected audits will be lost.
+   */
+  clear(): void;
+
+  /**
+   * Add metadata to all future audit records.
+   * Merges with existing metadata (new values override existing).
+   * Typically called by adaptors to add request context.
+   *
+   * @param metadata - Metadata to add (requestId, endpoint, method, ip, etc.)
+   *
+   * @example
+   * ```typescript
+   * // In endpoint adaptor
+   * auditor.addMetadata({
+   *   requestId: 'req-123',
+   *   endpoint: '/users',
+   *   method: 'POST',
+   *   ip: '192.168.1.1',
+   * });
+   * ```
+   */
+  addMetadata(metadata: AuditMetadata): void;
+
+  /**
+   * Set the transaction context for audit flushing.
+   * When set, flush() will use this transaction instead of requiring
+   * it to be passed explicitly. This enables declarative audits to
+   * participate in the same transaction as the handler's database operations.
+   *
+   * @param trx - The transaction context (e.g., Kysely Transaction)
+   *
+   * @example
+   * ```typescript
+   * // In handler with explicit transaction management
+   * const result = await withTransaction(services.database.raw, async (trx) => {
+   *   // Register transaction with auditor so declarative audits use it
+   *   auditor.setTransaction(trx);
+   *
+   *   const user = await trx.insertInto('users').values(data).returningAll().executeTakeFirstOrThrow();
+   *
+   *   // Manual audits will also use this transaction when flush() is called
+   *   auditor.audit('user.created', { userId: user.id });
+   *
+   *   return user;
+   * });
+   * // After handler, adaptor calls auditor.flush() which uses the stored transaction
+   * ```
+   */
+  setTransaction(trx: TTransaction): void;
+
+  /**
+   * Get the currently set transaction context.
+   * Returns undefined if no transaction has been set.
+   */
+  getTransaction(): TTransaction | undefined;
+}

package/src/DefaultAuditor.ts

@@ -0,0 +1,141 @@
+import { nanoid } from 'nanoid';
+import type { Auditor } from './Auditor';
+import type { AuditStorage } from './storage';
+import type {
+  AuditableAction,
+  AuditActor,
+  AuditMetadata,
+  AuditOptions,
+  AuditRecord,
+  ExtractAuditPayload,
+  ExtractAuditType,
+} from './types';
+
+/**
+ * Configuration for DefaultAuditor.
+ */
+export interface DefaultAuditorConfig {
+  /** The actor performing audits (set at construction, immutable) */
+  actor: AuditActor;
+  /** Storage backend for persisting audits */
+  storage: AuditStorage;
+  /** Optional metadata to attach to all audits */
+  metadata?: AuditMetadata;
+  /** Optional custom ID generator (defaults to nanoid) */
+  generateId?: () => string;
+}
+
+/**
+ * Default implementation of the Auditor interface.
+ * Collects audit records in memory and flushes to storage.
+ *
+ * @template TAuditAction - Union of all allowed audit action types
+ * @template TTransaction - Transaction type (e.g., Kysely Transaction)
+ *
+ * @example
+ * ```typescript
+ * const auditor = new DefaultAuditor<AppAuditAction>({
+ *   actor: { id: 'user-123', type: 'user' },
+ *   storage: auditStorage,
+ *   metadata: { requestId: 'req-456', endpoint: '/users' },
+ * });
+ *
+ * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });
+ *
+ * // Flush inside transaction
+ * await auditor.flush(trx);
+ * ```
+ */
+export class DefaultAuditor<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TTransaction = unknown,
+> implements Auditor<TAuditAction, TTransaction>
+{
+  readonly actor: AuditActor;
+  private readonly storage: AuditStorage;
+  private metadata?: AuditMetadata;
+  private readonly generateId: () => string;
+  private records: AuditRecord[] = [];
+  private transaction?: TTransaction;
+
+  constructor(config: DefaultAuditorConfig) {
+    this.actor = config.actor;
+    this.storage = config.storage;
+    this.metadata = config.metadata;
+    this.generateId = config.generateId ?? (() => nanoid());
+  }
+
+  audit<TType extends ExtractAuditType<TAuditAction>>(
+    type: TType,
+    payload: ExtractAuditPayload<TAuditAction, TType>,
+    options?: AuditOptions,
+  ): void {
+    const record: AuditRecord = {
+      id: this.generateId(),
+      type,
+      operation: options?.operation ?? 'CUSTOM',
+      table: options?.table,
+      entityId: options?.entityId,
+      oldValues: options?.oldValues,
+      newValues: options?.newValues,
+      payload,
+      timestamp: new Date(),
+      actor: this.actor,
+      metadata: this.metadata,
+    };
+
+    this.records.push(record);
+  }
+
+  record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {
+    const fullRecord: AuditRecord = {
+      ...record,
+      id: this.generateId(),
+      timestamp: new Date(),
+      actor: this.actor,
+      metadata: this.metadata
+        ? { ...this.metadata, ...record.metadata }
+        : record.metadata,
+    };
+
+    this.records.push(fullRecord);
+  }
+
+  getRecords(): AuditRecord[] {
+    return [...this.records];
+  }
+
+  async flush(trx?: TTransaction): Promise<void> {
+    if (this.records.length === 0) {
+      return;
+    }
+
+    const recordsToFlush = [...this.records];
+    this.records = [];
+
+    // Use explicitly passed transaction, or fall back to stored transaction
+    const transactionToUse = trx ?? this.transaction;
+    await this.storage.write(recordsToFlush, transactionToUse);
+  }
+
+  setTransaction(trx: TTransaction): void {
+    this.transaction = trx;
+  }
+
+  getTransaction(): TTransaction | undefined {
+    return this.transaction;
+  }
+
+  clear(): void {
+    this.records = [];
+  }
+
+  addMetadata(metadata: AuditMetadata): void {
+    this.metadata = this.metadata
+      ? { ...this.metadata, ...metadata }
+      : metadata;
+  }
+}