simple-module-audit-log 0.0.24__py3-none-any.whl

audit_log/capture.py

@@ -0,0 +1,28 @@
+"""Audit callback that converts AuditRecords into AuditEntry rows."""
+
+from __future__ import annotations
+
+import logging
+
+from simple_module_db.audit import AuditRecord
+from sqlalchemy.orm import Session
+
+from audit_log.models import AuditEntry
+
+logger = logging.getLogger(__name__)
+
+
+def audit_callback(session: Session, records: list[AuditRecord]) -> None:
+    try:
+        for record in records:
+            entry = AuditEntry(
+                entity_type=record.entity_type,
+                entity_id=record.entity_id,
+                action=record.action,
+                changes=record.changes,
+                user_id=record.user_id,
+                correlation_id=record.correlation_id,
+            )
+            session.add(entry)
+    except Exception:
+        logger.exception("Failed to write audit entries")

audit_log/constants.py

@@ -0,0 +1,42 @@
+"""Centralized constants for the Audit Log module."""
+
+from __future__ import annotations
+
+from typing import Final
+
+MODULE_NAME: Final = "AuditLog"
+MODULE_PACKAGE: Final = "audit_log"
+LOCALE_NAMESPACE: Final = MODULE_PACKAGE
+
+API_PREFIX: Final = "/api/audit_log"
+VIEW_PREFIX: Final = "/audit_log"
+
+MENU_LABEL: Final = "Audit Log"
+MENU_URL: Final = VIEW_PREFIX
+MENU_ICON: Final = "scroll-text"
+MENU_ORDER: Final = 210
+
+PERM_GROUP: Final = MODULE_NAME
+PERM_VIEW: Final = "audit_log.view"
+ALL_PERMISSIONS: Final = (PERM_VIEW,)
+
+TABLE_AUDIT_ENTRY: Final = "audit_log_audit_entry"
+
+ACTION_CREATED: Final = "created"
+ACTION_UPDATED: Final = "updated"
+ACTION_DELETED: Final = "deleted"
+ACTION_SOFT_DELETED: Final = "soft_deleted"
+ALL_ACTIONS: Final = (ACTION_CREATED, ACTION_UPDATED, ACTION_DELETED, ACTION_SOFT_DELETED)
+
+ENTITY_TYPE_MAX_LENGTH: Final = 255
+ENTITY_ID_MAX_LENGTH: Final = 255
+ACTION_MAX_LENGTH: Final = 20
+USER_ID_MAX_LENGTH: Final = 255
+CORRELATION_ID_MAX_LENGTH: Final = 255
+
+DEFAULT_PAGE_SIZE: Final = 50
+MAX_PAGE_SIZE: Final = 200
+
+PAGE_BROWSE: Final = f"{MODULE_NAME}/Browse"
+
+STATUS_OK: Final = 200

audit_log/contracts/schemas.py

@@ -0,0 +1,29 @@
+"""SQLModel DTOs for the Audit Log module."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import ConfigDict
+from sqlmodel import SQLModel
+
+
+class AuditEntryRead(SQLModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    entity_type: str
+    entity_id: str
+    action: str
+    changes: list[dict]
+    user_id: str | None = None
+    correlation_id: str | None = None
+    created_at: datetime
+
+
+class AuditEntryList(SQLModel):
+    items: list[AuditEntryRead]
+    total: int
+    page: int
+    page_size: int

audit_log/deps.py

@@ -0,0 +1,20 @@
+"""FastAPI dependencies for the Audit Log module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from audit_log.service import AuditLogService
+
+
+async def get_audit_log_service(
+    db: AsyncSession = Depends(get_db),
+) -> AuditLogService:
+    return AuditLogService(db)
+
+
+AuditLogServiceDep = Annotated[AuditLogService, Depends(get_audit_log_service)]

audit_log/endpoints/api.py

