@axova/shared 1.0.2 → 1.1.0

package/src/lib/auditLogger.ts

@@ -1,1117 +1,1117 @@
-import { performance } from "node:perf_hooks";
-import { createId } from "@paralleldrive/cuid2";
-
-// Re-export types from audit service for convenience
-export interface AuditLogEntry {
-	eventType:
-		| "CREATE"
-		| "UPDATE"
-		| "DELETE"
-		| "LOGIN"
-		| "LOGOUT"
-		| "ACCESS"
-		| "PERMISSION_CHANGE"
-		| "SYSTEM_ACTION"
-		| "COMPLIANCE_ACTION"
-		| "SECURITY_EVENT";
-	eventCategory:
-		| "USER_ACTION"
-		| "SYSTEM_ACTION"
-		| "ADMIN_ACTION"
-		| "COMPLIANCE_ACTION"
-		| "SECURITY_ACTION"
-		| "DATA_ACTION"
-		| "NOTIFICATION_ACTION";
-	action: string;
-	resource: string;
-	resourceId: string;
-	resourceType?:
-		| "STORE"
-		| "USER"
-		| "PRODUCT"
-		| "ORDER"
-		| "COMPLIANCE"
-		| "POLICY"
-		| "VIOLATION"
-		| "APPEAL"
-		| "NOTIFICATION"
-		| "SYSTEM"
-		| "OTHER";
-	performedBy: string;
-	performedByType:
-		| "USER"
-		| "SYSTEM"
-		| "ADMIN"
-		| "SERVICE"
-		| "AI"
-		| "AUTOMATION"
-		| "ANONYMOUS";
-	performedByName?: string;
-	sessionId?: string;
-	requestId?: string;
-	correlationId?: string;
-	ipAddress?: string;
-	userAgent?: string;
-	clientType?:
-		| "WEB"
-		| "MOBILE_APP"
-		| "API"
-		| "ADMIN_PANEL"
-		| "SYSTEM"
-		| "WEBHOOK"
-		| "CRON_JOB";
-	clientId?: string;
-	clientVersion?: string;
-	location?: {
-		country?: string;
-		region?: string;
-		city?: string;
-		coordinates?: { lat: number; lng: number };
-		timezone?: string;
-	};
-	changes?: {
-		before?: Record<string, unknown>;
-		after?: Record<string, unknown>;
-		fields?: string[];
-	};
-	metadata?: {
-		businessImpact?: string;
-		severity?: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
-		tags?: string[];
-		department?: string;
-		project?: string;
-		feature?: string;
-		version?: string;
-		environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
-		customFields?: Record<string, unknown>;
-	};
-	success?: boolean;
-	errorCode?: string;
-	errorMessage?: string;
-	stackTrace?: string;
-	duration?: number;
-	size?: number;
-	sensitiveData?: boolean;
-	piiInvolved?: boolean;
-	complianceRelevant?: boolean;
-	retentionPeriod?: number;
-	riskLevel?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
-	securityImpact?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
-	workflowId?: string;
-	workflowStep?: string;
-	parentEventId?: string;
-	storeId?: string;
-	storeName?: string;
-	storeSubdomain?: string;
-}
-
-// Context interface for automatic enrichment
-export interface AuditContext {
-	serviceName: string;
-	serviceVersion?: string;
-	requestId?: string;
-	correlationId?: string;
-	sessionId?: string;
-	userId?: string;
-	userType?: "USER" | "ADMIN" | "SYSTEM" | "SERVICE";
-	ipAddress?: string;
-	userAgent?: string;
-	clientId?: string;
-	clientType?:
-		| "WEB"
-		| "MOBILE_APP"
-		| "API"
-		| "ADMIN_PANEL"
-		| "SYSTEM"
-		| "WEBHOOK"
-		| "CRON_JOB";
-	storeId?: string;
-	storeName?: string;
-	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
-	features?: string[];
-	tags?: string[];
-	customMetadata?: Record<string, unknown>;
-}
-
-// Performance tracker for duration logging
-export interface PerformanceTracker {
-	start: number;
-	end(): number;
-	duration(): number;
-}
-
-// Audit logger configuration
-export interface AuditLoggerConfig {
-	serviceName: string;
-	serviceVersion?: string;
-	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
-	auditServiceUrl?: string;
-	auditServiceApiKey?: string;
-	enableLocalLogging?: boolean;
-	enableRemoteLogging?: boolean;
-	bufferSize?: number;
-	flushInterval?: number;
-	defaultRetentionDays?: number;
-	autoEnrichment?: boolean;
-	sensitiveFieldMasking?: boolean;
-	geoLocationEnabled?: boolean;
-}
-
-// Quick action builders for common operations
-export interface QuickActionBuilders {
-	userLogin: (
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	userLogout: (
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	dataAccess: (
-		resource: string,
-		resourceId: string,
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	dataCreate: (
-		resource: string,
-		resourceId: string,
-		userId: string,
-		data?: unknown,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	dataUpdate: (
-		resource: string,
-		resourceId: string,
-		userId: string,
-		changes?: unknown,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	dataDelete: (
-		resource: string,
-		resourceId: string,
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	permissionChange: (
-		targetUserId: string,
-		changedBy: string,
-		changes: unknown,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	securityEvent: (
-		eventType: string,
-		description: string,
-		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	complianceEvent: (
-		framework: string,
-		requirement: string,
-		status: "MET" | "NOT_MET",
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	systemAction: (
-		action: string,
-		resource: string,
-		resourceId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-	storeAction: (
-		storeId: string,
-		action: string,
-		resource: string,
-		resourceId: string,
-		userId?: string,
-		additionalData?: Partial<AuditLogEntry>,
-	) => AuditLogEntry;
-}
-
-// Shared Audit Logger Class
-export class AuditLogger {
-	private config: AuditLoggerConfig;
-	private context: AuditContext;
-	private buffer: AuditLogEntry[] = [];
-	private flushTimer: NodeJS.Timeout | null = null;
-	private performanceTrackers = new Map<string, PerformanceTracker>();
-
-	constructor(
-		config: AuditLoggerConfig,
-		initialContext?: Partial<AuditContext>,
-	) {
-		this.config = {
-			bufferSize: 100,
-			flushInterval: 5000,
-			defaultRetentionDays: 2555,
-			autoEnrichment: true,
-			sensitiveFieldMasking: true,
-			geoLocationEnabled: false,
-			enableLocalLogging: true,
-			enableRemoteLogging: true,
-			...config,
-		};
-
-		this.context = {
-			serviceName: config.serviceName,
-			serviceVersion: config.serviceVersion,
-			environment:
-				config.environment ||
-				(process.env.NODE_ENV as "DEVELOPMENT" | "STAGING" | "PRODUCTION") ||
-				"DEVELOPMENT",
-			...initialContext,
-		};
-
-		this.setupAutoFlush();
-	}
-
-	// Update context (useful for request-scoped information)
-	updateContext(contextUpdate: Partial<AuditContext>): void {
-		this.context = { ...this.context, ...contextUpdate };
-	}
-
-	// Get current context
-	getContext(): AuditContext {
-		return { ...this.context };
-	}
-
-	// Log a custom audit event
-	async log(entry: Partial<AuditLogEntry>): Promise<string> {
-		try {
-			const enrichedEntry = await this.enrichEntry(entry);
-			const auditId = createId();
-
-			// Add to buffer
-			this.addToBuffer(enrichedEntry);
-
-			// Local logging
-			if (this.config.enableLocalLogging) {
-				this.logLocally(enrichedEntry, auditId);
-			}
-
-			// Check if immediate flush is needed for critical events
-			if (this.isCriticalEvent(enrichedEntry)) {
-				await this.flush();
-			}
-
-			return auditId;
-		} catch (error) {
-			console.error("Failed to log audit event:", error);
-			throw error;
-		}
-	}
-
-	// Performance tracking helpers
-	startPerformanceTracking(operationId?: string): string {
-		const id = operationId || createId();
-		const tracker: PerformanceTracker = {
-			start: performance.now(),
-			end: () => performance.now(),
-			duration: function () {
-				return this.end() - this.start;
-			},
-		};
-
-		this.performanceTrackers.set(id, tracker);
-		return id;
-	}
-
-	endPerformanceTracking(operationId: string): number {
-		const tracker = this.performanceTrackers.get(operationId);
-		if (tracker) {
-			const duration = tracker.duration();
-			this.performanceTrackers.delete(operationId);
-			return Math.round(duration);
-		}
-		return 0;
-	}
-
-	// Quick action builders
-	get quick(): QuickActionBuilders {
-		return {
-			userLogin: (userId: string, additionalData?: Partial<AuditLogEntry>) => ({
-				eventType: "LOGIN",
-				eventCategory: "USER_ACTION",
-				action: "user_login",
-				resource: "authentication",
-				resourceId: userId,
-				resourceType: "USER",
-				performedBy: userId,
-				performedByType: "USER",
-				riskLevel: "LOW",
-				complianceRelevant: true,
-				...additionalData,
-			}),
-
-			userLogout: (
-				userId: string,
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "LOGOUT",
-				eventCategory: "USER_ACTION",
-				action: "user_logout",
-				resource: "authentication",
-				resourceId: userId,
-				resourceType: "USER",
-				performedBy: userId,
-				performedByType: "USER",
-				riskLevel: "NONE",
-				...additionalData,
-			}),
-
-			dataAccess: (
-				resource: string,
-				resourceId: string,
-				userId: string,
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "ACCESS",
-				eventCategory: "DATA_ACTION",
-				action: "data_access",
-				resource,
-				resourceId,
-				performedBy: userId,
-				performedByType: "USER",
-				riskLevel: "LOW",
-				complianceRelevant: true,
-				...additionalData,
-			}),
-
-			dataCreate: (
-				resource: string,
-				resourceId: string,
-				userId: string,
-				data?: unknown,
-				additionalData?: Partial<AuditLogEntry>,
-			): AuditLogEntry => ({
-				eventType: "CREATE",
-				eventCategory: "DATA_ACTION",
-				action: "data_create",
-				resource,
-				resourceId,
-				performedBy: userId,
-				performedByType: "USER",
-				changes: data ? { after: data as Record<string, unknown> } : undefined,
-				riskLevel: "LOW",
-				...additionalData,
-			}),
-
-			dataUpdate: (
-				resource: string,
-				resourceId: string,
-				userId: string,
-				changes?: unknown,
-				additionalData?: Partial<AuditLogEntry>,
-			): AuditLogEntry => ({
-				eventType: "UPDATE",
-				eventCategory: "DATA_ACTION",
-				action: "data_update",
-				resource,
-				resourceId,
-				performedBy: userId,
-				performedByType: "USER",
-				changes: changes
-					? {
-							before: (changes as any)?.before,
-							after: (changes as any)?.after,
-							fields: (changes as any)?.fields,
-						}
-					: undefined,
-				riskLevel: "MEDIUM",
-				...additionalData,
-			}),
-
-			dataDelete: (
-				resource: string,
-				resourceId: string,
-				userId: string,
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "DELETE",
-				eventCategory: "DATA_ACTION",
-				action: "data_delete",
-				resource,
-				resourceId,
-				performedBy: userId,
-				performedByType: "USER",
-				riskLevel: "HIGH",
-				complianceRelevant: true,
-				...additionalData,
-			}),
-
-			permissionChange: (
-				targetUserId: string,
-				changedBy: string,
-				changes: unknown,
-				additionalData?: Partial<AuditLogEntry>,
-			): AuditLogEntry => ({
-				eventType: "PERMISSION_CHANGE",
-				eventCategory: "ADMIN_ACTION",
-				action: "permission_change",
-				resource: "user_permissions",
-				resourceId: targetUserId,
-				performedBy: changedBy,
-				performedByType: "ADMIN",
-				changes: changes
-					? {
-							before: (changes as any)?.before,
-							after: (changes as any)?.after,
-							fields: (changes as any)?.fields,
-						}
-					: undefined,
-				riskLevel: "HIGH",
-				securityImpact: "MEDIUM",
-				...additionalData,
-			}),
-
-			securityEvent: (
-				eventType: string,
-				description: string,
-				severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "SECURITY_EVENT",
-				eventCategory: "SECURITY_ACTION",
-				action: eventType,
-				resource: "security",
-				resourceId: createId(),
-				performedBy: "SYSTEM",
-				performedByType: "SYSTEM",
-				riskLevel: severity,
-				securityImpact: severity,
-				metadata: {
-					severity,
-					description,
-					businessImpact:
-						severity === "CRITICAL"
-							? "Service disruption possible"
-							: "Monitoring required",
-				},
-				...additionalData,
-			}),
-
-			complianceEvent: (
-				framework: string,
-				requirement: string,
-				status: "MET" | "NOT_MET",
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "COMPLIANCE_ACTION",
-				eventCategory: "COMPLIANCE_ACTION",
-				action: "compliance_check",
-				resource: "compliance_requirement",
-				resourceId: `${framework}_${requirement}`,
-				performedBy: "SYSTEM",
-				performedByType: "SYSTEM",
-				complianceRelevant: true,
-				riskLevel: status === "NOT_MET" ? "HIGH" : "LOW",
-				metadata: {
-					framework,
-					requirement,
-					status,
-					businessImpact:
-						status === "NOT_MET"
-							? "Compliance violation detected"
-							: "Compliance maintained",
-				},
-				...additionalData,
-			}),
-
-			systemAction: (
-				action: string,
-				resource: string,
-				resourceId: string,
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "SYSTEM_ACTION",
-				eventCategory: "SYSTEM_ACTION",
-				action,
-				resource,
-				resourceId,
-				performedBy: this.context.serviceName,
-				performedByType: "SYSTEM",
-				riskLevel: "NONE",
-				...additionalData,
-			}),
-
-			storeAction: (
-				storeId: string,
-				action: string,
-				resource: string,
-				resourceId: string,
-				userId?: string,
-				additionalData?: Partial<AuditLogEntry>,
-			) => ({
-				eventType: "UPDATE",
-				eventCategory: userId ? "USER_ACTION" : "SYSTEM_ACTION",
-				action,
-				resource,
-				resourceId,
-				resourceType: "STORE",
-				performedBy: userId || this.context.serviceName,
-				performedByType: userId ? "USER" : "SYSTEM",
-				storeId,
-				riskLevel: "LOW",
-				...additionalData,
-			}),
-		};
-	}
-
-	// Convenience methods for common audit events
-	async logUserLogin(
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(this.quick.userLogin(userId, additionalData));
-	}
-
-	async logUserLogout(
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(this.quick.userLogout(userId, additionalData));
-	}
-
-	async logDataAccess(
-		resource: string,
-		resourceId: string,
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.dataAccess(resource, resourceId, userId, additionalData),
-		);
-	}
-
-	async logDataCreate(
-		resource: string,
-		resourceId: string,
-		userId: string,
-		data?: unknown,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.dataCreate(resource, resourceId, userId, data, additionalData),
-		);
-	}
-
-	async logDataUpdate(
-		resource: string,
-		resourceId: string,
-		userId: string,
-		changes?: unknown,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.dataUpdate(
-				resource,
-				resourceId,
-				userId,
-				changes,
-				additionalData,
-			),
-		);
-	}
-
-	async logDataDelete(
-		resource: string,
-		resourceId: string,
-		userId: string,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.dataDelete(resource, resourceId, userId, additionalData),
-		);
-	}
-
-	async logSecurityEvent(
-		eventType: string,
-		description: string,
-		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.securityEvent(
-				eventType,
-				description,
-				severity,
-				additionalData,
-			),
-		);
-	}
-
-	async logStoreAction(
-		storeId: string,
-		action: string,
-		resource: string,
-		resourceId: string,
-		userId?: string,
-		additionalData?: Partial<AuditLogEntry>,
-	): Promise<string> {
-		return this.log(
-			this.quick.storeAction(
-				storeId,
-				action,
-				resource,
-				resourceId,
-				userId,
-				additionalData,
-			),
-		);
-	}
-
-	// Wrapper for async operations with automatic audit logging
-	async auditedOperation<T>(
-		operationName: string,
-		operation: () => Promise<T>,
-		auditData: Partial<AuditLogEntry>,
-	): Promise<{ result: T; auditId: string; duration: number }> {
-		const trackingId = this.startPerformanceTracking();
-		const _startTime = Date.now();
-
-		try {
-			const result = await operation();
-			const duration = this.endPerformanceTracking(trackingId);
-
-			const _auditId = await this.log({
-				...auditData,
-				action: operationName,
-				success: true,
-				duration,
-			});
-
-			return { result, auditId: _auditId, duration };
-		} catch (error) {
-			const duration = this.endPerformanceTracking(trackingId);
-
-			const _auditId = await this.log({
-				...auditData,
-				action: operationName,
-				success: false,
-				duration,
-				errorMessage: error instanceof Error ? error.message : "Unknown error",
-				stackTrace: error instanceof Error ? error.stack : undefined,
-				riskLevel: "MEDIUM",
-			});
-
-			throw error;
-		}
-	}
-
-	// Bulk logging for batch operations
-	async logBatch(entries: Partial<AuditLogEntry>[]): Promise<string[]> {
-		try {
-			const enrichedEntries = await Promise.all(
-				entries.map((entry) => this.enrichEntry(entry)),
-			);
-
-			const auditIds = enrichedEntries.map(() => createId());
-
-			// Add all to buffer
-			enrichedEntries.forEach((entry) => this.addToBuffer(entry));
-
-			// Local logging
-			if (this.config.enableLocalLogging) {
-				enrichedEntries.forEach((entry, index) => {
-					this.logLocally(entry, auditIds[index]);
-				});
-			}
-
-			// Check if any critical events require immediate flush
-			const hasCriticalEvents = enrichedEntries.some((entry) =>
-				this.isCriticalEvent(entry),
-			);
-			if (hasCriticalEvents) {
-				await this.flush();
-			}
-
-			return auditIds;
-		} catch (error) {
-			console.error("Failed to log batch audit events:", error);
-			throw error;
-		}
-	}
-
-	// Flush buffer manually
-	async flush(): Promise<void> {
-		if (this.buffer.length === 0) return;
-
-		try {
-			const entriesToFlush = this.buffer.splice(0);
-
-			if (this.config.enableRemoteLogging) {
-				await this.sendToAuditService(entriesToFlush);
-			}
-
-			console.log(`✅ Flushed ${entriesToFlush.length} audit log entries`);
-		} catch (error) {
-			console.error("Failed to flush audit log buffer:", error);
-			// Re-add entries to buffer for retry
-			this.buffer.unshift(...this.buffer);
-			throw error;
-		}
-	}
-
-	// Private helper methods
-
-	private async enrichEntry(
-		entry: Partial<AuditLogEntry>,
-	): Promise<AuditLogEntry> {
-		const baseEntry: AuditLogEntry = {
-			eventType: entry.eventType || "SYSTEM_ACTION",
-			eventCategory: entry.eventCategory || "SYSTEM_ACTION",
-			action: entry.action || "unknown_action",
-			resource: entry.resource || "unknown_resource",
-			resourceId: entry.resourceId || createId(),
-			performedBy: entry.performedBy || this.context.serviceName,
-			performedByType: entry.performedByType || "SYSTEM",
-			success: entry.success ?? true,
-			riskLevel: entry.riskLevel || "NONE",
-			securityImpact: entry.securityImpact || "NONE",
-			retentionPeriod:
-				entry.retentionPeriod || this.config.defaultRetentionDays,
-			...entry,
-		};
-
-		// Auto-enrichment from context
-		if (this.config.autoEnrichment) {
-			if (this.context.requestId && !baseEntry.requestId) {
-				baseEntry.requestId = this.context.requestId;
-			}
-			if (this.context.correlationId && !baseEntry.correlationId) {
-				baseEntry.correlationId = this.context.correlationId;
-			}
-			if (this.context.sessionId && !baseEntry.sessionId) {
-				baseEntry.sessionId = this.context.sessionId;
-			}
-			if (this.context.ipAddress && !baseEntry.ipAddress) {
-				baseEntry.ipAddress = this.context.ipAddress;
-			}
-			if (this.context.userAgent && !baseEntry.userAgent) {
-				baseEntry.userAgent = this.context.userAgent;
-			}
-			if (this.context.clientId && !baseEntry.clientId) {
-				baseEntry.clientId = this.context.clientId;
-			}
-			if (this.context.clientType && !baseEntry.clientType) {
-				baseEntry.clientType = this.context.clientType;
-			}
-			if (this.context.storeId && !baseEntry.storeId) {
-				baseEntry.storeId = this.context.storeId;
-			}
-			if (this.context.storeName && !baseEntry.storeName) {
-				baseEntry.storeName = this.context.storeName;
-			}
-
-			// Enrich metadata
-			if (!baseEntry.metadata) {
-				baseEntry.metadata = {};
-			}
-
-			baseEntry.metadata.environment = this.context.environment;
-			baseEntry.metadata.version = this.context.serviceVersion;
-
-			if (this.context.features?.length) {
-				baseEntry.metadata.tags = [
-					...(baseEntry.metadata.tags || []),
-					...this.context.features,
-				];
-			}
-
-			if (this.context.tags?.length) {
-				baseEntry.metadata.tags = [
-					...(baseEntry.metadata.tags || []),
-					...this.context.tags,
-				];
-			}
-
-			if (this.context.customMetadata) {
-				baseEntry.metadata.customFields = {
-					...baseEntry.metadata.customFields,
-					...this.context.customMetadata,
-				};
-			}
-		}
-
-		// Mask sensitive data if enabled
-		if (this.config.sensitiveFieldMasking) {
-			baseEntry.changes = this.maskSensitiveData(
-				baseEntry.changes,
-			) as typeof baseEntry.changes;
-			baseEntry.metadata = this.maskSensitiveData(
-				baseEntry.metadata,
-			) as typeof baseEntry.metadata;
-		}
-
-		return baseEntry;
-	}
-
-	private addToBuffer(entry: AuditLogEntry): void {
-		this.buffer.push(entry);
-
-		if (this.buffer.length >= (this.config.bufferSize || 100)) {
-			setImmediate(() => this.flush());
-		}
-	}
-
-	private logLocally(entry: AuditLogEntry, auditId: string): void {
-		const logLevel = this.getLogLevel(entry);
-		const message = `AUDIT [${auditId}] ${entry.action} on ${entry.resource}:${entry.resourceId} by ${entry.performedBy}`;
-
-		switch (logLevel) {
-			case "error":
-				console.error(message, { auditEntry: entry });
-				break;
-			case "warn":
-				console.warn(message, { auditEntry: entry });
-				break;
-			default:
-				console.log(message, { auditEntry: entry });
-				break;
-		}
-	}
-
-	private getLogLevel(entry: AuditLogEntry): "error" | "warn" | "info" {
-		if (
-			!entry.success ||
-			entry.riskLevel === "CRITICAL" ||
-			entry.securityImpact === "CRITICAL"
-		) {
-			return "error";
-		}
-		if (entry.riskLevel === "HIGH" || entry.securityImpact === "HIGH") {
-			return "warn";
-		}
-		return "info";
-	}
-
-	private isCriticalEvent(entry: AuditLogEntry): boolean {
-		return (
-			entry.riskLevel === "CRITICAL" ||
-			entry.securityImpact === "CRITICAL" ||
-			entry.eventCategory === "SECURITY_ACTION" ||
-			(entry.success === false && entry.eventType === "LOGIN")
-		);
-	}
-
-	private async sendToAuditService(entries: AuditLogEntry[]): Promise<void> {
-		if (!this.config.auditServiceUrl) return;
-
-		try {
-			const response = await fetch(
-				`${this.config.auditServiceUrl}/audit/bulk`,
-				{
-					method: "POST",
-					headers: {
-						"Content-Type": "application/json",
-						...(this.config.auditServiceApiKey && {
-							Authorization: `Bearer ${this.config.auditServiceApiKey}`,
-						}),
-					},
-					body: JSON.stringify({ entries }),
-				},
-			);
-
-			if (!response.ok) {
-				throw new Error(
-					`Audit service responded with status: ${response.status}`,
-				);
-			}
-		} catch (error) {
-			console.error("Failed to send audit logs to audit service:", error);
-			throw error;
-		}
-	}
-
-	private maskSensitiveData(data: unknown): unknown {
-		if (!data || typeof data !== "object") {
-			return data;
-		}
-
-		const sensitiveKeys = [
-			"password",
-			"token",
-			"secret",
-			"key",
-			"ssn",
-			"credit",
-			"card",
-			"bank",
-			"account",
-		];
-
-		const masked = { ...(data as Record<string, unknown>) };
-
-		Object.keys(masked).forEach((key) => {
-			const lowerKey = key.toLowerCase();
-			if (sensitiveKeys.some((sensitive) => lowerKey.includes(sensitive))) {
-				masked[key] = "[MASKED]";
-			} else if (typeof masked[key] === "object" && masked[key] !== null) {
-				masked[key] = this.maskSensitiveData(masked[key]);
-			}
-		});
-
-		return masked;
-	}
-
-	private setupAutoFlush(): void {
-		if (this.config.flushInterval && this.config.flushInterval > 0) {
-			this.flushTimer = setInterval(() => {
-				if (this.buffer.length > 0) {
-					this.flush().catch((error) => {
-						console.error("Auto-flush failed:", error);
-					});
-				}
-			}, this.config.flushInterval);
-		}
-	}
-
-	// Cleanup
-	async shutdown(): Promise<void> {
-		try {
-			if (this.flushTimer) {
-				clearInterval(this.flushTimer);
-				this.flushTimer = null;
-			}
-
-			// Flush any remaining entries
-			if (this.buffer.length > 0) {
-				await this.flush();
-			}
-
-			console.log("✅ Audit Logger shutdown complete");
-		} catch (error) {
-			console.error("❌ Error during audit logger shutdown:", error);
-		}
-	}
-}
-
-// Factory function for creating audit logger instances
-export function createAuditLogger(
-	config: AuditLoggerConfig,
-	initialContext?: Partial<AuditContext>,
-): AuditLogger {
-	return new AuditLogger(config, initialContext);
-}
-
-// Middleware factory for Express/Fastify request context
-export function createAuditMiddleware(logger: AuditLogger) {
-	return (req: any, _res: unknown, next: () => void) => {
-		const requestId = req.headers?.["x-request-id"] || createId();
-		const correlationId = req.headers?.["x-correlation-id"];
-		const sessionId = req.headers?.["x-session-id"] || req.session?.id;
-
-		// Update audit context for this request
-		logger.updateContext({
-			requestId,
-			correlationId,
-			sessionId,
-			ipAddress: req.ip || req.connection?.remoteAddress,
-			userAgent: req.headers?.["user-agent"],
-			userId: req.user?.id,
-			userType: req.user?.type,
-			clientId: req.headers?.["x-client-id"],
-			clientType: req.headers?.["x-client-type"] as
-				| "WEB"
-				| "MOBILE_APP"
-				| "API"
-				| "ADMIN_PANEL"
-				| "SYSTEM"
-				| "WEBHOOK"
-				| "CRON_JOB"
-				| undefined,
-		});
-
-		// Attach audit logger to request for easy access
-		(req as any).audit = logger;
-
-		next();
-	};
-}
-
-// Export convenience functions
-export async function logAuditEvent(
-	serviceName: string,
-	entry: Partial<AuditLogEntry>,
-	context?: Partial<AuditContext>,
-): Promise<string> {
-	const logger = createAuditLogger({ serviceName }, context);
-	return logger.log(entry);
-}
-
-export async function logStoreAuditEvent(
-	serviceName: string,
-	storeId: string,
-	action: string,
-	resource: string,
-	resourceId: string,
-	userId?: string,
-	additionalData?: Partial<AuditLogEntry>,
-): Promise<string> {
-	const logger = createAuditLogger({ serviceName }, { storeId });
-	return logger.logStoreAction(
-		storeId,
-		action,
-		resource,
-		resourceId,
-		userId,
-		additionalData,
-	);
-}
-
-// Default audit logger instance (can be configured once and reused)
-let defaultLogger: AuditLogger | null = null;
-
-export function setDefaultAuditLogger(logger: AuditLogger): void {
-	defaultLogger = logger;
-}
-
-export function getDefaultAuditLogger(): AuditLogger {
-	if (!defaultLogger) {
-		throw new Error(
-			"Default audit logger not configured. Call setDefaultAuditLogger() first.",
-		);
-	}
-	return defaultLogger;
-}
-
-// Quick logging functions using default logger
-export async function quickLog(entry: Partial<AuditLogEntry>): Promise<string> {
-	return getDefaultAuditLogger().log(entry);
-}
-
-export async function quickLogUserAction(
-	action: string,
-	resource: string,
-	resourceId: string,
-	userId: string,
-	additionalData?: Partial<AuditLogEntry>,
-): Promise<string> {
-	return getDefaultAuditLogger().log({
-		eventType: "UPDATE",
-		eventCategory: "USER_ACTION",
-		action,
-		resource,
-		resourceId,
-		performedBy: userId,
-		performedByType: "USER",
-		...additionalData,
-	});
-}
-
-export async function quickLogSystemAction(
-	action: string,
-	resource: string,
-	resourceId: string,
-	additionalData?: Partial<AuditLogEntry>,
-): Promise<string> {
-	return getDefaultAuditLogger().log({
-		eventType: "SYSTEM_ACTION",
-		eventCategory: "SYSTEM_ACTION",
-		action,
-		resource,
-		resourceId,
-		performedBy: "SYSTEM",
-		performedByType: "SYSTEM",
-		...additionalData,
-	});
-}
+import { performance } from "node:perf_hooks";
+import { createId } from "@paralleldrive/cuid2";
+
+// Re-export types from audit service for convenience
+export interface AuditLogEntry {
+	eventType:
+		| "CREATE"
+		| "UPDATE"
+		| "DELETE"
+		| "LOGIN"
+		| "LOGOUT"
+		| "ACCESS"
+		| "PERMISSION_CHANGE"
+		| "SYSTEM_ACTION"
+		| "COMPLIANCE_ACTION"
+		| "SECURITY_EVENT";
+	eventCategory:
+		| "USER_ACTION"
+		| "SYSTEM_ACTION"
+		| "ADMIN_ACTION"
+		| "COMPLIANCE_ACTION"
+		| "SECURITY_ACTION"
+		| "DATA_ACTION"
+		| "NOTIFICATION_ACTION";
+	action: string;
+	resource: string;
+	resourceId: string;
+	resourceType?:
+		| "STORE"
+		| "USER"
+		| "PRODUCT"
+		| "ORDER"
+		| "COMPLIANCE"
+		| "POLICY"
+		| "VIOLATION"
+		| "APPEAL"
+		| "NOTIFICATION"
+		| "SYSTEM"
+		| "OTHER";
+	performedBy: string;
+	performedByType:
+		| "USER"
+		| "SYSTEM"
+		| "ADMIN"
+		| "SERVICE"
+		| "AI"
+		| "AUTOMATION"
+		| "ANONYMOUS";
+	performedByName?: string;
+	sessionId?: string;
+	requestId?: string;
+	correlationId?: string;
+	ipAddress?: string;
+	userAgent?: string;
+	clientType?:
+		| "WEB"
+		| "MOBILE_APP"
+		| "API"
+		| "ADMIN_PANEL"
+		| "SYSTEM"
+		| "WEBHOOK"
+		| "CRON_JOB";
+	clientId?: string;
+	clientVersion?: string;
+	location?: {
+		country?: string;
+		region?: string;
+		city?: string;
+		coordinates?: { lat: number; lng: number };
+		timezone?: string;
+	};
+	changes?: {
+		before?: Record<string, unknown>;
+		after?: Record<string, unknown>;
+		fields?: string[];
+	};
+	metadata?: {
+		businessImpact?: string;
+		severity?: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+		tags?: string[];
+		department?: string;
+		project?: string;
+		feature?: string;
+		version?: string;
+		environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+		customFields?: Record<string, unknown>;
+	};
+	success?: boolean;
+	errorCode?: string;
+	errorMessage?: string;
+	stackTrace?: string;
+	duration?: number;
+	size?: number;
+	sensitiveData?: boolean;
+	piiInvolved?: boolean;
+	complianceRelevant?: boolean;
+	retentionPeriod?: number;
+	riskLevel?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+	securityImpact?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+	workflowId?: string;
+	workflowStep?: string;
+	parentEventId?: string;
+	storeId?: string;
+	storeName?: string;
+	storeSubdomain?: string;
+}
+
+// Context interface for automatic enrichment
+export interface AuditContext {
+	serviceName: string;
+	serviceVersion?: string;
+	requestId?: string;
+	correlationId?: string;
+	sessionId?: string;
+	userId?: string;
+	userType?: "USER" | "ADMIN" | "SYSTEM" | "SERVICE";
+	ipAddress?: string;
+	userAgent?: string;
+	clientId?: string;
+	clientType?:
+		| "WEB"
+		| "MOBILE_APP"
+		| "API"
+		| "ADMIN_PANEL"
+		| "SYSTEM"
+		| "WEBHOOK"
+		| "CRON_JOB";
+	storeId?: string;
+	storeName?: string;
+	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+	features?: string[];
+	tags?: string[];
+	customMetadata?: Record<string, unknown>;
+}
+
+// Performance tracker for duration logging
+export interface PerformanceTracker {
+	start: number;
+	end(): number;
+	duration(): number;
+}
+
+// Audit logger configuration
+export interface AuditLoggerConfig {
+	serviceName: string;
+	serviceVersion?: string;
+	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+	auditServiceUrl?: string;
+	auditServiceApiKey?: string;
+	enableLocalLogging?: boolean;
+	enableRemoteLogging?: boolean;
+	bufferSize?: number;
+	flushInterval?: number;
+	defaultRetentionDays?: number;
+	autoEnrichment?: boolean;
+	sensitiveFieldMasking?: boolean;
+	geoLocationEnabled?: boolean;
+}
+
+// Quick action builders for common operations
+export interface QuickActionBuilders {
+	userLogin: (
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	userLogout: (
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataAccess: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataCreate: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		data?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataUpdate: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		changes?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataDelete: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	permissionChange: (
+		targetUserId: string,
+		changedBy: string,
+		changes: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	securityEvent: (
+		eventType: string,
+		description: string,
+		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	complianceEvent: (
+		framework: string,
+		requirement: string,
+		status: "MET" | "NOT_MET",
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	systemAction: (
+		action: string,
+		resource: string,
+		resourceId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	storeAction: (
+		storeId: string,
+		action: string,
+		resource: string,
+		resourceId: string,
+		userId?: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+}
+
+// Shared Audit Logger Class
+export class AuditLogger {
+	private config: AuditLoggerConfig;
+	private context: AuditContext;
+	private buffer: AuditLogEntry[] = [];
+	private flushTimer: NodeJS.Timeout | null = null;
+	private performanceTrackers = new Map<string, PerformanceTracker>();
+
+	constructor(
+		config: AuditLoggerConfig,
+		initialContext?: Partial<AuditContext>,
+	) {
+		this.config = {
+			bufferSize: 100,
+			flushInterval: 5000,
+			defaultRetentionDays: 2555,
+			autoEnrichment: true,
+			sensitiveFieldMasking: true,
+			geoLocationEnabled: false,
+			enableLocalLogging: true,
+			enableRemoteLogging: true,
+			...config,
+		};
+
+		this.context = {
+			serviceName: config.serviceName,
+			serviceVersion: config.serviceVersion,
+			environment:
+				config.environment ||
+				(process.env.NODE_ENV as "DEVELOPMENT" | "STAGING" | "PRODUCTION") ||
+				"DEVELOPMENT",
+			...initialContext,
+		};
+
+		this.setupAutoFlush();
+	}
+
+	// Update context (useful for request-scoped information)
+	updateContext(contextUpdate: Partial<AuditContext>): void {
+		this.context = { ...this.context, ...contextUpdate };
+	}
+
+	// Get current context
+	getContext(): AuditContext {
+		return { ...this.context };
+	}
+
+	// Log a custom audit event
+	async log(entry: Partial<AuditLogEntry>): Promise<string> {
+		try {
+			const enrichedEntry = await this.enrichEntry(entry);
+			const auditId = createId();
+
+			// Add to buffer
+			this.addToBuffer(enrichedEntry);
+
+			// Local logging
+			if (this.config.enableLocalLogging) {
+				this.logLocally(enrichedEntry, auditId);
+			}
+
+			// Check if immediate flush is needed for critical events
+			if (this.isCriticalEvent(enrichedEntry)) {
+				await this.flush();
+			}
+
+			return auditId;
+		} catch (error) {
+			console.error("Failed to log audit event:", error);
+			throw error;
+		}
+	}
+
+	// Performance tracking helpers
+	startPerformanceTracking(operationId?: string): string {
+		const id = operationId || createId();
+		const tracker: PerformanceTracker = {
+			start: performance.now(),
+			end: () => performance.now(),
+			duration: function () {
+				return this.end() - this.start;
+			},
+		};
+
+		this.performanceTrackers.set(id, tracker);
+		return id;
+	}
+
+	endPerformanceTracking(operationId: string): number {
+		const tracker = this.performanceTrackers.get(operationId);
+		if (tracker) {
+			const duration = tracker.duration();
+			this.performanceTrackers.delete(operationId);
+			return Math.round(duration);
+		}
+		return 0;
+	}
+
+	// Quick action builders
+	get quick(): QuickActionBuilders {
+		return {
+			userLogin: (userId: string, additionalData?: Partial<AuditLogEntry>) => ({
+				eventType: "LOGIN",
+				eventCategory: "USER_ACTION",
+				action: "user_login",
+				resource: "authentication",
+				resourceId: userId,
+				resourceType: "USER",
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "LOW",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			userLogout: (
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "LOGOUT",
+				eventCategory: "USER_ACTION",
+				action: "user_logout",
+				resource: "authentication",
+				resourceId: userId,
+				resourceType: "USER",
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "NONE",
+				...additionalData,
+			}),
+
+			dataAccess: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "ACCESS",
+				eventCategory: "DATA_ACTION",
+				action: "data_access",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "LOW",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			dataCreate: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				data?: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "CREATE",
+				eventCategory: "DATA_ACTION",
+				action: "data_create",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				changes: data ? { after: data as Record<string, unknown> } : undefined,
+				riskLevel: "LOW",
+				...additionalData,
+			}),
+
+			dataUpdate: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				changes?: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "UPDATE",
+				eventCategory: "DATA_ACTION",
+				action: "data_update",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				changes: changes
+					? {
+							before: (changes as any)?.before,
+							after: (changes as any)?.after,
+							fields: (changes as any)?.fields,
+						}
+					: undefined,
+				riskLevel: "MEDIUM",
+				...additionalData,
+			}),
+
+			dataDelete: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "DELETE",
+				eventCategory: "DATA_ACTION",
+				action: "data_delete",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "HIGH",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			permissionChange: (
+				targetUserId: string,
+				changedBy: string,
+				changes: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "PERMISSION_CHANGE",
+				eventCategory: "ADMIN_ACTION",
+				action: "permission_change",
+				resource: "user_permissions",
+				resourceId: targetUserId,
+				performedBy: changedBy,
+				performedByType: "ADMIN",
+				changes: changes
+					? {
+							before: (changes as any)?.before,
+							after: (changes as any)?.after,
+							fields: (changes as any)?.fields,
+						}
+					: undefined,
+				riskLevel: "HIGH",
+				securityImpact: "MEDIUM",
+				...additionalData,
+			}),
+
+			securityEvent: (
+				eventType: string,
+				description: string,
+				severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "SECURITY_EVENT",
+				eventCategory: "SECURITY_ACTION",
+				action: eventType,
+				resource: "security",
+				resourceId: createId(),
+				performedBy: "SYSTEM",
+				performedByType: "SYSTEM",
+				riskLevel: severity,
+				securityImpact: severity,
+				metadata: {
+					severity,
+					description,
+					businessImpact:
+						severity === "CRITICAL"
+							? "Service disruption possible"
+							: "Monitoring required",
+				},
+				...additionalData,
+			}),
+
+			complianceEvent: (
+				framework: string,
+				requirement: string,
+				status: "MET" | "NOT_MET",
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "COMPLIANCE_ACTION",
+				eventCategory: "COMPLIANCE_ACTION",
+				action: "compliance_check",
+				resource: "compliance_requirement",
+				resourceId: `${framework}_${requirement}`,
+				performedBy: "SYSTEM",
+				performedByType: "SYSTEM",
+				complianceRelevant: true,
+				riskLevel: status === "NOT_MET" ? "HIGH" : "LOW",
+				metadata: {
+					framework,
+					requirement,
+					status,
+					businessImpact:
+						status === "NOT_MET"
+							? "Compliance violation detected"
+							: "Compliance maintained",
+				},
+				...additionalData,
+			}),
+
+			systemAction: (
+				action: string,
+				resource: string,
+				resourceId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "SYSTEM_ACTION",
+				eventCategory: "SYSTEM_ACTION",
+				action,
+				resource,
+				resourceId,
+				performedBy: this.context.serviceName,
+				performedByType: "SYSTEM",
+				riskLevel: "NONE",
+				...additionalData,
+			}),
+
+			storeAction: (
+				storeId: string,
+				action: string,
+				resource: string,
+				resourceId: string,
+				userId?: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "UPDATE",
+				eventCategory: userId ? "USER_ACTION" : "SYSTEM_ACTION",
+				action,
+				resource,
+				resourceId,
+				resourceType: "STORE",
+				performedBy: userId || this.context.serviceName,
+				performedByType: userId ? "USER" : "SYSTEM",
+				storeId,
+				riskLevel: "LOW",
+				...additionalData,
+			}),
+		};
+	}
+
+	// Convenience methods for common audit events
+	async logUserLogin(
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(this.quick.userLogin(userId, additionalData));
+	}
+
+	async logUserLogout(
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(this.quick.userLogout(userId, additionalData));
+	}
+
+	async logDataAccess(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataAccess(resource, resourceId, userId, additionalData),
+		);
+	}
+
+	async logDataCreate(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		data?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataCreate(resource, resourceId, userId, data, additionalData),
+		);
+	}
+
+	async logDataUpdate(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		changes?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataUpdate(
+				resource,
+				resourceId,
+				userId,
+				changes,
+				additionalData,
+			),
+		);
+	}
+
+	async logDataDelete(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataDelete(resource, resourceId, userId, additionalData),
+		);
+	}
+
+	async logSecurityEvent(
+		eventType: string,
+		description: string,
+		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.securityEvent(
+				eventType,
+				description,
+				severity,
+				additionalData,
+			),
+		);
+	}
+
+	async logStoreAction(
+		storeId: string,
+		action: string,
+		resource: string,
+		resourceId: string,
+		userId?: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.storeAction(
+				storeId,
+				action,
+				resource,
+				resourceId,
+				userId,
+				additionalData,
+			),
+		);
+	}
+
+	// Wrapper for async operations with automatic audit logging
+	async auditedOperation<T>(
+		operationName: string,
+		operation: () => Promise<T>,
+		auditData: Partial<AuditLogEntry>,
+	): Promise<{ result: T; auditId: string; duration: number }> {
+		const trackingId = this.startPerformanceTracking();
+		const _startTime = Date.now();
+
+		try {
+			const result = await operation();
+			const duration = this.endPerformanceTracking(trackingId);
+
+			const _auditId = await this.log({
+				...auditData,
+				action: operationName,
+				success: true,
+				duration,
+			});
+
+			return { result, auditId: _auditId, duration };
+		} catch (error) {
+			const duration = this.endPerformanceTracking(trackingId);
+
+			const _auditId = await this.log({
+				...auditData,
+				action: operationName,
+				success: false,
+				duration,
+				errorMessage: error instanceof Error ? error.message : "Unknown error",
+				stackTrace: error instanceof Error ? error.stack : undefined,
+				riskLevel: "MEDIUM",
+			});
+
+			throw error;
+		}
+	}
+
+	// Bulk logging for batch operations
+	async logBatch(entries: Partial<AuditLogEntry>[]): Promise<string[]> {
+		try {
+			const enrichedEntries = await Promise.all(
+				entries.map((entry) => this.enrichEntry(entry)),
+			);
+
+			const auditIds = enrichedEntries.map(() => createId());
+
+			// Add all to buffer
+			enrichedEntries.forEach((entry) => this.addToBuffer(entry));
+
+			// Local logging
+			if (this.config.enableLocalLogging) {
+				enrichedEntries.forEach((entry, index) => {
+					this.logLocally(entry, auditIds[index]);
+				});
+			}
+
+			// Check if any critical events require immediate flush
+			const hasCriticalEvents = enrichedEntries.some((entry) =>
+				this.isCriticalEvent(entry),
+			);
+			if (hasCriticalEvents) {
+				await this.flush();
+			}
+
+			return auditIds;
+		} catch (error) {
+			console.error("Failed to log batch audit events:", error);
+			throw error;
+		}
+	}
+
+	// Flush buffer manually
+	async flush(): Promise<void> {
+		if (this.buffer.length === 0) return;
+
+		try {
+			const entriesToFlush = this.buffer.splice(0);
+
+			if (this.config.enableRemoteLogging) {
+				await this.sendToAuditService(entriesToFlush);
+			}
+
+			console.log(`✅ Flushed ${entriesToFlush.length} audit log entries`);
+		} catch (error) {
+			console.error("Failed to flush audit log buffer:", error);
+			// Re-add entries to buffer for retry
+			this.buffer.unshift(...this.buffer);
+			throw error;
+		}
+	}
+
+	// Private helper methods
+
+	private async enrichEntry(
+		entry: Partial<AuditLogEntry>,
+	): Promise<AuditLogEntry> {
+		const baseEntry: AuditLogEntry = {
+			eventType: entry.eventType || "SYSTEM_ACTION",
+			eventCategory: entry.eventCategory || "SYSTEM_ACTION",
+			action: entry.action || "unknown_action",
+			resource: entry.resource || "unknown_resource",
+			resourceId: entry.resourceId || createId(),
+			performedBy: entry.performedBy || this.context.serviceName,
+			performedByType: entry.performedByType || "SYSTEM",
+			success: entry.success ?? true,
+			riskLevel: entry.riskLevel || "NONE",
+			securityImpact: entry.securityImpact || "NONE",
+			retentionPeriod:
+				entry.retentionPeriod || this.config.defaultRetentionDays,
+			...entry,
+		};
+
+		// Auto-enrichment from context
+		if (this.config.autoEnrichment) {
+			if (this.context.requestId && !baseEntry.requestId) {
+				baseEntry.requestId = this.context.requestId;
+			}
+			if (this.context.correlationId && !baseEntry.correlationId) {
+				baseEntry.correlationId = this.context.correlationId;
+			}
+			if (this.context.sessionId && !baseEntry.sessionId) {
+				baseEntry.sessionId = this.context.sessionId;
+			}
+			if (this.context.ipAddress && !baseEntry.ipAddress) {
+				baseEntry.ipAddress = this.context.ipAddress;
+			}
+			if (this.context.userAgent && !baseEntry.userAgent) {
+				baseEntry.userAgent = this.context.userAgent;
+			}
+			if (this.context.clientId && !baseEntry.clientId) {
+				baseEntry.clientId = this.context.clientId;
+			}
+			if (this.context.clientType && !baseEntry.clientType) {
+				baseEntry.clientType = this.context.clientType;
+			}
+			if (this.context.storeId && !baseEntry.storeId) {
+				baseEntry.storeId = this.context.storeId;
+			}
+			if (this.context.storeName && !baseEntry.storeName) {
+				baseEntry.storeName = this.context.storeName;
+			}
+
+			// Enrich metadata
+			if (!baseEntry.metadata) {
+				baseEntry.metadata = {};
+			}
+
+			baseEntry.metadata.environment = this.context.environment;
+			baseEntry.metadata.version = this.context.serviceVersion;
+
+			if (this.context.features?.length) {
+				baseEntry.metadata.tags = [
+					...(baseEntry.metadata.tags || []),
+					...this.context.features,
+				];
+			}
+
+			if (this.context.tags?.length) {
+				baseEntry.metadata.tags = [
+					...(baseEntry.metadata.tags || []),
+					...this.context.tags,
+				];
+			}
+
+			if (this.context.customMetadata) {
+				baseEntry.metadata.customFields = {
+					...baseEntry.metadata.customFields,
+					...this.context.customMetadata,
+				};
+			}
+		}
+
+		// Mask sensitive data if enabled
+		if (this.config.sensitiveFieldMasking) {
+			baseEntry.changes = this.maskSensitiveData(
+				baseEntry.changes,
+			) as typeof baseEntry.changes;
+			baseEntry.metadata = this.maskSensitiveData(
+				baseEntry.metadata,
+			) as typeof baseEntry.metadata;
+		}
+
+		return baseEntry;
+	}
+
+	private addToBuffer(entry: AuditLogEntry): void {
+		this.buffer.push(entry);
+
+		if (this.buffer.length >= (this.config.bufferSize || 100)) {
+			setImmediate(() => this.flush());
+		}
+	}
+
+	private logLocally(entry: AuditLogEntry, auditId: string): void {
+		const logLevel = this.getLogLevel(entry);
+		const message = `AUDIT [${auditId}] ${entry.action} on ${entry.resource}:${entry.resourceId} by ${entry.performedBy}`;
+
+		switch (logLevel) {
+			case "error":
+				console.error(message, { auditEntry: entry });
+				break;
+			case "warn":
+				console.warn(message, { auditEntry: entry });
+				break;
+			default:
+				console.log(message, { auditEntry: entry });
+				break;
+		}
+	}
+
+	private getLogLevel(entry: AuditLogEntry): "error" | "warn" | "info" {
+		if (
+			!entry.success ||
+			entry.riskLevel === "CRITICAL" ||
+			entry.securityImpact === "CRITICAL"
+		) {
+			return "error";
+		}
+		if (entry.riskLevel === "HIGH" || entry.securityImpact === "HIGH") {
+			return "warn";
+		}
+		return "info";
+	}
+
+	private isCriticalEvent(entry: AuditLogEntry): boolean {
+		return (
+			entry.riskLevel === "CRITICAL" ||
+			entry.securityImpact === "CRITICAL" ||
+			entry.eventCategory === "SECURITY_ACTION" ||
+			(entry.success === false && entry.eventType === "LOGIN")
+		);
+	}
+
+	private async sendToAuditService(entries: AuditLogEntry[]): Promise<void> {
+		if (!this.config.auditServiceUrl) return;
+
+		try {
+			const response = await fetch(
+				`${this.config.auditServiceUrl}/audit/bulk`,
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						...(this.config.auditServiceApiKey && {
+							Authorization: `Bearer ${this.config.auditServiceApiKey}`,
+						}),
+					},
+					body: JSON.stringify({ entries }),
+				},
+			);
+
+			if (!response.ok) {
+				throw new Error(
+					`Audit service responded with status: ${response.status}`,
+				);
+			}
+		} catch (error) {
+			console.error("Failed to send audit logs to audit service:", error);
+			throw error;
+		}
+	}
+
+	private maskSensitiveData(data: unknown): unknown {
+		if (!data || typeof data !== "object") {
+			return data;
+		}
+
+		const sensitiveKeys = [
+			"password",
+			"token",
+			"secret",
+			"key",
+			"ssn",
+			"credit",
+			"card",
+			"bank",
+			"account",
+		];
+
+		const masked = { ...(data as Record<string, unknown>) };
+
+		Object.keys(masked).forEach((key) => {
+			const lowerKey = key.toLowerCase();
+			if (sensitiveKeys.some((sensitive) => lowerKey.includes(sensitive))) {
+				masked[key] = "[MASKED]";
+			} else if (typeof masked[key] === "object" && masked[key] !== null) {
+				masked[key] = this.maskSensitiveData(masked[key]);
+			}
+		});
+
+		return masked;
+	}
+
+	private setupAutoFlush(): void {
+		if (this.config.flushInterval && this.config.flushInterval > 0) {
+			this.flushTimer = setInterval(() => {
+				if (this.buffer.length > 0) {
+					this.flush().catch((error) => {
+						console.error("Auto-flush failed:", error);
+					});
+				}
+			}, this.config.flushInterval);
+		}
+	}
+
+	// Cleanup
+	async shutdown(): Promise<void> {
+		try {
+			if (this.flushTimer) {
+				clearInterval(this.flushTimer);
+				this.flushTimer = null;
+			}
+
+			// Flush any remaining entries
+			if (this.buffer.length > 0) {
+				await this.flush();
+			}
+
+			console.log("✅ Audit Logger shutdown complete");
+		} catch (error) {
+			console.error("❌ Error during audit logger shutdown:", error);
+		}
+	}
+}
+
+// Factory function for creating audit logger instances
+export function createAuditLogger(
+	config: AuditLoggerConfig,
+	initialContext?: Partial<AuditContext>,
+): AuditLogger {
+	return new AuditLogger(config, initialContext);
+}
+
+// Middleware factory for Express/Fastify request context
+export function createAuditMiddleware(logger: AuditLogger) {
+	return (req: any, _res: unknown, next: () => void) => {
+		const requestId = req.headers?.["x-request-id"] || createId();
+		const correlationId = req.headers?.["x-correlation-id"];
+		const sessionId = req.headers?.["x-session-id"] || req.session?.id;
+
+		// Update audit context for this request
+		logger.updateContext({
+			requestId,
+			correlationId,
+			sessionId,
+			ipAddress: req.ip || req.connection?.remoteAddress,
+			userAgent: req.headers?.["user-agent"],
+			userId: req.user?.id,
+			userType: req.user?.type,
+			clientId: req.headers?.["x-client-id"],
+			clientType: req.headers?.["x-client-type"] as
+				| "WEB"
+				| "MOBILE_APP"
+				| "API"
+				| "ADMIN_PANEL"
+				| "SYSTEM"
+				| "WEBHOOK"
+				| "CRON_JOB"
+				| undefined,
+		});
+
+		// Attach audit logger to request for easy access
+		(req as any).audit = logger;
+
+		next();
+	};
+}
+
+// Export convenience functions
+export async function logAuditEvent(
+	serviceName: string,
+	entry: Partial<AuditLogEntry>,
+	context?: Partial<AuditContext>,
+): Promise<string> {
+	const logger = createAuditLogger({ serviceName }, context);
+	return logger.log(entry);
+}
+
+export async function logStoreAuditEvent(
+	serviceName: string,
+	storeId: string,
+	action: string,
+	resource: string,
+	resourceId: string,
+	userId?: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	const logger = createAuditLogger({ serviceName }, { storeId });
+	return logger.logStoreAction(
+		storeId,
+		action,
+		resource,
+		resourceId,
+		userId,
+		additionalData,
+	);
+}
+
+// Default audit logger instance (can be configured once and reused)
+let defaultLogger: AuditLogger | null = null;
+
+export function setDefaultAuditLogger(logger: AuditLogger): void {
+	defaultLogger = logger;
+}
+
+export function getDefaultAuditLogger(): AuditLogger {
+	if (!defaultLogger) {
+		throw new Error(
+			"Default audit logger not configured. Call setDefaultAuditLogger() first.",
+		);
+	}
+	return defaultLogger;
+}
+
+// Quick logging functions using default logger
+export async function quickLog(entry: Partial<AuditLogEntry>): Promise<string> {
+	return getDefaultAuditLogger().log(entry);
+}
+
+export async function quickLogUserAction(
+	action: string,
+	resource: string,
+	resourceId: string,
+	userId: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	return getDefaultAuditLogger().log({
+		eventType: "UPDATE",
+		eventCategory: "USER_ACTION",
+		action,
+		resource,
+		resourceId,
+		performedBy: userId,
+		performedByType: "USER",
+		...additionalData,
+	});
+}
+
+export async function quickLogSystemAction(
+	action: string,
+	resource: string,
+	resourceId: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	return getDefaultAuditLogger().log({
+		eventType: "SYSTEM_ACTION",
+		eventCategory: "SYSTEM_ACTION",
+		action,
+		resource,
+		resourceId,
+		performedBy: "SYSTEM",
+		performedByType: "SYSTEM",
+		...additionalData,
+	});
+}