@geekmidas/audit 0.0.1

package/src/kysely.ts

@@ -0,0 +1,391 @@
+import type {
+  ControlledTransaction,
+  IsolationLevel,
+  Kysely,
+  Transaction,
+} from 'kysely';
+import type { AuditQueryOptions, AuditStorage } from './storage';
+import type { AuditRecord } from './types';
+
+/**
+ * Minimal interface for transaction-aware audit flushing.
+ * Use this when you need to flush audits within a database transaction.
+ *
+ * @template TTransaction - Transaction type (e.g., Kysely Transaction)
+ *
+ * @example
+ * ```typescript
+ * import { withAuditableTransaction } from '@geekmidas/audit/kysely';
+ * import type { TransactionAwareAuditor } from '@geekmidas/audit/kysely';
+ *
+ * const result = await withAuditableTransaction(
+ *   db,
+ *   auditor as TransactionAwareAuditor<Transaction<DB>>,
+ *   async (trx) => {
+ *     // Your transactional operations
+ *     return result;
+ *   },
+ * );
+ * ```
+ */
+export interface TransactionAwareAuditor<TTransaction = unknown> {
+  /** Register the transaction with the auditor for use during flush */
+  setTransaction(trx: TTransaction): void;
+  /** Flush all pending audits, optionally within a transaction */
+  flush(trx?: TTransaction): Promise<void>;
+}
+
+export interface TransactionSettings {
+  isolationLevel?: IsolationLevel;
+}
+
+export type DatabaseConnection<T> =
+  | ControlledTransaction<T>
+  | Kysely<T>
+  | Transaction<T>;
+
+/**
+ * Execute a callback within a database transaction with automatic audit handling.
+ *
+ * This wrapper ensures that:
+ * 1. The transaction is automatically registered with the auditor
+ * 2. Manual audits (via `auditor.audit()`) are flushed BEFORE the transaction commits
+ * 3. If audit flush fails, the entire transaction rolls back
+ * 4. If the callback fails, audits are NOT written (atomic consistency)
+ *
+ * **Note:** Declarative audits (defined via `.audit([...])` on the endpoint builder)
+ * are processed AFTER the handler returns, so they run outside this transaction.
+ * If you need all audits to be atomic with your database operations, use manual
+ * audits via `auditor.audit()` inside this wrapper.
+ *
+ * @param db - Database connection (Kysely, Transaction, or ControlledTransaction)
+ * @param auditor - Auditor instance that will receive the transaction
+ * @param cb - Callback to execute within the transaction
+ * @param settings - Optional transaction settings (isolation level)
+ * @returns The result of the callback
+ *
+ * @example
+ * ```typescript
+ * import { withAuditableTransaction } from '@geekmidas/audit/kysely';
+ *
+ * const result = await withAuditableTransaction(
+ *   services.database,
+ *   auditor,
+ *   async (trx) => {
+ *     const user = await trx
+ *       .insertInto('users')
+ *       .values(data)
+ *       .returningAll()
+ *       .executeTakeFirstOrThrow();
+ *
+ *     // Manual audits are atomic with the transaction
+ *     auditor.audit('user.created', { userId: user.id, email: user.email });
+ *
+ *     return user;
+ *   },
+ * );
+ * // Audits are automatically flushed inside the transaction before commit
+ * ```
+ */
+export async function withAuditableTransaction<DB, T>(
+  db: DatabaseConnection<DB>,
+  auditor: TransactionAwareAuditor<Transaction<DB>>,
+  cb: (trx: Transaction<DB>) => Promise<T>,
+  settings?: TransactionSettings,
+): Promise<T> {
+  const execute = async (trx: Transaction<DB>): Promise<T> => {
+    // Register transaction with auditor
+    auditor.setTransaction(trx);
+
+    // Execute the callback
+    const result = await cb(trx);
+
+    // Flush audits BEFORE transaction commits
+    // If this fails, the transaction will roll back
+    await auditor.flush(trx);
+
+    return result;
+  };
+
+  // If already in a transaction, just run with it
+  if (db.isTransaction) {
+    return execute(db as Transaction<DB>);
+  }
+
+  const builder = db.transaction();
+
+  if (settings?.isolationLevel) {
+    return builder.setIsolationLevel(settings.isolationLevel).execute(execute);
+  }
+
+  return builder.execute(execute);
+}
+
+/**
+ * Database table interface for audit records.
+ * Use this to define your audit_logs table in your Kysely database schema.
+ *
+ * @example
+ * ```typescript
+ * interface Database {
+ *   audit_logs: AuditLogTable;
+ *   // ... other tables
+ * }
+ * ```
+ */
+export interface AuditLogTable {
+  id: string;
+  type: string;
+  operation: string;
+  table: string | null;
+  entityId: string | null;
+  oldValues: string | null;
+  newValues: string | null;
+  payload: string | null;
+  timestamp: Date;
+  actorId: string | null;
+  actorType: string | null;
+  actorData: string | null;
+  metadata: string | null;
+}
+
+/**
+ * Configuration for KyselyAuditStorage.
+ */
+export interface KyselyAuditStorageConfig<DB> {
+  /** Kysely database instance */
+  db: Kysely<DB>;
+  /** Table name for audit logs (must be a key in DB that extends AuditLogTable) */
+  tableName: keyof DB & string;
+}
+
+/**
+ * Kysely-based audit storage implementation.
+ * Stores audit records in a database table using Kysely.
+ *
+ * @template DB - Your Kysely database schema
+ *
+ * @example
+ * ```typescript
+ * interface Database {
+ *   audit_logs: AuditLogTable;
+ * }
+ *
+ * const storage = new KyselyAuditStorage({
+ *   db: kyselyDb,
+ *   tableName: 'audit_logs',
+ * });
+ *
+ * const auditor = new DefaultAuditor({
+ *   actor: { id: 'user-123', type: 'user' },
+ *   storage,
+ * });
+ * ```
+ */
+export class KyselyAuditStorage<DB> implements AuditStorage {
+  private readonly db: Kysely<DB>;
+  private readonly tableName: keyof DB & string;
+
+  constructor(config: KyselyAuditStorageConfig<DB>) {
+    this.db = config.db;
+    this.tableName = config.tableName;
+  }
+
+  async write(records: AuditRecord[], trx?: unknown): Promise<void> {
+    if (records.length === 0) {
+      return;
+    }
+
+    const db = (trx as Transaction<DB>) ?? this.db;
+    const rows = records.map((record) => this.toRow(record));
+
+    await (db as any)
+      .insertInto(this.tableName)
+      .values(rows)
+      .execute();
+  }
+
+  async query(options: AuditQueryOptions): Promise<AuditRecord[]> {
+    let query = (this.db as any)
+      .selectFrom(this.tableName)
+      .selectAll();
+
+    query = this.applyFilters(query, options);
+
+    // Ordering
+    const orderBy = options.orderBy ?? 'timestamp';
+    const orderDirection = options.orderDirection ?? 'desc';
+    query = query.orderBy(
+      orderBy === 'timestamp' ? 'timestamp' : 'type',
+      orderDirection,
+    );
+
+    // Pagination
+    if (options.limit !== undefined) {
+      query = query.limit(options.limit);
+    }
+    if (options.offset !== undefined) {
+      query = query.offset(options.offset);
+    }
+
+    const rows = await query.execute();
+    return rows.map((row: AuditLogTable) => this.fromRow(row));
+  }
+
+  async count(
+    options: Omit<AuditQueryOptions, 'limit' | 'offset'>,
+  ): Promise<number> {
+    let query = (this.db as any)
+      .selectFrom(this.tableName)
+      .select((eb: any) => eb.fn.count('id').as('count'));
+
+    query = this.applyFilters(query, options);
+
+    const result = await query.executeTakeFirst();
+    return Number(result?.count ?? 0);
+  }
+
+  /**
+   * Get the Kysely database instance for transactional operations.
+   * Used by endpoint adaptors to automatically wrap handlers in transactions.
+   */
+  getDatabase(): Kysely<DB> {
+    return this.db;
+  }
+
+  private applyFilters(query: any, options: AuditQueryOptions): any {
+    // Type filter
+    if (options.type !== undefined) {
+      if (Array.isArray(options.type)) {
+        query = query.where('type', 'in', options.type);
+      } else {
+        query = query.where('type', '=', options.type);
+      }
+    }
+
+    // Entity ID filter
+    if (options.entityId !== undefined) {
+      const entityId =
+        typeof options.entityId === 'string'
+          ? options.entityId
+          : JSON.stringify(options.entityId);
+      query = query.where('entityId', '=', entityId);
+    }
+
+    // Table filter
+    if (options.table !== undefined) {
+      query = query.where('table', '=', options.table);
+    }
+
+    // Actor ID filter
+    if (options.actorId !== undefined) {
+      query = query.where('actorId', '=', options.actorId);
+    }
+
+    // Date range filters
+    if (options.from !== undefined) {
+      query = query.where('timestamp', '>=', options.from);
+    }
+    if (options.to !== undefined) {
+      query = query.where('timestamp', '<=', options.to);
+    }
+
+    return query;
+  }
+
+  private toRow(record: AuditRecord): AuditLogTable {
+    return {
+      id: record.id,
+      type: record.type,
+      operation: record.operation,
+      table: record.table ?? null,
+      entityId:
+        record.entityId === undefined
+          ? null
+          : typeof record.entityId === 'string'
+            ? record.entityId
+            : JSON.stringify(record.entityId),
+      oldValues:
+        record.oldValues !== undefined
+          ? JSON.stringify(record.oldValues)
+          : null,
+      newValues:
+        record.newValues !== undefined
+          ? JSON.stringify(record.newValues)
+          : null,
+      payload:
+        record.payload !== undefined ? JSON.stringify(record.payload) : null,
+      timestamp: record.timestamp,
+      actorId: record.actor?.id ?? null,
+      actorType: record.actor?.type ?? null,
+      actorData:
+        record.actor !== undefined
+          ? JSON.stringify(this.getActorData(record.actor))
+          : null,
+      metadata:
+        record.metadata !== undefined ? JSON.stringify(record.metadata) : null,
+    };
+  }
+
+  private fromRow(row: AuditLogTable): AuditRecord {
+    const actor =
+      row.actorId !== null || row.actorType !== null
+        ? {
+            id: row.actorId ?? undefined,
+            type: row.actorType ?? undefined,
+            ...(row.actorData ? this.parseJson(row.actorData) : {}),
+          }
+        : undefined;
+
+    return {
+      id: row.id,
+      type: row.type,
+      operation: row.operation as AuditRecord['operation'],
+      table: row.table ?? undefined,
+      entityId: row.entityId
+        ? this.parseEntityId(row.entityId)
+        : undefined,
+      oldValues: row.oldValues
+        ? this.parseJson(row.oldValues)
+        : undefined,
+      newValues: row.newValues
+        ? this.parseJson(row.newValues)
+        : undefined,
+      payload: row.payload ? this.parseJson(row.payload) : undefined,
+      timestamp: row.timestamp,
+      actor,
+      metadata: row.metadata ? this.parseJson(row.metadata) : undefined,
+    };
+  }
+
+  /**
+   * Parse a JSON value that may already be parsed (e.g., from jsonb columns).
+   */
+  private parseJson(value: string | object): Record<string, unknown> {
+    if (typeof value === 'object') {
+      return value as Record<string, unknown>;
+    }
+    return JSON.parse(value);
+  }
+
+  private getActorData(
+    actor: NonNullable<AuditRecord['actor']>,
+  ): Record<string, unknown> {
+    const { id, type, ...rest } = actor;
+    return rest;
+  }
+
+  private parseEntityId(
+    entityId: string,
+  ): string | Record<string, unknown> {
+    try {
+      const parsed = JSON.parse(entityId);
+      if (typeof parsed === 'object' && parsed !== null) {
+        return parsed;
+      }
+      return entityId;
+    } catch {
+      return entityId;
+    }
+  }
+}

