universal-audit-logs 1.0.2__tar.gz

universal_audit_logs-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sumanth <sumanth6633@gmail.com>
+
+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.

universal_audit_logs-1.0.2/PKG-INFO

@@ -0,0 +1,225 @@
+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
+

universal_audit_logs-1.0.2/README.md

@@ -0,0 +1,177 @@
+# 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

universal_audit_logs-1.0.2/audit_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""
+Universal Audit Framework (UAF) SDK
+====================================
+
+A production-ready, framework-agnostic audit logging SDK for Python 3.12+.
+
+Quick-start — REST transport::
+
+    from audit_sdk import AuditClient, AuditSettings
+
+    settings = AuditSettings(endpoint="https://audit.example.com/api/v1/events")
+    audit = AuditClient(settings=settings)
+
+Quick-start — Database transport::
+
+    from audit_sdk import AuditClient
+    from audit_sdk.transport.database import DatabaseTransport
+
+    transport = DatabaseTransport.for_postgres(
+        host="localhost", database="audit_db",
+        username="user", password="pass",
+    )
+    audit = AuditClient(transport=transport)
+
+Quick-start — FastAPI middleware::
+
+    from audit_sdk.middleware.fastapi import AuditMiddleware, AuditMiddlewareConfig
+
+    app.add_middleware(AuditMiddleware, audit_client=audit, config=AuditMiddlewareConfig(...))
+"""
+
+from audit_sdk.audit import AuditClient
+from audit_sdk.config.settings import AuditSettings
+from audit_sdk.core.exceptions import QueueFullError, TransportError
+from audit_sdk.models.audit_event import AuditEvent
+from audit_sdk.utils.retry_manager import RetryManager, RetryMetrics
+
+__all__: list[str] = [
+    # Core
+    "AuditClient",
+    "AuditSettings",
+    "AuditEvent",
+    # Retry
+    "RetryManager",
+    "RetryMetrics",
+    # Exceptions
+    "QueueFullError",
+    "TransportError",
+]
+
+# Optional: FastAPI middleware (requires `pip install universal-audit-logs[fastapi]`)
+try:
+    from audit_sdk.middleware.fastapi import AuditMiddleware, AuditMiddlewareConfig
+
+    __all__ += ["AuditMiddleware", "AuditMiddlewareConfig"]
+except ImportError:
+    pass
+
+# Optional: Database transport (requires `pip install universal-audit-logs[postgres]` or `[sqlite]`)
+try:
+    from audit_sdk.transport.database import DatabaseTransport
+
+    __all__ += ["DatabaseTransport"]
+except ImportError:
+    pass
+
+__version__: str = "1.0.2"