interface AuditLog {
  id: string;
  action_type: string;    // "create", "update", "delete", "export", etc.
  entity_type: string;    // "form", "submission", "user", "settings"
  entity_id: string;
  user_id: string;
  user_email: string;
  user_role: string;
  workspace_id?: string;
  changes?: {
    [field: string]: { before: unknown; after: unknown };
  };
  metadata?: Record<string, unknown>;
  ip_address?: string;    // Anonymized (last octet zeroed)
  user_agent?: string;
  request_id?: string;    // For distributed tracing
  success: boolean;
  error_message?: string;
  created_at: string;
}

import { auditLog } from "@/lib/audit";

await auditLog({
  actionType: "update",
  entityType: "form",
  entityId: formId,
  changes: {
    title: { before: "Old Title", after: "New Title" },
  },
  metadata: { formTitle: "New Title" },
});

import { auditLog, getRequestContext } from "@/lib/audit";
import { headers } from "next/headers";

const requestContext = getRequestContext(await headers());

await auditLog({
  actionType: "export",
  entityType: "submission",
  entityId: "bulk:50",
  metadata: { format: "csv", count: 50 },
  requestContext,
});

import {
  auditFormCreate,
  auditFormPublish,
  auditSettingsChange,
  auditSubmissionStatusChange,
} from "@/lib/audit";

// Form operations
await auditFormCreate(formId, { title, createdBy });
await auditFormPublish(formId, { version: 1 });

// Settings changes
await auditSettingsChange("settings", "system", "system_settings", {
  before: oldSettings,
  after: newSettings,
});

// Submission status
await auditSubmissionStatusChange(
  submissionId,
  { oldStatus: "pending", newStatus: "approved" },
  { formId }
);

// GET /api/audit?page=1&limit=50&actionType=update&entityType=form
const response = await fetch("/api/audit?" + params);
const { logs, total } = await response.json();

-- Find all changes to a form
SELECT * FROM audit_logs
WHERE entity_type = 'form'
  AND entity_id = $1
ORDER BY created_at DESC;

-- Find all actions by a user
SELECT * FROM audit_logs
WHERE user_id = $1
ORDER BY created_at DESC
LIMIT 100;

-- Find all exports (for compliance review)
SELECT * FROM audit_logs
WHERE action_type = 'export'
ORDER BY created_at DESC;

# Download CSV
curl -H "Authorization: Bearer $TOKEN" \
  "https://your-domain.com/api/audit/access-report?format=csv" \
  -o access-review.csv

# Get JSON
curl -H "Authorization: Bearer $TOKEN" \
  "https://your-domain.com/api/audit/access-report"

// /api/cron/audit-cleanup
// Called daily by Vercel cron

// Runs: SELECT * FROM cleanup_expired_audit_logs();
// Returns: { deleted_count, retention_days }

{
  "crons": [
    {
      "path": "/api/cron/audit-cleanup",
      "schedule": "0 3 * * *"
    }
  ]
}

function anonymizeIP(ip: string): string {
  // IPv4: 192.168.1.100 → 192.168.1.0
  // IPv6: 2001:db8:85a3::8a2e:370:7334 → 2001:db8:85a3::
}

-- Only service role can insert
CREATE POLICY "Service role can manage audit logs"
ON audit_logs
FOR ALL
USING (true)
WITH CHECK (true);