Metadata-Version: 2.4
Name: universal-audit-logs
Version: 1.0.2
Summary: Universal Audit Framework (UAF) — A production-ready, framework-agnostic audit logging SDK for Python.
License: MIT
License-File: LICENSE
Keywords: audit,logging,sdk,fastapi,middleware,postgresql,observability
Author: Sumanth
Author-email: sumanth6633@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: fastapi
Provides-Extra: kafka
Provides-Extra: mongodb
Provides-Extra: postgres
Provides-Extra: sqlite
Requires-Dist: aiokafka (>=0.9,<0.10) ; extra == "kafka" or extra == "all"
Requires-Dist: aiosqlite (>=0.20,<0.21) ; extra == "sqlite" or extra == "all"
Requires-Dist: asyncpg (>=0.29,<0.30) ; extra == "postgres" or extra == "all"
Requires-Dist: cryptography (>=42.0,<43.0)
Requires-Dist: fastapi (>=0.100,<0.101) ; extra == "fastapi" or extra == "all"
Requires-Dist: httpx (>=0.27,<0.28)
Requires-Dist: motor (>=3.3,<4.0) ; extra == "mongodb" or extra == "all"
Requires-Dist: pydantic (>=2.7,<3.0)
Requires-Dist: pydantic-settings (>=2.3,<3.0)
Requires-Dist: sqlalchemy[asyncio] (>=2.0,<3.0) ; extra == "postgres" or extra == "sqlite" or extra == "all"
Requires-Dist: starlette (>=0.27) ; extra == "fastapi" or extra == "all"
Requires-Dist: structlog (>=24.1,<25.0)
Requires-Dist: tenacity (>=8.3,<9.0)
Project-URL: Bug Tracker, https://github.com/rakurthisumanth/audit_logs/issues
Project-URL: Changelog, https://github.com/rakurthisumanth/audit_logs/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/rakurthisumanth/audit_logs#readme
Project-URL: Homepage, https://github.com/rakurthisumanth/audit_logs
Project-URL: Repository, https://github.com/rakurthisumanth/audit_logs
Description-Content-Type: text/markdown

# Universal Audit Framework (UAF) SDK

[![PyPI version](https://badge.fury.io/py/universal-audit-logs.svg)](https://pypi.org/project/universal-audit-logs/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

A production-ready audit logging SDK for Python. Auto-captures WHO did WHAT, WHEN — with zero code in your endpoints.

---

## Installation

```bash
# With FastAPI middleware + PostgreSQL (most common)
pip install universal-audit-logs[fastapi,postgres]

# Core only (REST transport)
pip install universal-audit-logs

# All transports
pip install universal-audit-logs[all]
```

---

## FastAPI Middleware Setup (Recommended)

```python
from fastapi import FastAPI
from starlette.middleware.sessions import SessionMiddleware
from audit_sdk.middleware.enhanced import (
    EnhancedAuditMiddleware,
    EnhancedAuditConfig,
)
from audit_sdk.transport.simple_database import SimpleAuditTransport

app = FastAPI()

# 1. Configure audit transport (writes to PostgreSQL)
transport = SimpleAuditTransport.for_postgres(
    host="localhost",
    port=5432,
    database="audit_db",
    username="your_user",
    password="your_password",
)

# 2. Add audit middleware
app.add_middleware(
    EnhancedAuditMiddleware,
    transport=transport,
    config=EnhancedAuditConfig(
        capture_request_body=True,
        excluded_paths=frozenset({"/health", "/docs", "/openapi.json"}),
    ),
)

# 3. Add session middleware (for user tracking)
app.add_middleware(SessionMiddleware, secret_key="your-secret-key")
```

**Done.** Every endpoint is now automatically audited. No `audit.log()` calls needed anywhere.

---

## User Detection

The middleware auto-detects the logged-in user. Provide a `UserProvider`:

```python
from audit_sdk.middleware.enhanced import EnhancedAuditMiddleware

class SessionUserProvider:
    async def get_user(self, request) -> dict | None:
        user = request.session.get("current_user")
        if user:
            return {
                "user_id": user["id"],
                "username": user["username"],
                "email": user.get("email", ""),
                "roles": user.get("roles", []),
            }
        return None

app.add_middleware(
    EnhancedAuditMiddleware,
    transport=transport,
    user_provider=SessionUserProvider(),
    config=EnhancedAuditConfig(capture_request_body=True),
)
```

---

## What Gets Captured Automatically

| Field | Example |
|-------|---------|
| `performed_by` | `Sumanth` |
| `action` | `CREATE`, `UPDATE`, `DELETE`, `LOGIN` |
| `action_message` | `Sumanth created Employee John` |
| `functionality` | `Employee Management` |
| `performed_on` | `Employee #1` |
| `performed_at` | `2025-07-08 10:30:00+00` |
| `previous_state` | `{"salary": 100000}` |
| `current_state` | `{"salary": 120000}` |
| `changed_fields` | `{"salary": {"old": 100000, "new": 120000}}` |

---

## Transport Options

### PostgreSQL (recommended)

```python
from audit_sdk.transport.simple_database import SimpleAuditTransport

transport = SimpleAuditTransport.for_postgres(
    host="localhost", port=5432,
    database="audit_db", username="user", password="pass",
)
```

### SQLite

```python
transport = SimpleAuditTransport.for_sqlite(path="./audit.db")
```

### MongoDB

```bash
pip install universal-audit-logs[mongodb]
```

```python
from audit_sdk.transport.mongodb import MongoDBTransport

transport = MongoDBTransport(uri="mongodb://localhost:27017", database="audit_db")
```

### REST (HTTP collector)

```python
from audit_sdk import AuditClient, AuditSettings

settings = AuditSettings(endpoint="https://audit.example.com/api/v1/events")
audit = AuditClient(settings=settings)
```

---

## Audit Log Table (auto-created)

```sql
CREATE TABLE audit_log (
    id              VARCHAR(36) PRIMARY KEY,
    performed_by    TEXT NOT NULL,
    action          VARCHAR(100) NOT NULL,
    action_message  TEXT,
    functionality   VARCHAR(200) NOT NULL,
    performed_on    TEXT NOT NULL,
    performed_at    TIMESTAMPTZ NOT NULL,
    previous_state  JSONB,
    current_state   JSONB,
    changed_fields  JSONB,
    http_context    JSONB
);
```

---

## License

MIT - see [LICENSE](LICENSE)

Copyright (c) 2025 Sumanth

