@geekmidas/audit 0.0.1

package/dist/kysely.d.mts

@@ -0,0 +1,165 @@
+import { AuditRecord } from "./Auditor-ii62d_pF.mjs";
+import { AuditQueryOptions, AuditStorage } from "./storage-DnAMfOA7.mjs";
+import { ControlledTransaction, IsolationLevel, Kysely, Transaction } from "kysely";
+
+//#region src/kysely.d.ts
+
+/**
+ * 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;
+ *   },
+ * );
+ * ```
+ */
+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>;
+}
+interface TransactionSettings {
+  isolationLevel?: IsolationLevel;
+}
+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
+ * ```
+ */
+declare function withAuditableTransaction<DB, T>(db: DatabaseConnection<DB>, auditor: TransactionAwareAuditor<Transaction<DB>>, cb: (trx: Transaction<DB>) => Promise<T>, settings?: TransactionSettings): Promise<T>;
+/**
+ * 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
+ * }
+ * ```
+ */
+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.
+ */
+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,
+ * });
+ * ```
+ */
+declare class KyselyAuditStorage<DB> implements AuditStorage {
+  private readonly db;
+  private readonly tableName;
+  constructor(config: KyselyAuditStorageConfig<DB>);
+  write(records: AuditRecord[], trx?: unknown): Promise<void>;
+  query(options: AuditQueryOptions): Promise<AuditRecord[]>;
+  count(options: Omit<AuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
+  /**
+   * Get the Kysely database instance for transactional operations.
+   * Used by endpoint adaptors to automatically wrap handlers in transactions.
+   */
+  getDatabase(): Kysely<DB>;
+  private applyFilters;
+  private toRow;
+  private fromRow;
+  /**
+   * Parse a JSON value that may already be parsed (e.g., from jsonb columns).
+   */
+  private parseJson;
+  private getActorData;
+  private parseEntityId;
+}
+//#endregion
+export { AuditLogTable, DatabaseConnection, KyselyAuditStorage, KyselyAuditStorageConfig, TransactionAwareAuditor, TransactionSettings, withAuditableTransaction };
+//# sourceMappingURL=kysely.d.mts.map

package/dist/kysely.mjs

@@ -0,0 +1,191 @@
+//#region src/kysely.ts
+/**
+* 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
+* ```
+*/
+async function withAuditableTransaction(db, auditor, cb, settings) {
+	const execute = async (trx) => {
+		auditor.setTransaction(trx);
+		const result = await cb(trx);
+		await auditor.flush(trx);
+		return result;
+	};
+	if (db.isTransaction) return execute(db);
+	const builder = db.transaction();
+	if (settings?.isolationLevel) return builder.setIsolationLevel(settings.isolationLevel).execute(execute);
+	return builder.execute(execute);
+}
+/**
+* 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,
+* });
+* ```
+*/
+var KyselyAuditStorage = class {
+	db;
+	tableName;
+	constructor(config) {
+		this.db = config.db;
+		this.tableName = config.tableName;
+	}
+	async write(records, trx) {
+		if (records.length === 0) return;
+		const db = trx ?? this.db;
+		const rows = records.map((record) => this.toRow(record));
+		await db.insertInto(this.tableName).values(rows).execute();
+	}
+	async query(options) {
+		let query = this.db.selectFrom(this.tableName).selectAll();
+		query = this.applyFilters(query, options);
+		const orderBy = options.orderBy ?? "timestamp";
+		const orderDirection = options.orderDirection ?? "desc";
+		query = query.orderBy(orderBy === "timestamp" ? "timestamp" : "type", orderDirection);
+		if (options.limit !== void 0) query = query.limit(options.limit);
+		if (options.offset !== void 0) query = query.offset(options.offset);
+		const rows = await query.execute();
+		return rows.map((row) => this.fromRow(row));
+	}
+	async count(options) {
+		let query = this.db.selectFrom(this.tableName).select((eb) => 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() {
+		return this.db;
+	}
+	applyFilters(query, options) {
+		if (options.type !== void 0) if (Array.isArray(options.type)) query = query.where("type", "in", options.type);
+		else query = query.where("type", "=", options.type);
+		if (options.entityId !== void 0) {
+			const entityId = typeof options.entityId === "string" ? options.entityId : JSON.stringify(options.entityId);
+			query = query.where("entityId", "=", entityId);
+		}
+		if (options.table !== void 0) query = query.where("table", "=", options.table);
+		if (options.actorId !== void 0) query = query.where("actorId", "=", options.actorId);
+		if (options.from !== void 0) query = query.where("timestamp", ">=", options.from);
+		if (options.to !== void 0) query = query.where("timestamp", "<=", options.to);
+		return query;
+	}
+	toRow(record) {
+		return {
+			id: record.id,
+			type: record.type,
+			operation: record.operation,
+			table: record.table ?? null,
+			entityId: record.entityId === void 0 ? null : typeof record.entityId === "string" ? record.entityId : JSON.stringify(record.entityId),
+			oldValues: record.oldValues !== void 0 ? JSON.stringify(record.oldValues) : null,
+			newValues: record.newValues !== void 0 ? JSON.stringify(record.newValues) : null,
+			payload: record.payload !== void 0 ? JSON.stringify(record.payload) : null,
+			timestamp: record.timestamp,
+			actorId: record.actor?.id ?? null,
+			actorType: record.actor?.type ?? null,
+			actorData: record.actor !== void 0 ? JSON.stringify(this.getActorData(record.actor)) : null,
+			metadata: record.metadata !== void 0 ? JSON.stringify(record.metadata) : null
+		};
+	}
+	fromRow(row) {
+		const actor = row.actorId !== null || row.actorType !== null ? {
+			id: row.actorId ?? void 0,
+			type: row.actorType ?? void 0,
+			...row.actorData ? this.parseJson(row.actorData) : {}
+		} : void 0;
+		return {
+			id: row.id,
+			type: row.type,
+			operation: row.operation,
+			table: row.table ?? void 0,
+			entityId: row.entityId ? this.parseEntityId(row.entityId) : void 0,
+			oldValues: row.oldValues ? this.parseJson(row.oldValues) : void 0,
+			newValues: row.newValues ? this.parseJson(row.newValues) : void 0,
+			payload: row.payload ? this.parseJson(row.payload) : void 0,
+			timestamp: row.timestamp,
+			actor,
+			metadata: row.metadata ? this.parseJson(row.metadata) : void 0
+		};
+	}
+	/**
+	* Parse a JSON value that may already be parsed (e.g., from jsonb columns).
+	*/
+	parseJson(value) {
+		if (typeof value === "object") return value;
+		return JSON.parse(value);
+	}
+	getActorData(actor) {
+		const { id, type,...rest } = actor;
+		return rest;
+	}
+	parseEntityId(entityId) {
+		try {
+			const parsed = JSON.parse(entityId);
+			if (typeof parsed === "object" && parsed !== null) return parsed;
+			return entityId;
+		} catch {
+			return entityId;
+		}
+	}
+};
+
+//#endregion
+export { KyselyAuditStorage, withAuditableTransaction };
+//# sourceMappingURL=kysely.mjs.map

package/dist/kysely.mjs.map

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

package/dist/storage-BtFY7Rha.d.cts

@@ -0,0 +1,102 @@
+import { AuditRecord } from "./Auditor-CZ8lkASv.cjs";
+
+//#region src/storage.d.ts
+
+/**
+ * Options for querying audit records.
+ */
+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 }),
+ *     });
+ *   },
+ * };
+ * ```
+ */
+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;
+}
+//#endregion
+export { AuditQueryOptions, AuditStorage };
+//# sourceMappingURL=storage-BtFY7Rha.d.cts.map

package/dist/storage-DnAMfOA7.d.mts

@@ -0,0 +1,102 @@
+import { AuditRecord } from "./Auditor-ii62d_pF.mjs";
+
+//#region src/storage.d.ts
+
+/**
+ * Options for querying audit records.
+ */
+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 }),
+ *     });
+ *   },
+ * };
+ * ```
+ */
+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;
+}
+//#endregion
+export { AuditQueryOptions, AuditStorage };
+//# sourceMappingURL=storage-DnAMfOA7.d.mts.map