package/src/storage.ts

@@ -0,0 +1,101 @@
+import type { AuditRecord } from './types';
+
+/**
+ * Options for querying audit records.
+ */
+export interface AuditQueryOptions {
+  /** Filter by audit type */
+  type?: string | string[];
+  /** Filter by entity ID */
+  entityId?: string | Record<string, unknown>;
+  /** Filter by table name */
+  table?: string;
+  /** Filter by actor ID */
+  actorId?: string;
+  /** Filter by date range (start) */
+  from?: Date;
+  /** Filter by date range (end) */
+  to?: Date;
+  /** Limit number of results */
+  limit?: number;
+  /** Offset for pagination */
+  offset?: number;
+  /** Sort order */
+  orderBy?: 'timestamp' | 'type';
+  /** Sort direction */
+  orderDirection?: 'asc' | 'desc';
+}
+
+/**
+ * Interface for audit storage backends.
+ * Implement this to store audits in your preferred location.
+ *
+ * @example
+ * ```typescript
+ * // Same database storage (recommended for transactions)
+ * const auditStorage: AuditStorage = {
+ *   async write(records, trx) {
+ *     const db = trx ?? getDatabase();
+ *     await db.insertInto('audit_logs').values(records).execute();
+ *   },
+ * };
+ *
+ * // External audit service
+ * const externalAuditStorage: AuditStorage = {
+ *   async write(records) {
+ *     await fetch('https://audit.example.com/api/audits', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ records }),
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export interface AuditStorage {
+  /**
+   * Write audit records to storage.
+   * Called by Auditor.flush() to persist collected audits.
+   *
+   * @param records - The audit records to write
+   * @param trx - Optional transaction context (for same-DB storage)
+   */
+  write(records: AuditRecord[], trx?: unknown): Promise<void>;
+
+  /**
+   * Optional: Query audit records for retrieval.
+   * Implement this for audit log viewing/searching.
+   *
+   * @param options - Query filters and pagination
+   * @returns Matching audit records
+   */
+  query?(options: AuditQueryOptions): Promise<AuditRecord[]>;
+
+  /**
+   * Optional: Count audit records matching filters.
+   * Useful for pagination.
+   *
+   * @param options - Query filters (limit/offset ignored)
+   * @returns Count of matching records
+   */
+  count?(options: Omit<AuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
+
+  /**
+   * Optional: Get the database connection for transactional audit writes.
+   * When implemented, the endpoint adaptor can automatically wrap handlers
+   * in a transaction, ensuring audits are atomic with other database operations.
+   *
+   * @returns Database connection (e.g., Kysely instance)
+   *
+   * @example
+   * ```typescript
+   * class KyselyAuditStorage implements AuditStorage {
+   *   constructor(private db: Kysely<DB>) {}
+   *
+   *   getDatabase() {
+   *     return this.db;
+   *   }
+   * }
+   * ```
+   */
+  getDatabase?(): unknown;
+}

