/**
 * @ai-summary Type definitions for centralized audit logging
 * @ai-context Categories, severity levels, log entries, and filter options
 */

/**
 * Audit log categories - maps to system domains
 */
export type AuditLogCategory = 'auth' | 'vehicle' | 'user' | 'system' | 'admin';

/**
 * Audit log severity levels
 */
export type AuditLogSeverity = 'info' | 'warning' | 'error';

/**
 * Audit log entry as stored in database
 */
export interface AuditLogEntry {
  id: string;
  category: AuditLogCategory;
  severity: AuditLogSeverity;
  userId: string | null;
  userEmail: string | null;
  action: string;
  resourceType: string | null;
  resourceId: string | null;
  details: Record<string, unknown> | null;
  createdAt: Date;
}

/**
 * Input for creating a new audit log entry
 */
export interface CreateAuditLogInput {
  category: AuditLogCategory;
  severity: AuditLogSeverity;
  userId?: string | null;
  action: string;
  resourceType?: string | null;
  resourceId?: string | null;
  details?: Record<string, unknown> | null;
}

/**
 * Filters for querying audit logs
 */
export interface AuditLogFilters {
  search?: string;
  category?: AuditLogCategory;
  severity?: AuditLogSeverity;
  userId?: string;
  startDate?: Date;
  endDate?: Date;
}

/**
 * Pagination options for audit log queries
 */
export interface AuditLogPagination {
  limit: number;
  offset: number;
}

/**
 * Paginated result set for audit logs
 */
export interface AuditLogSearchResult {
  logs: AuditLogEntry[];
  total: number;
  limit: number;
  offset: number;
}

/**
 * Valid category values for validation
 */
export const AUDIT_LOG_CATEGORIES: readonly AuditLogCategory[] = [
  'auth',
  'vehicle',
  'user',
  'system',
  'admin',
] as const;

/**
 * Valid severity values for validation
 */
export const AUDIT_LOG_SEVERITIES: readonly AuditLogSeverity[] = [
  'info',
  'warning',
  'error',
] as const;

/**
 * Type guard for category validation
 */
export function isValidCategory(value: string): value is AuditLogCategory {
  return AUDIT_LOG_CATEGORIES.includes(value as AuditLogCategory);
}

/**
 * Type guard for severity validation
 */
export function isValidSeverity(value: string): value is AuditLogSeverity {
  return AUDIT_LOG_SEVERITIES.includes(value as AuditLogSeverity);
}