@@ -0,0 +1,40 @@
+"""REST API endpoints for the Audit Log module."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, Query
+from simple_module_hosting.permissions import RequiresPermission
+
+from audit_log.constants import DEFAULT_PAGE_SIZE, PERM_VIEW
+from audit_log.contracts.schemas import AuditEntryList
+from audit_log.deps import AuditLogServiceDep
+
+router = APIRouter()
+
+_VIEW = [Depends(RequiresPermission(PERM_VIEW))]
+
+
+@router.get("/", response_model=AuditEntryList, dependencies=_VIEW)
+async def list_audit_entries(
+    service: AuditLogServiceDep,
+    entity_type: str | None = Query(default=None),
+    entity_id: str | None = Query(default=None),
+    action: str | None = Query(default=None),
+    user_id: str | None = Query(default=None),
+    from_date: datetime | None = Query(default=None),
+    to_date: datetime | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=DEFAULT_PAGE_SIZE, ge=1, le=200),
+) -> AuditEntryList:
+    return await service.list_entries(
+        entity_type=entity_type,
+        entity_id=entity_id,
+        action=action,
+        user_id=user_id,
+        from_date=from_date,
+        to_date=to_date,
+        page=page,
+        page_size=page_size,
+    )

audit_log/endpoints/views.py

@@ -0,0 +1,82 @@
+"""Inertia view endpoints for the Audit Log admin UI."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, Query
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from audit_log.constants import (
+    DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE,
+    PAGE_BROWSE,
+    PERM_VIEW,
+)
+from audit_log.deps import AuditLogServiceDep
+
+router = APIRouter()
+
+
+def _safe_int(raw: str | None, default: int) -> int:
+    """Parse *raw* as an integer, returning *default* on failure."""
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (ValueError, TypeError):
+        return default
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_VIEW))],
+)
+async def browse(
+    inertia: InertiaDep,
+    service: AuditLogServiceDep,
+    entity_type: str | None = Query(default=None),
+    entity_id: str | None = Query(default=None),
+    action: str | None = Query(default=None),
+    user_id: str | None = Query(default=None),
+    from_date: datetime | None = Query(default=None),
+    to_date: datetime | None = Query(default=None),
+    page: str | None = Query(default=None),
+    page_size: str | None = Query(default=None),
+) -> InertiaResponse:
+    # Sanitize pagination — never raise a validation error for bad values.
+    page_int = max(_safe_int(page, 1), 1)
+    page_size_int = max(1, min(_safe_int(page_size, DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE))
+    result = await service.list_entries(
+        entity_type=entity_type,
+        entity_id=entity_id,
+        action=action,
+        user_id=user_id,
+        from_date=from_date,
+        to_date=to_date,
+        page=page_int,
+        page_size=page_size_int,
+    )
+    entity_types = await service.distinct_entity_types()
+
+    return await inertia.render(
+        PAGE_BROWSE,
+        {
+            "items": [item.model_dump(mode="json") for item in result.items],
+            "total": result.total,
+            "page": result.page,
+            "page_size": result.page_size,
+            "entity_types": entity_types,
+            "filters": {
+                "entity_type": entity_type,
+                "entity_id": entity_id,
+                "action": action,
+                "user_id": user_id,
+                "from_date": from_date.isoformat() if from_date else None,
+                "to_date": to_date.isoformat() if to_date else None,
+            },
+        },
+    )

audit_log/locales/en.json

@@ -0,0 +1,43 @@
+{
+  "browse": {
+    "title": "Audit Log",
+    "description": "Track all entity changes across the system.",
+    "empty_title": "No audit entries",
+    "empty_description": "Changes to entities will appear here automatically.",
+    "showing": "Showing {from}–{to} of {total} entries",
+    "previous": "Previous",
+    "next": "Next"
+  },
+  "filters": {
+    "entity_type_label": "Entity Type",
+    "entity_type_all": "All types",
+    "action_label": "Action",
+    "action_all": "All actions",
+    "user_label": "User ID",
+    "user_placeholder": "Filter by user…",
+    "from_date_label": "From",
+    "to_date_label": "To",
+    "apply": "Apply",
+    "clear": "Clear"
+  },
+  "table": {
+    "timestamp": "Timestamp",
+    "action": "Action",
+    "entity": "Entity",
+    "user": "User",
+    "changes": "Changes"
+  },
+  "actions": {
+    "created": "Created",
+    "updated": "Updated",
+    "deleted": "Deleted",
+    "soft_deleted": "Archived"
+  },
+  "changes": {
+    "fields_set": "{count} fields set",
+    "show_more": "Show {count} more…",
+    "show_less": "Show less",
+    "system_user": "System",
+    "no_changes": "—"
+  }
+}

audit_log/models.py

@@ -0,0 +1,47 @@
+"""SQLModel table for the Audit Log module."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from simple_module_db.base import create_module_base
+from sqlalchemy import JSON, DateTime, Index, func
+from sqlmodel import Column, Field
+
+from audit_log.constants import (
+    ACTION_MAX_LENGTH,
+    CORRELATION_ID_MAX_LENGTH,
+    ENTITY_ID_MAX_LENGTH,
+    ENTITY_TYPE_MAX_LENGTH,
+    MODULE_PACKAGE,
+    TABLE_AUDIT_ENTRY,
+    USER_ID_MAX_LENGTH,
+)
+
+Base = create_module_base(MODULE_PACKAGE)
+
+
+class AuditEntry(Base, table=True):  # ty: ignore[unsupported-base]
+    __tablename__ = TABLE_AUDIT_ENTRY
+    __audit_exclude__ = True
+
+    __table_args__ = (
+        Index("ix_audit_entry_entity_type", "entity_type"),
+        Index("ix_audit_entry_entity_id", "entity_id"),
+        Index("ix_audit_entry_user_id", "user_id"),
+        Index("ix_audit_entry_created_at", "created_at"),
+    )
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    entity_type: str = Field(max_length=ENTITY_TYPE_MAX_LENGTH)
+    entity_id: str = Field(max_length=ENTITY_ID_MAX_LENGTH)
+    action: str = Field(max_length=ACTION_MAX_LENGTH)
+    changes: dict | list = Field(default_factory=list, sa_column=Column(JSON))
+    user_id: str | None = Field(default=None, max_length=USER_ID_MAX_LENGTH)
+    correlation_id: str | None = Field(default=None, max_length=CORRELATION_ID_MAX_LENGTH)
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"server_default": func.now()},
+    )

audit_log/module.py

@@ -0,0 +1,69 @@
+"""Audit Log module definition."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from audit_log.constants import (
+    ALL_PERMISSIONS,
+    API_PREFIX,
+    LOCALE_NAMESPACE,
+    MENU_ICON,
+    MENU_LABEL,
+    MENU_ORDER,
+    MENU_URL,
+    MODULE_NAME,
+    PERM_GROUP,
+    VIEW_PREFIX,
+)
+
+_MODULE_USERS = "Users"
+
+
+class AuditLogModule(ModuleBase):
+    meta = ModuleMeta(
+        name=MODULE_NAME,
+        route_prefix=API_PREFIX,
+        view_prefix=VIEW_PREFIX,
+        depends_on=[_MODULE_USERS],
+    )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from audit_log.endpoints.api import router as api
+        from audit_log.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=MENU_LABEL,
+                url=MENU_URL,
+                icon=MENU_ICON,
+                order=MENU_ORDER,
+                section=MenuSection.SIDEBAR,
+                group="System",
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(PERM_GROUP, list(ALL_PERMISSIONS))
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from audit_log.capture import audit_callback
+
+        app.state.sm.db.audit_callback = audit_callback
+
+    async def on_shutdown(self, app: FastAPI) -> None:
+        app.state.sm.db.audit_callback = None
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {LOCALE_NAMESPACE: base}