package/src/types.ts

@@ -0,0 +1,147 @@
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * Represents an auditable action with a type and payload.
+ * Similar to PublishableMessage in @geekmidas/events.
+ *
+ * @template TType - The audit type/name (e.g., 'user.created')
+ * @template TPayload - The audit payload data
+ *
+ * @example
+ * ```typescript
+ * type AppAuditAction =
+ *   | AuditableAction<'user.created', { userId: string; email: string }>
+ *   | AuditableAction<'user.updated', { userId: string; changes: string[] }>
+ *   | AuditableAction<'order.placed', { orderId: string; total: number }>;
+ * ```
+ */
+export type AuditableAction<TType extends string, TPayload = unknown> = {
+  type: TType;
+  payload: TPayload;
+};
+
+/**
+ * Extract the type string from an AuditableAction union.
+ */
+export type ExtractAuditType<T extends AuditableAction<string, unknown>> =
+  T extends AuditableAction<infer TType, unknown> ? TType : never;
+
+/**
+ * Extract the payload for a specific audit type from an AuditableAction union.
+ */
+export type ExtractAuditPayload<
+  T extends AuditableAction<string, unknown>,
+  TType extends ExtractAuditType<T>,
+> = T extends AuditableAction<TType, infer TPayload> ? TPayload : never;
+
+/**
+ * Audit operation types for database auditing.
+ */
+export type AuditOperation = 'INSERT' | 'UPDATE' | 'DELETE' | 'CUSTOM';
+
+/**
+ * Represents the actor who performed an audited action.
+ */
+export interface AuditActor {
+  /** Unique identifier for the actor (user ID, service ID, etc.) */
+  id?: string;
+  /** Type of actor ('user', 'system', 'service', etc.) */
+  type?: string;
+  /** Additional actor properties */
+  [key: string]: unknown;
+}
+
+/**
+ * Metadata associated with an audit record.
+ */
+export interface AuditMetadata {
+  /** Request correlation ID */
+  requestId?: string;
+  /** Which endpoint was called */
+  endpoint?: string;
+  /** HTTP method */
+  method?: string;
+  /** Client IP address */
+  ip?: string;
+  /** Client user agent */
+  userAgent?: string;
+  /** Additional metadata */
+  [key: string]: unknown;
+}
+
+/**
+ * A complete audit record representing a tracked action.
+ */
+export interface AuditRecord<TPayload = unknown> {
+  /** Unique identifier for this audit record */
+  id: string;
+  /** Audit type (e.g., 'user.created', 'order.placed') */
+  type: string;
+  /** Operation type for database audits */
+  operation: AuditOperation;
+  /** Database table name (for database operations) */
+  table?: string;
+  /** Entity primary key(s) */
+  entityId?: string | Record<string, unknown>;
+  /** Previous state (for UPDATE/DELETE) */
+  oldValues?: Record<string, unknown>;
+  /** New state (for INSERT/UPDATE) */
+  newValues?: Record<string, unknown>;
+  /** Custom payload (for CUSTOM operations) */
+  payload?: TPayload;
+  /** When the audit was recorded */
+  timestamp: Date;
+  /** Who performed the action */
+  actor?: AuditActor;
+  /** Request context */
+  metadata?: AuditMetadata;
+}
+
+/**
+ * Options for manual audit calls.
+ */
+export interface AuditOptions {
+  /** Entity primary key(s) for easier querying */
+  entityId?: string | Record<string, unknown>;
+  /** Database table name */
+  table?: string;
+  /** Operation type (defaults to 'CUSTOM') */
+  operation?: AuditOperation;
+  /** Previous state */
+  oldValues?: Record<string, unknown>;
+  /** New state */
+  newValues?: Record<string, unknown>;
+}
+
+/**
+ * Mapped audit definition for declarative auditing.
+ * Similar to MappedEvent in @geekmidas/events.
+ */
+export interface MappedAudit<
+  TAuditAction extends AuditableAction<string, unknown>,
+  TOutput extends StandardSchemaV1 | undefined = undefined,
+> {
+  /** The audit type - must be a valid type from the AuditableAction union */
+  type: ExtractAuditType<TAuditAction>;
+  /** Function to extract payload from the response */
+  payload: (
+    response: InferStandardSchema<TOutput>,
+  ) => ExtractAuditPayload<TAuditAction, ExtractAuditType<TAuditAction>>;
+  /** Optional condition - only audit if this returns true */
+  when?: (response: InferStandardSchema<TOutput>) => boolean;
+  /** Optional entity ID extractor for easier querying */
+  entityId?: (
+    response: InferStandardSchema<TOutput>,
+  ) => string | Record<string, unknown>;
+  /** Optional table name for database association */
+  table?: string;
+}
+
+/**
+ * Extract the AuditableAction type from an Auditor.
+ */
+export type ExtractAuditorAction<T> = T extends Auditor<infer A> ? A : never;
+
+// Forward declaration for Auditor type extraction
+import type { Auditor } from './Auditor';