package/dist/storage.d.cts

@@ -0,0 +1,3 @@
+import "./Auditor-CZ8lkASv.cjs";
+import { AuditQueryOptions, AuditStorage } from "./storage-BtFY7Rha.cjs";
+export { AuditQueryOptions, AuditStorage };

package/dist/storage.d.mts

@@ -0,0 +1,3 @@
+import "./Auditor-ii62d_pF.mjs";
+import { AuditQueryOptions, AuditStorage } from "./storage-DnAMfOA7.mjs";
+export { AuditQueryOptions, AuditStorage };

package/dist/types.d.cts

@@ -0,0 +1,2 @@
+import { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditRecord, AuditableAction, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, MappedAudit } from "./Auditor-CZ8lkASv.cjs";
+export { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditRecord, AuditableAction, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, MappedAudit };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditRecord, AuditableAction, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, MappedAudit } from "./Auditor-ii62d_pF.mjs";
+export { AuditActor, AuditMetadata, AuditOperation, AuditOptions, AuditRecord, AuditableAction, ExtractAuditPayload, ExtractAuditType, ExtractAuditorAction, MappedAudit };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@geekmidas/audit",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./kysely": {
+      "types": "./dist/kysely.d.ts",
+      "import": "./dist/kysely.mjs",
+      "require": "./dist/kysely.cjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "~1.0.0",
+    "nanoid": "~5.1.5",
+    "@geekmidas/schema": "0.0.2"
+  },
+  "peerDependencies": {
+    "kysely": "^0.28.0"
+  },
+  "devDependencies": {
+    "kysely": "~0.28.2",
+    "pg": "~8.16.0",
+    "@types/pg": "~8.15.6"
+  }
+}