audit_log/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/audit-log",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Audit Log module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

audit_log/pages/Browse.tsx

@@ -0,0 +1,245 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { ScrollText } from 'lucide-react';
+import type React from 'react';
+import { useState } from 'react';
+import { ALL, FilterBar, type FilterState } from './components/FilterBar';
+
+interface Change {
+  field: string;
+  old?: unknown;
+  new?: unknown;
+}
+
+interface AuditEntryRead {
+  id: string;
+  entity_type: string;
+  entity_id: string;
+  action: 'created' | 'updated' | 'deleted' | 'soft_deleted';
+  changes: Change[];
+  user_id: string | null;
+  correlation_id: string | null;
+  created_at: string;
+}
+
+interface Filters {
+  entity_type: string | null;
+  action: string | null;
+  user_id: string | null;
+  from_date: string | null;
+  to_date: string | null;
+}
+
+interface Props {
+  items: AuditEntryRead[];
+  total: number;
+  page: number;
+  page_size: number;
+  entity_types: string[];
+  filters: Filters;
+}
+
+const ACTION_BADGE: Record<string, string> = {
+  created: 'border-green-200 bg-green-50 text-green-700',
+  updated: 'border-blue-200 bg-blue-50 text-blue-700',
+  deleted: 'border-red-200 bg-red-50 text-red-700',
+  soft_deleted: 'border-amber-200 bg-amber-50 text-amber-700',
+};
+const TH = 'sm:px-6 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground';
+
+function ChangesList({ entry }: { entry: AuditEntryRead }) {
+  const { t } = useT();
+  const [expanded, setExpanded] = useState(false);
+  if (entry.action === 'deleted' || entry.action === 'soft_deleted')
+    return <span className="text-muted-foreground">{t(keys.audit_log.changes.no_changes)}</span>;
+  if (entry.action === 'created')
+    return (
+      <span className="text-muted-foreground">
+        {t(keys.audit_log.changes.fields_set, { count: entry.changes.length })}
+      </span>
+    );
+
+  const visible = expanded ? entry.changes : entry.changes.slice(0, 3);
+  const remaining = entry.changes.length - 3;
+  return (
+    <div className="space-y-0.5 text-xs">
+      {visible.map((c) => (
+        <div key={c.field} className="font-mono">
+          <span className="font-semibold">{c.field}</span>{' '}
+          <span className="text-muted-foreground">
+            {String(c.old ?? '""')}&rarr;{String(c.new ?? '""')}
+          </span>
+        </div>
+      ))}
+      {remaining > 0 && (
+        <button
+          type="button"
+          className="text-primary-700 hover:underline text-xs"
+          onClick={() => setExpanded(!expanded)}
+        >
+          {expanded
+            ? t(keys.audit_log.changes.show_less)
+            : t(keys.audit_log.changes.show_more, { count: remaining })}
+        </button>
+      )}
+    </div>
+  );
+}
+
+function Browse() {
+  const { items, total, page, page_size, entity_types, filters } = usePage<{ props: Props }>()
+    .props as unknown as Props;
+  const { t } = useT();
+
+  const [state, setState] = useState<FilterState>({
+    entityType: filters.entity_type ?? ALL,
+    action: filters.action ?? ALL,
+    userId: filters.user_id ?? '',
+    fromDate: filters.from_date ?? '',
+    toDate: filters.to_date ?? '',
+  });
+
+  function navigate(next: FilterState, nextPage = 1) {
+    const p: Record<string, string> = {};
+    if (next.entityType && next.entityType !== ALL) p.entity_type = next.entityType;
+    if (next.action && next.action !== ALL) p.action = next.action;
+    if (next.userId) p.user_id = next.userId;
+    if (next.fromDate) p.from_date = next.fromDate;
+    if (next.toDate) p.to_date = next.toDate;
+    if (nextPage > 1) p.page = String(nextPage);
+    if (page_size !== 50) p.page_size = String(page_size);
+    router.visit(`/audit_log?${new URLSearchParams(p).toString()}`);
+  }
+
+  function handleClear() {
+    const cleared: FilterState = {
+      entityType: ALL,
+      action: ALL,
+      userId: '',
+      fromDate: '',
+      toDate: '',
+    };
+    setState(cleared);
+    navigate(cleared);
+  }
+
+  const totalPages = Math.ceil(total / page_size);
+  const from = total === 0 ? 0 : (page - 1) * page_size + 1;
+  const to = Math.min(page * page_size, total);
+
+  return (
+    <>
+      <Head title="Audit Log" />
+      <PageShell
+        title={t(keys.audit_log.browse.title)}
+        description={t(keys.audit_log.browse.description)}
+      >
+        <FilterBar
+          state={state}
+          entity_types={entity_types}
+          onChange={setState}
+          onSubmit={() => navigate(state)}
+          onClear={handleClear}
+        />
+
+        {items.length === 0 ? (
+          <Card className="border-border">
+            <div className="flex flex-col items-center gap-2 py-16 text-muted-foreground">
+              <ScrollText className="size-8" />
+              <h2 className="text-base font-semibold text-foreground font-[var(--font-display)]">
+                {t(keys.audit_log.browse.empty_title)}
+              </h2>
+              <p className="text-sm">{t(keys.audit_log.browse.empty_description)}</p>
+            </div>
+          </Card>
+        ) : (
+          <Card className="border-border overflow-hidden p-0">
+            <Table>
+              <TableHeader className="bg-secondary/40">
+                <TableRow>
+                  <TableHead className={TH}>{t(keys.audit_log.table.timestamp)}</TableHead>
+                  <TableHead className={TH}>{t(keys.audit_log.table.action)}</TableHead>
+                  <TableHead className={TH}>{t(keys.audit_log.table.entity)}</TableHead>
+                  <TableHead className={`${TH} hidden sm:table-cell`}>
+                    {t(keys.audit_log.table.user)}
+                  </TableHead>
+                  <TableHead className={`${TH} hidden md:table-cell`}>
+                    {t(keys.audit_log.table.changes)}
+                  </TableHead>
+                </TableRow>
+              </TableHeader>
+              <TableBody>
+                {items.map((entry) => (
+                  <TableRow key={entry.id} className="hover:bg-secondary/40">
+                    <TableCell className="sm:px-6 whitespace-nowrap text-sm tabular-nums text-muted-foreground">
+                      {new Date(entry.created_at).toLocaleString()}
+                    </TableCell>
+                    <TableCell className="sm:px-6">
+                      <Badge variant="outline" className={ACTION_BADGE[entry.action] ?? ''}>
+                        {t(keys.audit_log.actions[entry.action])}
+                      </Badge>
+                    </TableCell>
+                    <TableCell className="sm:px-6">
+                      <span className="font-medium text-sm">{entry.entity_type}</span>
+                      <span className="ml-1 font-mono text-xs text-muted-foreground">
+                        {entry.entity_id}
+                      </span>
+                    </TableCell>
+                    <TableCell className="sm:px-6 hidden sm:table-cell text-sm text-muted-foreground">
+                      {entry.user_id ?? t(keys.audit_log.changes.system_user)}
+                    </TableCell>
+                    <TableCell className="sm:px-6 hidden md:table-cell">
+                      <ChangesList entry={entry} />
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          </Card>
+        )}
+
+        {totalPages > 1 && (
+          <div className="mt-4 flex items-center justify-between">
+            <span className="text-sm text-muted-foreground">
+              {t(keys.audit_log.browse.showing, { from, to, total })}
+            </span>
+            <div className="flex items-center gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={page <= 1}
+                onClick={() => navigate(state, page - 1)}
+              >
+                {t(keys.audit_log.browse.previous)}
+              </Button>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={page >= totalPages}
+                onClick={() => navigate(state, page + 1)}
+              >
+                {t(keys.audit_log.browse.next)}
+              </Button>
+            </div>
+          </div>
+        )}
+      </PageShell>
+    </>
+  );
+}
+
+Browse.layout = (page: React.ReactNode) => <AuthenticatedLayout>{page}</AuthenticatedLayout>;
+export default Browse;

audit_log/pages/components/FilterBar.tsx

@@ -0,0 +1,126 @@
+import { keys, useT } from '@simple-module-py/i18n';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@simple-module-py/ui/components/ui/select';
+
+export const ALL = '__all__';
+const ACTIONS = ['created', 'updated', 'deleted', 'soft_deleted'] as const;
+
+export interface FilterState {
+  entityType: string;
+  action: string;
+  userId: string;
+  fromDate: string;
+  toDate: string;
+}
+
+interface FilterBarProps {
+  state: FilterState;
+  entity_types: string[];
+  onChange: (next: FilterState) => void;
+  onSubmit: () => void;
+  onClear: () => void;
+}
+
+export function FilterBar({ state, entity_types, onChange, onSubmit, onClear }: FilterBarProps) {
+  const { t } = useT();
+  const set = (patch: Partial<FilterState>) => onChange({ ...state, ...patch });
+
+  return (
+    <Card className="mb-4 p-4">
+      <form
+        className="flex flex-wrap items-end gap-3"
+        onSubmit={(e) => {
+          e.preventDefault();
+          onSubmit();
+        }}
+      >
+        <div className="min-w-[140px]">
+          <label htmlFor="audit-entity-type" className="block text-sm font-medium mb-1">
+            {t(keys.audit_log.filters.entity_type_label)}
+          </label>
+          <Select value={state.entityType} onValueChange={(v) => set({ entityType: v })}>
+            <SelectTrigger id="audit-entity-type" size="sm" className="w-full">
+              <SelectValue placeholder={t(keys.audit_log.filters.entity_type_all)} />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value={ALL}>{t(keys.audit_log.filters.entity_type_all)}</SelectItem>
+              {entity_types.map((et) => (
+                <SelectItem key={et} value={et}>
+                  {et}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <div className="min-w-[130px]">
+          <label htmlFor="audit-action" className="block text-sm font-medium mb-1">
+            {t(keys.audit_log.filters.action_label)}
+          </label>
+          <Select value={state.action} onValueChange={(v) => set({ action: v })}>
+            <SelectTrigger id="audit-action" size="sm" className="w-full">
+              <SelectValue placeholder={t(keys.audit_log.filters.action_all)} />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value={ALL}>{t(keys.audit_log.filters.action_all)}</SelectItem>
+              {ACTIONS.map((a) => (
+                <SelectItem key={a} value={a}>
+                  {t(keys.audit_log.actions[a])}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <div className="min-w-[160px]">
+          <label htmlFor="audit-user-id" className="block text-sm font-medium mb-1">
+            {t(keys.audit_log.filters.user_label)}
+          </label>
+          <Input
+            id="audit-user-id"
+            value={state.userId}
+            onChange={(e) => set({ userId: e.target.value })}
+            placeholder={t(keys.audit_log.filters.user_placeholder)}
+            className="h-8 text-sm"
+          />
+        </div>
+        <div className="min-w-[140px]">
+          <label htmlFor="audit-from-date" className="block text-sm font-medium mb-1">
+            {t(keys.audit_log.filters.from_date_label)}
+          </label>
+          <Input
+            id="audit-from-date"
+            type="datetime-local"
+            value={state.fromDate}
+            onChange={(e) => set({ fromDate: e.target.value })}
+            className="h-8 text-sm"
+          />
+        </div>
+        <div className="min-w-[140px]">
+          <label htmlFor="audit-to-date" className="block text-sm font-medium mb-1">
+            {t(keys.audit_log.filters.to_date_label)}
+          </label>
+          <Input
+            id="audit-to-date"
+            type="datetime-local"
+            value={state.toDate}
+            onChange={(e) => set({ toDate: e.target.value })}
+            className="h-8 text-sm"
+          />
+        </div>
+        <Button type="submit" size="sm">
+          {t(keys.audit_log.filters.apply)}
+        </Button>
+        <Button type="button" variant="ghost" size="sm" onClick={onClear}>
+          {t(keys.audit_log.filters.clear)}
+        </Button>
+      </form>
+    </Card>
+  );
+}

audit_log/service.py

@@ -0,0 +1,82 @@
+"""Read-only query service for audit log entries."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from audit_log.constants import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from audit_log.contracts.schemas import AuditEntryList, AuditEntryRead
+from audit_log.models import AuditEntry
+
+
+class AuditLogService:
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def list_entries(
+        self,
+        *,
+        entity_type: str | None = None,
+        entity_id: str | None = None,
+        action: str | None = None,
+        user_id: str | None = None,
+        from_date: datetime | None = None,
+        to_date: datetime | None = None,
+        page: int = 1,
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> AuditEntryList:
+        page_size = min(max(page_size, 1), MAX_PAGE_SIZE)
+        page = max(page, 1)
+
+        conditions = []
+        if entity_type:
+            conditions.append(AuditEntry.entity_type == entity_type)
+        if entity_id:
+            conditions.append(AuditEntry.entity_id == entity_id)
+        if action:
+            conditions.append(AuditEntry.action == action)
+        if user_id:
+            conditions.append(AuditEntry.user_id == user_id)
+        if from_date:
+            conditions.append(AuditEntry.created_at >= from_date)
+        if to_date:
+            conditions.append(AuditEntry.created_at <= to_date)
+
+        # Select only AuditEntryRead's columns (plain rows, no ORM hydration) and
+        # count the same conditions directly — avoids hydrating full AuditEntry
+        # objects per page and the subquery wrapper around the count.
+        cols = select(
+            AuditEntry.id,
+            AuditEntry.entity_type,
+            AuditEntry.entity_id,
+            AuditEntry.action,
+            AuditEntry.changes,
+            AuditEntry.user_id,
+            AuditEntry.correlation_id,
+            AuditEntry.created_at,
+        )
+        count_stmt = select(func.count()).select_from(AuditEntry)
+        for cond in conditions:
+            cols = cols.where(cond)
+            count_stmt = count_stmt.where(cond)
+
+        total = (await self.db.execute(count_stmt)).scalar_one()
+
+        offset = (page - 1) * page_size
+        stmt = (
+            cols.order_by(AuditEntry.created_at.desc(), AuditEntry.id)
+            .offset(offset)
+            .limit(page_size)
+        )
+        rows = (await self.db.execute(stmt)).all()
+        items = [AuditEntryRead(**row._mapping) for row in rows]
+
+        return AuditEntryList(items=items, total=total, page=page, page_size=page_size)
+
+    async def distinct_entity_types(self) -> list[str]:
+        stmt = select(AuditEntry.entity_type).distinct().order_by(AuditEntry.entity_type)
+        result = await self.db.execute(stmt)
+        return list(result.scalars())

simple_module_audit_log-0.0.24.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: simple_module_audit_log
+Version: 0.0.24
+Summary: Automatic field-level audit trail for all SQLModel entities
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit-log,change-tracking,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.24
+Requires-Dist: simple-module-db==0.0.24
+Requires-Dist: simple-module-hosting==0.0.24
+Description-Content-Type: text/markdown
+
+# simple_module_audit_log
+
+Automatic field-level audit trail for all SQLModel entities in [simple_module](https://github.com/antosubash/simple_module_python) apps. Every create / update / delete / soft-delete is captured in the `audit_log_audit_entry` table with the changed fields, the user who made the change, and the request correlation id — no instrumentation required in module code.
+
+## Install
+
+```bash
+pip install simple_module_audit_log
+```
+
+Add `simple_module_audit_log` to your host's dependencies and the entry point will be discovered automatically.
+
+## What it provides
+
+- Two-phase capture (`before_flush` snapshots diffs, `after_flush_postexec` resolves DB-assigned primary keys) so integer-PK entities record the real id, not the empty string.
+- `AuditEntry` SQLModel table with indexed `entity_type`, `entity_id`, `user_id`, `created_at` columns.
+- `GET /api/audit_log/` REST endpoint with `entity_type`, `entity_id`, `action`, `user_id`, `from_date`, `to_date`, paging filters.
+- `/audit_log` Inertia browse page with the same filter set rendered as a table, gated by the `audit_log.view` permission.
+- Opt-outs: set `__audit_exclude__ = True` on a model to skip it entirely, or `__audit_exclude_fields__ = {"password_hash"}` to skip specific columns. `AuditMixin` / `SoftDeleteMixin` bookkeeping fields are excluded automatically.
+
+## Usage
+
+Install the module and grant the `audit_log.view` permission to your admin role. Audit entries appear automatically for every entity that does not opt out.
+
+To exclude a sensitive column:
+
+```python
+from typing import ClassVar
+from sqlmodel import Field
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+
+Base = create_module_base("auth")
+
+
+class Credential(Base, AuditMixin, table=True):
+    __audit_exclude_fields__: ClassVar[set[str]] = {"password_hash"}
+
+    id: int | None = Field(default=None, primary_key=True)
+    user_id: str
+    password_hash: str
+```
+
+To opt a whole table out:
+
+```python
+class Cache(Base, table=True):
+    __audit_exclude__ = True
+    ...
+```
+
+## License
+
+MIT

simple_module_audit_log-0.0.24.dist-info/RECORD

@@ -0,0 +1,22 @@
+audit_log/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audit_log/capture.py,sha256=sxF4uOLQiNhSo7aU2JocHhIPhE6qwFA_R3ooJl4svKY,821
+audit_log/constants.py,sha256=q3vGKFfn3BuLOG3d8dGloGizfWI8ByVOCG65-bOteDc,1115
+audit_log/deps.py,sha256=bymJeX2S7Bo7hwfh8CG-A8ygd0zDj_n6iEx-yxY9wG0,494
+audit_log/models.py,sha256=fYc0xVj86THtg60_U4fq0xgSnbLOGDK4ALFXXh01L3o,1606
+audit_log/module.py,sha256=ol92qEKtM4CZRjQiZRKuvgA-Q1sPvHC2zxrfXdLpGuA,1984
+audit_log/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audit_log/service.py,sha256=pMo4Mieo_NQNOKQU8Vhkba5YBYfXJoCnU-G8XxuoxdQ,2893
+audit_log/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audit_log/contracts/schemas.py,sha256=TPWMP2-ffjwKuyxo9HfB_wPHkBn2WyjEid350dA2NFI,581
+audit_log/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audit_log/endpoints/api.py,sha256=K1gOYEa-tbr8GMfEKKOYEeTdRmhGzAJ553SfSU-rVFo,1284
+audit_log/endpoints/views.py,sha256=rIx9-qOTlhknY984DesvanYFlM1OFBitT3b7IzB8Nm0,2550
+audit_log/locales/en.json,sha256=gpZUFrE4Y3iJyoZ3OmG7AdqN8fgWRC1eUHjBhtIHl50,1127
+audit_log/pages/Browse.tsx,sha256=ro5p-gza544UXVHA03_byA47cwZ3OFShTgvmf5WZrdI,8731
+audit_log/pages/components/FilterBar.tsx,sha256=yr9WkG_E1mG-0wyVcJiPY5Wkw4rw3VYx2DtqRz6W8nc,4494
+audit_log/package.json,sha256=vJl7D1od7Ad2txIZ2nc8bjPLOykC-BpArUaQc-xfano,381
+simple_module_audit_log-0.0.24.dist-info/METADATA,sha256=sf_IOwLXXtzRZ58ZReWtGnN8hpWf_E7_EDLfIEOHDPk,3373
+simple_module_audit_log-0.0.24.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+simple_module_audit_log-0.0.24.dist-info/entry_points.txt,sha256=2M-_3LD-RclZjaRXjVjmH2Pr6eOxMxTnf8zaCs2di-Q,60
+simple_module_audit_log-0.0.24.dist-info/licenses/LICENSE,sha256=uM3NiXzdM3GqHSyKCZdIgOtd0CArtlKOfAmG0hvZe3M,1068
+simple_module_audit_log-0.0.24.dist-info/RECORD,,

simple_module_audit_log-0.0.24.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_audit_log-0.0.24.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+audit_log = audit_log.module:AuditLogModule

simple_module_audit_log-0.0.24.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.