@contractspec/module.audit-trail 1.44.0

package/dist/storage/index.d.ts

@@ -0,0 +1,88 @@
+import { AuditQueryOptions, AuditRecord, AuditStorage } from "@contractspec/lib.bus";
+
+//#region src/storage/index.d.ts
+
+/**
+ * Extended query options for audit storage.
+ */
+interface ExtendedAuditQueryOptions extends AuditQueryOptions {
+  targetType?: string;
+  clientIp?: string;
+  sessionId?: string;
+  orderBy?: 'occurredAt' | 'recordedAt';
+  orderDir?: 'asc' | 'desc';
+}
+/**
+ * Audit storage adapter interface with extended capabilities.
+ */
+interface AuditStorageAdapter extends AuditStorage {
+  /** Query audit records with extended options */
+  query(options: ExtendedAuditQueryOptions): Promise<AuditRecord[]>;
+  /** Count matching records */
+  count(options: Omit<ExtendedAuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
+  /** Get a single record by ID */
+  getById(id: string): Promise<AuditRecord | null>;
+  /** Get all records for a trace */
+  getByTraceId(traceId: string): Promise<AuditRecord[]>;
+  /** Delete old records (for retention) */
+  deleteOlderThan(date: Date): Promise<number>;
+}
+/**
+ * In-memory audit storage for development/testing.
+ */
+declare class InMemoryAuditStorage implements AuditStorageAdapter {
+  private records;
+  store(record: AuditRecord): Promise<void>;
+  query(options: ExtendedAuditQueryOptions): Promise<AuditRecord[]>;
+  count(options: Omit<ExtendedAuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
+  getById(id: string): Promise<AuditRecord | null>;
+  getByTraceId(traceId: string): Promise<AuditRecord[]>;
+  deleteOlderThan(date: Date): Promise<number>;
+  /**
+   * Get all records (for testing).
+   */
+  getAll(): AuditRecord[];
+  /**
+   * Clear all records (for testing).
+   */
+  clear(): void;
+}
+/**
+ * Retention policy configuration.
+ */
+interface RetentionPolicyConfig {
+  /** Days to keep detailed logs */
+  hotRetentionDays: number;
+  /** Days to keep archived logs (for compliance) */
+  archiveRetentionDays?: number;
+  /** Cron expression for cleanup schedule */
+  cleanupSchedule?: string;
+}
+/**
+ * Retention policy manager.
+ */
+declare class RetentionPolicy {
+  private readonly config;
+  constructor(config: RetentionPolicyConfig);
+  /**
+   * Get the cutoff date for hot storage.
+   */
+  getHotCutoff(): Date;
+  /**
+   * Get the cutoff date for archive storage.
+   */
+  getArchiveCutoff(): Date | null;
+  /**
+   * Apply retention policy to storage.
+   */
+  apply(storage: AuditStorageAdapter): Promise<{
+    deletedCount: number;
+  }>;
+}
+/**
+ * Create an in-memory audit storage.
+ */
+declare function createInMemoryAuditStorage(): InMemoryAuditStorage;
+//#endregion
+export { AuditStorageAdapter, ExtendedAuditQueryOptions, InMemoryAuditStorage, RetentionPolicy, RetentionPolicyConfig, createInMemoryAuditStorage };
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/storage/index.ts"],"sourcesContent":[],"mappings":";;;;;;AASA;AAWiB,UAXA,yBAAA,SAAkC,iBAWd,CAAA;EAEpB,UAAA,CAAA,EAAA,MAAA;EAAoC,QAAA,CAAA,EAAA,MAAA;EAAR,SAAA,CAAA,EAAA,MAAA;EAG3B,OAAA,CAAA,EAAA,YAAA,GAAA,YAAA;EAAL,QAAA,CAAA,EAAA,KAAA,GAAA,MAAA;;;;;AAKoB,UAVhB,mBAAA,SAA4B,YAUZ,CAAA;EAET;EAAO,KAAA,CAAA,OAAA,EAVd,yBAUc,CAAA,EAVc,OAUd,CAVsB,WAUtB,EAAA,CAAA;EAZc;EAAY,KAAA,CAAA,OAAA,EAK5C,IAL4C,CAKvC,yBALuC,EAAA,OAAA,GAAA,QAAA,CAAA,CAAA,EAMpD,OANoD,CAAA,MAAA,CAAA;EAkB5C;EAGS,OAAA,CAAA,EAAA,EAAA,MAAA,CAAA,EAbC,OAaD,CAbS,WAaT,GAAA,IAAA,CAAA;EAAc;EAIb,YAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EAfU,OAeV,CAfkB,WAelB,EAAA,CAAA;EAAoC;EAAR,eAAA,CAAA,IAAA,EAb3B,IAa2B,CAAA,EAbpB,OAaoB,CAAA,MAAA,CAAA;;;;;AAwEtB,cA/EhB,oBAAA,YAAgC,mBA+EhB,CAAA;EAIkB,QAAA,OAAA;EAAR,KAAA,CAAA,MAAA,EAhFjB,WAgFiB,CAAA,EAhFH,OAgFG,CAAA,IAAA,CAAA;EAIT,KAAA,CAAA,OAAA,EAhFP,yBAgFO,CAAA,EAhFqB,OAgFrB,CAhF6B,WAgF7B,EAAA,CAAA;EAAO,KAAA,CAAA,OAAA,EAdxB,IAcwB,CAdnB,yBAcmB,EAAA,OAAA,GAAA,QAAA,CAAA,CAAA,EAbhC,OAagC,CAAA,MAAA,CAAA;EASzB,OAAA,CAAA,EAAA,EAAA,MAAA,CAAA,EAjBiB,OAiBjB,CAjByB,WAiBzB,GAAA,IAAA,CAAA;EAhGiC,YAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EAmFN,OAnFM,CAmFE,WAnFF,EAAA,CAAA;EAAmB,eAAA,CAAA,IAAA,EAuFlC,IAvFkC,CAAA,EAuF3B,OAvF2B,CAAA,MAAA,CAAA;EA+G/C;AAYjB;;EAMkB,MAAA,CAAA,CAAA,EAjCN,WAiCM,EAAA;EASI;;;EAU8B,KAAA,CAAA,CAAA,EAAA,IAAA;AAYpD;;;;UAjDiB,qBAAA;;;;;;;;;;;cAYJ,eAAA;;sBAC0B;;;;kBAKrB;;;;sBASI;;;;iBAUC,sBAAsB;;;;;;;iBAY7B,0BAAA,CAAA,GAA8B"}

package/dist/storage/index.js

@@ -0,0 +1,112 @@
+//#region src/storage/index.ts
+/**
+* In-memory audit storage for development/testing.
+*/
+var InMemoryAuditStorage = class {
+	records = [];
+	async store(record) {
+		this.records.push(record);
+	}
+	async query(options) {
+		let results = [...this.records];
+		if (options.eventKey) {
+			const pattern = options.eventKey.replace(/\*/g, ".*");
+			const regex = /* @__PURE__ */ new RegExp(`^${pattern}$`);
+			results = results.filter((r) => regex.test(r.eventKey));
+		}
+		if (options.actorId) results = results.filter((r) => r.metadata?.actorId === options.actorId);
+		if (options.targetId) results = results.filter((r) => r.metadata?.targetId === options.targetId);
+		if (options.targetType) results = results.filter((r) => r.metadata?.targetType === options.targetType);
+		if (options.orgId) results = results.filter((r) => r.metadata?.orgId === options.orgId);
+		if (options.traceId) results = results.filter((r) => r.traceId === options.traceId);
+		if (options.from) {
+			const fromDate = options.from;
+			results = results.filter((r) => new Date(r.occurredAt) >= fromDate);
+		}
+		if (options.to) {
+			const toDate = options.to;
+			results = results.filter((r) => new Date(r.occurredAt) <= toDate);
+		}
+		const orderBy = options.orderBy ?? "occurredAt";
+		const orderDir = options.orderDir ?? "desc";
+		results.sort((a, b) => {
+			const aTime = orderBy === "occurredAt" ? new Date(a.occurredAt).getTime() : a.recordedAt.getTime();
+			const bTime = orderBy === "occurredAt" ? new Date(b.occurredAt).getTime() : b.recordedAt.getTime();
+			return orderDir === "desc" ? bTime - aTime : aTime - bTime;
+		});
+		const offset = options.offset ?? 0;
+		const limit = options.limit ?? 100;
+		return results.slice(offset, offset + limit);
+	}
+	async count(options) {
+		return (await this.query({
+			...options,
+			limit: Infinity
+		})).length;
+	}
+	async getById(id) {
+		return this.records.find((r) => r.id === id) ?? null;
+	}
+	async getByTraceId(traceId) {
+		return this.query({ traceId });
+	}
+	async deleteOlderThan(date) {
+		const before = this.records.length;
+		this.records = this.records.filter((r) => new Date(r.occurredAt) >= date);
+		return before - this.records.length;
+	}
+	/**
+	* Get all records (for testing).
+	*/
+	getAll() {
+		return [...this.records];
+	}
+	/**
+	* Clear all records (for testing).
+	*/
+	clear() {
+		this.records = [];
+	}
+};
+/**
+* Retention policy manager.
+*/
+var RetentionPolicy = class {
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Get the cutoff date for hot storage.
+	*/
+	getHotCutoff() {
+		const cutoff = /* @__PURE__ */ new Date();
+		cutoff.setDate(cutoff.getDate() - this.config.hotRetentionDays);
+		return cutoff;
+	}
+	/**
+	* Get the cutoff date for archive storage.
+	*/
+	getArchiveCutoff() {
+		if (!this.config.archiveRetentionDays) return null;
+		const cutoff = /* @__PURE__ */ new Date();
+		cutoff.setDate(cutoff.getDate() - this.config.archiveRetentionDays);
+		return cutoff;
+	}
+	/**
+	* Apply retention policy to storage.
+	*/
+	async apply(storage) {
+		const cutoff = this.getHotCutoff();
+		return { deletedCount: await storage.deleteOlderThan(cutoff) };
+	}
+};
+/**
+* Create an in-memory audit storage.
+*/
+function createInMemoryAuditStorage() {
+	return new InMemoryAuditStorage();
+}
+
+//#endregion
+export { InMemoryAuditStorage, RetentionPolicy, createInMemoryAuditStorage };
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["config: RetentionPolicyConfig"],"sources":["../../src/storage/index.ts"],"sourcesContent":["import type {\n  AuditRecord,\n  AuditQueryOptions,\n  AuditStorage,\n} from '@contractspec/lib.bus';\n\n/**\n * Extended query options for audit storage.\n */\nexport interface ExtendedAuditQueryOptions extends AuditQueryOptions {\n  targetType?: string;\n  clientIp?: string;\n  sessionId?: string;\n  orderBy?: 'occurredAt' | 'recordedAt';\n  orderDir?: 'asc' | 'desc';\n}\n\n/**\n * Audit storage adapter interface with extended capabilities.\n */\nexport interface AuditStorageAdapter extends AuditStorage {\n  /** Query audit records with extended options */\n  query(options: ExtendedAuditQueryOptions): Promise<AuditRecord[]>;\n  /** Count matching records */\n  count(\n    options: Omit<ExtendedAuditQueryOptions, 'limit' | 'offset'>\n  ): Promise<number>;\n  /** Get a single record by ID */\n  getById(id: string): Promise<AuditRecord | null>;\n  /** Get all records for a trace */\n  getByTraceId(traceId: string): Promise<AuditRecord[]>;\n  /** Delete old records (for retention) */\n  deleteOlderThan(date: Date): Promise<number>;\n}\n\n/**\n * In-memory audit storage for development/testing.\n */\nexport class InMemoryAuditStorage implements AuditStorageAdapter {\n  private records: AuditRecord[] = [];\n\n  async store(record: AuditRecord): Promise<void> {\n    this.records.push(record);\n  }\n\n  async query(options: ExtendedAuditQueryOptions): Promise<AuditRecord[]> {\n    let results = [...this.records];\n\n    // Apply filters\n    if (options.eventKey) {\n      const pattern = options.eventKey.replace(/\\*/g, '.*');\n      const regex = new RegExp(`^${pattern}$`);\n      results = results.filter((r) => regex.test(r.eventKey));\n    }\n\n    if (options.actorId) {\n      results = results.filter((r) => r.metadata?.actorId === options.actorId);\n    }\n\n    if (options.targetId) {\n      results = results.filter(\n        (r) => r.metadata?.targetId === options.targetId\n      );\n    }\n\n    if (options.targetType) {\n      results = results.filter(\n        (r) => r.metadata?.targetType === options.targetType\n      );\n    }\n\n    if (options.orgId) {\n      results = results.filter((r) => r.metadata?.orgId === options.orgId);\n    }\n\n    if (options.traceId) {\n      results = results.filter((r) => r.traceId === options.traceId);\n    }\n\n    if (options.from) {\n      const fromDate = options.from;\n      results = results.filter((r) => new Date(r.occurredAt) >= fromDate);\n    }\n\n    if (options.to) {\n      const toDate = options.to;\n      results = results.filter((r) => new Date(r.occurredAt) <= toDate);\n    }\n\n    // Sort\n    const orderBy = options.orderBy ?? 'occurredAt';\n    const orderDir = options.orderDir ?? 'desc';\n    results.sort((a, b) => {\n      const aTime =\n        orderBy === 'occurredAt'\n          ? new Date(a.occurredAt).getTime()\n          : a.recordedAt.getTime();\n      const bTime =\n        orderBy === 'occurredAt'\n          ? new Date(b.occurredAt).getTime()\n          : b.recordedAt.getTime();\n      return orderDir === 'desc' ? bTime - aTime : aTime - bTime;\n    });\n\n    // Paginate\n    const offset = options.offset ?? 0;\n    const limit = options.limit ?? 100;\n    return results.slice(offset, offset + limit);\n  }\n\n  async count(\n    options: Omit<ExtendedAuditQueryOptions, 'limit' | 'offset'>\n  ): Promise<number> {\n    const results = await this.query({ ...options, limit: Infinity });\n    return results.length;\n  }\n\n  async getById(id: string): Promise<AuditRecord | null> {\n    return this.records.find((r) => r.id === id) ?? null;\n  }\n\n  async getByTraceId(traceId: string): Promise<AuditRecord[]> {\n    return this.query({ traceId });\n  }\n\n  async deleteOlderThan(date: Date): Promise<number> {\n    const before = this.records.length;\n    this.records = this.records.filter((r) => new Date(r.occurredAt) >= date);\n    return before - this.records.length;\n  }\n\n  /**\n   * Get all records (for testing).\n   */\n  getAll(): AuditRecord[] {\n    return [...this.records];\n  }\n\n  /**\n   * Clear all records (for testing).\n   */\n  clear(): void {\n    this.records = [];\n  }\n}\n\n/**\n * Retention policy configuration.\n */\nexport interface RetentionPolicyConfig {\n  /** Days to keep detailed logs */\n  hotRetentionDays: number;\n  /** Days to keep archived logs (for compliance) */\n  archiveRetentionDays?: number;\n  /** Cron expression for cleanup schedule */\n  cleanupSchedule?: string;\n}\n\n/**\n * Retention policy manager.\n */\nexport class RetentionPolicy {\n  constructor(private readonly config: RetentionPolicyConfig) {}\n\n  /**\n   * Get the cutoff date for hot storage.\n   */\n  getHotCutoff(): Date {\n    const cutoff = new Date();\n    cutoff.setDate(cutoff.getDate() - this.config.hotRetentionDays);\n    return cutoff;\n  }\n\n  /**\n   * Get the cutoff date for archive storage.\n   */\n  getArchiveCutoff(): Date | null {\n    if (!this.config.archiveRetentionDays) return null;\n    const cutoff = new Date();\n    cutoff.setDate(cutoff.getDate() - this.config.archiveRetentionDays);\n    return cutoff;\n  }\n\n  /**\n   * Apply retention policy to storage.\n   */\n  async apply(storage: AuditStorageAdapter): Promise<{\n    deletedCount: number;\n  }> {\n    const cutoff = this.getHotCutoff();\n    const deletedCount = await storage.deleteOlderThan(cutoff);\n    return { deletedCount };\n  }\n}\n\n/**\n * Create an in-memory audit storage.\n */\nexport function createInMemoryAuditStorage(): InMemoryAuditStorage {\n  return new InMemoryAuditStorage();\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@contractspec/module.audit-trail",
+  "version": "1.44.0",
+  "description": "Audit trail module for tracking and querying system events",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src"
+  },
+  "dependencies": {
+    "@contractspec/lib.schema": "1.44.0",
+    "@contractspec/lib.contracts": "1.44.0",
+    "@contractspec/lib.bus": "1.44.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@contractspec/tool.typescript": "1.44.0",
+    "@contractspec/tool.tsdown": "1.44.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./audit-trail.feature": "./dist/audit-trail.feature.js",
+    "./contracts": "./dist/contracts/index.js",
+    "./entities": "./dist/entities/index.js",
+    "./storage": "./dist/storage/index.js",
+    "./*": "./*"
+  },
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./audit-trail.feature": "./dist/audit-trail.feature.js",
+      "./contracts": "./dist/contracts/index.js",
+      "./entities": "./dist/entities/index.js",
+      "./storage": "./dist/storage/index.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/modules/audit-trail"
+  },
+  "homepage": "https://contractspec.io"
+}