auditX 0.1.0__py3-none-any.whl

auditx/__init__.py

@@ -0,0 +1,79 @@
+"""
+auditX — ERP-grade audit logging for trading and service businesses.
+
+Install:
+    pip install auditX
+
+Quick start:
+    from auditx import audit, RequestContext, BusinessModule, AuditAction
+
+    RequestContext.set(user="admin", company_id="CO-001", branch_id="BR-YGN")
+    audit.log_transaction(
+        "Sales invoice posted",
+        module=BusinessModule.SALES,
+        action=AuditAction.POST,
+        reference_no="SI-2026-0042",
+        amount=1_250_000,
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from auditx.core import (
+    AuditAction,
+    AuditEntry,
+    AuditLogger,
+    BusinessModule,
+    LogLevel,
+    RequestContext,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "AuditAction",
+    "AuditEntry",
+    "AuditLogger",
+    "BusinessModule",
+    "LogLevel",
+    "RequestContext",
+    "audit",
+    "configure",
+    "create_logger",
+]
+
+_default_logger: Optional[AuditLogger] = None
+
+
+def create_logger(**kwargs: Any) -> AuditLogger:
+    """Create a new AuditLogger instance with custom settings."""
+    return AuditLogger(**kwargs)
+
+
+def configure(**kwargs: Any) -> AuditLogger:
+    """Replace the global `audit` singleton (e.g. set log_dir, disable console)."""
+    global _default_logger
+    _default_logger = AuditLogger(**kwargs)
+    return _default_logger
+
+
+def _get_default_logger() -> AuditLogger:
+    global _default_logger
+    if _default_logger is None:
+        _default_logger = AuditLogger(log_dir="logs")
+    return _default_logger
+
+
+class _AuditProxy:
+    """Lazy proxy so `from auditx import audit` uses the configured singleton."""
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(_get_default_logger(), name)
+
+    def __repr__(self) -> str:
+        return repr(_get_default_logger())
+
+
+audit = _AuditProxy()

auditx/__main__.py

@@ -0,0 +1,75 @@
+"""Run demo: python -m auditx"""
+
+from auditx.core import AuditAction, BusinessModule
+from auditx import RequestContext, audit
+
+
+def main() -> None:
+    RequestContext.set(
+        user="admin",
+        user_role="manager",
+        company_id="CO-001",
+        branch_id="BR-YGN",
+        ip="192.168.1.10",
+    )
+
+    print("auditX demo — writing logs to ./logs/\n")
+
+    audit.log_security("User login successful", action=AuditAction.LOGIN, user="admin", success=True)
+
+    audit.log_transaction(
+        "Sales invoice posted",
+        module=BusinessModule.SALES,
+        action=AuditAction.POST,
+        reference_no="SI-2026-0042",
+        amount=1_250_000,
+        entity_type="sales_invoice",
+        entity_id="inv-42",
+        party="Golden Trading Co.",
+    )
+
+    audit.log_inventory(
+        "Stock issued for sales order",
+        action=AuditAction.TRANSFER,
+        product_id="SKU-1001",
+        product_name="LED Panel 24W",
+        quantity=50,
+        warehouse_id="WH-MAIN",
+        reference_no="SI-2026-0042",
+    )
+
+    audit.log_service(
+        "Service job completed",
+        action=AuditAction.UPDATE,
+        job_id="SVC-889",
+        customer_id="CUST-220",
+        technician="U Kyaw",
+        service_type="AC Maintenance",
+        status_label="completed",
+        amount=85_000,
+    )
+
+    audit.log_change(
+        "Customer credit limit updated",
+        module=BusinessModule.CRM,
+        action=AuditAction.UPDATE,
+        entity_type="customer",
+        entity_id="CUST-220",
+        old_values={"credit_limit": 500_000},
+        new_values={"credit_limit": 1_000_000},
+    )
+
+    for _ in range(7):
+        audit.log_security(
+            "Failed login attempt",
+            action=AuditAction.LOGIN,
+            user="attacker",
+            ip="192.168.1.50",
+            success=False,
+        )
+
+    print("\nDone. Check logs/audit.jsonl and logs/security.jsonl")
+
+
+if __name__ == "__main__":
+    main()

auditx/core.py

@@ -0,0 +1,564 @@
+"""Core audit logger implementation for auditX."""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import socket
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+try:
+    from colorama import Fore, init
+
+    init(autoreset=True)
+    _COLORAMA = True
+except ImportError:
+    _COLORAMA = False
+    Fore = type("Fore", (), {"GREEN": "", "YELLOW": "", "RED": "", "CYAN": "", "WHITE": "", "MAGENTA": "", "BLUE": ""})()
+
+
+class LogLevel(str, Enum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    NORMAL = "NORMAL"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+    AUDIT = "AUDIT"
+    SECURITY = "SECURITY"
+
+
+class BusinessModule(str, Enum):
+    AUTH = "auth"
+    SALES = "sales"
+    PURCHASE = "purchase"
+    INVENTORY = "inventory"
+    ACCOUNTING = "accounting"
+    SERVICE = "service"
+    CRM = "crm"
+    HR = "hr"
+    REPORTING = "reporting"
+    SYSTEM = "system"
+
+
+class AuditAction(str, Enum):
+    CREATE = "CREATE"
+    READ = "READ"
+    UPDATE = "UPDATE"
+    DELETE = "DELETE"
+    APPROVE = "APPROVE"
+    REJECT = "REJECT"
+    VOID = "VOID"
+    POST = "POST"
+    PAYMENT = "PAYMENT"
+    REFUND = "REFUND"
+    TRANSFER = "TRANSFER"
+    ADJUST = "ADJUST"
+    LOGIN = "LOGIN"
+    LOGOUT = "LOGOUT"
+    EXPORT = "EXPORT"
+    IMPORT = "IMPORT"
+
+
+@dataclass
+class AuditEntry:
+    timestamp: str
+    level: str
+    module: str
+    action: str
+    description: str
+    user: str = "SYSTEM"
+    user_role: str = ""
+    company_id: str = ""
+    branch_id: str = ""
+    entity_type: str = ""
+    entity_id: str = ""
+    reference_no: str = ""
+    amount: Optional[float] = None
+    currency: str = "MMK"
+    old_values: dict[str, Any] = field(default_factory=dict)
+    new_values: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    request_id: str = ""
+    session_id: str = ""
+    ip: str = ""
+    hostname: str = ""
+    method: str = ""
+    endpoint: str = ""
+    status: int = 0
+    success: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        return {k: v for k, v in data.items() if v not in (None, "", {}, [])}
+
+
+class RequestContext:
+    """Carries user and tenant context across a request or background job."""
+
+    _local = threading.local()
+
+    @classmethod
+    def set(
+        cls,
+        *,
+        user: str = "SYSTEM",
+        user_role: str = "",
+        company_id: str = "",
+        branch_id: str = "",
+        session_id: str = "",
+        request_id: str = "",
+        ip: str = "",
+    ) -> None:
+        cls._local.user = user
+        cls._local.user_role = user_role
+        cls._local.company_id = company_id
+        cls._local.branch_id = branch_id
+        cls._local.session_id = session_id
+        cls._local.request_id = request_id or str(uuid.uuid4())
+        cls._local.ip = ip
+
+    @classmethod
+    def get(cls) -> dict[str, str]:
+        return {
+            "user": getattr(cls._local, "user", "SYSTEM"),
+            "user_role": getattr(cls._local, "user_role", ""),
+            "company_id": getattr(cls._local, "company_id", ""),
+            "branch_id": getattr(cls._local, "branch_id", ""),
+            "session_id": getattr(cls._local, "session_id", ""),
+            "request_id": getattr(cls._local, "request_id", ""),
+            "ip": getattr(cls._local, "ip", ""),
+        }
+
+    @classmethod
+    def clear(cls) -> None:
+        for attr in ("user", "user_role", "company_id", "branch_id", "session_id", "request_id", "ip"):
+            if hasattr(cls._local, attr):
+                delattr(cls._local, attr)
+
+
+class AuditLogger:
+    """
+    ERP audit logger with structured JSON trails, console output, and domain helpers.
+
+    Log files (under log_dir):
+      - audit.jsonl    — immutable audit trail (one JSON object per line)
+      - app.log        — human-readable application log
+      - security.jsonl — security-sensitive events
+    """
+
+    _LEVEL_COLORS = {
+        LogLevel.DEBUG.value: Fore.WHITE,
+        LogLevel.INFO.value: Fore.CYAN,
+        LogLevel.NORMAL.value: Fore.GREEN,
+        LogLevel.WARNING.value: Fore.YELLOW,
+        LogLevel.ERROR.value: Fore.RED,
+        LogLevel.CRITICAL.value: Fore.RED,
+        LogLevel.AUDIT.value: Fore.MAGENTA,
+        LogLevel.SECURITY.value: Fore.RED,
+        "EXTREME": Fore.RED,
+    }
+
+    _METHOD_COLORS = {
+        "GET": Fore.CYAN,
+        "POST": Fore.GREEN,
+        "PUT": Fore.YELLOW,
+        "PATCH": Fore.YELLOW,
+        "DELETE": Fore.RED,
+    }
+
+    def __init__(
+        self,
+        log_dir: str | Path = "logs",
+        app_log_file: str = "app.log",
+        audit_log_file: str = "audit.jsonl",
+        security_log_file: str = "security.jsonl",
+        max_file_bytes: int = 10 * 1024 * 1024,
+        backup_count: int = 5,
+        console: bool = True,
+        on_audit: Optional[Callable[[AuditEntry], None]] = None,
+    ):
+        self.log_dir = Path(log_dir)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+        self.app_log_path = self.log_dir / app_log_file
+        self.audit_log_path = self.log_dir / audit_log_file
+        self.security_log_path = self.log_dir / security_log_file
+
+        self.max_file_bytes = max_file_bytes
+        self.backup_count = backup_count
+        self.console = console
+        self.on_audit = on_audit
+
+        self.hostname = socket.gethostname()
+        try:
+            self.default_ip = socket.gethostbyname(self.hostname)
+        except socket.gaierror:
+            self.default_ip = "127.0.0.1"
+
+        self._lock = threading.Lock()
+        self._ip_counter: dict[str, int] = {}
+        self._rate_limit_window: dict[str, datetime.datetime] = {}
+
+        logger_name = f"auditx.app.{id(self)}"
+        self._app_logger = logging.getLogger(logger_name)
+        if not self._app_logger.handlers:
+            handler = logging.FileHandler(self.app_log_path, encoding="utf-8")
+            handler.setFormatter(logging.Formatter("%(asctime)s | %(levelname)s | %(message)s"))
+            self._app_logger.addHandler(handler)
+            self._app_logger.setLevel(logging.DEBUG)
+            self._app_logger.propagate = False
+
+    @staticmethod
+    def _iso_timestamp() -> str:
+        return datetime.datetime.now(datetime.timezone.utc).astimezone().isoformat(timespec="seconds")
+
+    @staticmethod
+    def _display_timestamp() -> str:
+        return datetime.datetime.now().strftime("%d/%m/%Y %I:%M:%S %p")
+
+    def _format_level(self, level: str) -> str:
+        level = level.upper()
+        if _COLORAMA:
+            color = self._LEVEL_COLORS.get(level, Fore.WHITE)
+            return color + level
+        return level
+
+    def _format_method(self, method: str) -> str:
+        method = method.upper()
+        if _COLORAMA:
+            color = self._METHOD_COLORS.get(method, Fore.WHITE)
+            return color + method
+        return method
+
+    def _rotate_if_needed(self, path: Path) -> None:
+        if not path.exists() or path.stat().st_size < self.max_file_bytes:
+            return
+        for i in range(self.backup_count - 1, 0, -1):
+            src = path.with_suffix(path.suffix + f".{i}")
+            dst = path.with_suffix(path.suffix + f".{i + 1}")
+            if src.exists():
+                src.replace(dst)
+        path.replace(path.with_suffix(path.suffix + ".1"))
+
+    def _append_line(self, path: Path, line: str) -> None:
+        with self._lock:
+            self._rotate_if_needed(path)
+            with path.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")
+
+    def _emit_console(self, entry: AuditEntry) -> None:
+        if not self.console:
+            return
+        ts = self._display_timestamp()
+        method = self._format_method(entry.method) if entry.method else "N/A"
+        level = self._format_level(entry.level)
+        ref = f" [{entry.reference_no}]" if entry.reference_no else ""
+        entity = f" {entry.entity_type}:{entry.entity_id}" if entry.entity_type else ""
+        amount = f" {entry.amount:,.2f} {entry.currency}" if entry.amount is not None else ""
+        print(
+            f"{ts} | {level} | {entry.module}/{entry.action} | "
+            f"{method} {entry.endpoint} | {entry.status} | "
+            f"{entry.description}{ref}{entity}{amount} | "
+            f"{entry.user}@{entry.branch_id or 'HQ'} | req:{entry.request_id[:8]} | IP:{entry.ip}"
+        )
+
+    def _write_audit(self, entry: AuditEntry) -> None:
+        self._append_line(self.audit_log_path, json.dumps(entry.to_dict(), ensure_ascii=False, default=str))
+
+        if entry.level in (LogLevel.SECURITY.value, LogLevel.CRITICAL.value, "EXTREME"):
+            self._append_line(self.security_log_path, json.dumps(entry.to_dict(), ensure_ascii=False, default=str))
+
+        if self.on_audit:
+            try:
+                self.on_audit(entry)
+            except Exception as exc:
+                self._app_logger.error("on_audit callback failed: %s", exc)
+
+    def _build_entry(
+        self,
+        *,
+        description: str,
+        level: str = LogLevel.AUDIT.value,
+        module: str = BusinessModule.SYSTEM.value,
+        action: str = AuditAction.READ.value,
+        user: Optional[str] = None,
+        user_role: str = "",
+        company_id: str = "",
+        branch_id: str = "",
+        entity_type: str = "",
+        entity_id: str = "",
+        reference_no: str = "",
+        amount: Optional[float] = None,
+        currency: str = "MMK",
+        old_values: Optional[dict[str, Any]] = None,
+        new_values: Optional[dict[str, Any]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        request_id: str = "",
+        session_id: str = "",
+        ip: Optional[str] = None,
+        method: str = "",
+        endpoint: str = "",
+        status: int = 200,
+        success: bool = True,
+    ) -> AuditEntry:
+        ctx = RequestContext.get()
+        return AuditEntry(
+            timestamp=self._iso_timestamp(),
+            level=level.upper(),
+            module=module,
+            action=action,
+            description=description,
+            user=user or ctx.get("user", "SYSTEM"),
+            user_role=user_role or ctx.get("user_role", ""),
+            company_id=company_id or ctx.get("company_id", ""),
+            branch_id=branch_id or ctx.get("branch_id", ""),
+            entity_type=entity_type,
+            entity_id=str(entity_id) if entity_id else "",
+            reference_no=reference_no,
+            amount=amount,
+            currency=currency,
+            old_values=old_values or {},
+            new_values=new_values or {},
+            metadata=metadata or {},
+            request_id=request_id or ctx.get("request_id", "") or str(uuid.uuid4()),
+            session_id=session_id or ctx.get("session_id", ""),
+            ip=ip or ctx.get("ip") or self.default_ip,
+            hostname=self.hostname,
+            method=method.upper() if method else "",
+            endpoint=endpoint,
+            status=status,
+            success=success,
+        )
+
+    def check_rate_limit(self, ip: str, limit: int = 5, window_seconds: int = 60) -> bool:
+        now = datetime.datetime.now()
+        window_start = self._rate_limit_window.get(ip)
+
+        if window_start is None or (now - window_start).total_seconds() > window_seconds:
+            self._rate_limit_window[ip] = now
+            self._ip_counter[ip] = 1
+            return True
+
+        self._ip_counter[ip] = self._ip_counter.get(ip, 0) + 1
+        return self._ip_counter[ip] <= limit
+
+    def reset_rate_limit(self, ip: str) -> None:
+        self._ip_counter.pop(ip, None)
+        self._rate_limit_window.pop(ip, None)
+
+    def log(
+        self,
+        description: str,
+        *,
+        level: str = LogLevel.AUDIT.value,
+        module: str = BusinessModule.SYSTEM.value,
+        action: str = AuditAction.READ.value,
+        **kwargs: Any,
+    ) -> AuditEntry:
+        entry = self._build_entry(
+            description=description,
+            level=level,
+            module=module,
+            action=action,
+            **kwargs,
+        )
+        self._emit_console(entry)
+        self._write_audit(entry)
+        return entry
+
+    def log_change(
+        self,
+        description: str,
+        *,
+        module: BusinessModule | str,
+        action: AuditAction | str,
+        entity_type: str,
+        entity_id: str,
+        old_values: dict[str, Any],
+        new_values: dict[str, Any],
+        reference_no: str = "",
+        **kwargs: Any,
+    ) -> AuditEntry:
+        return self.log(
+            description=description,
+            level=LogLevel.AUDIT.value,
+            module=module.value if isinstance(module, BusinessModule) else module,
+            action=action.value if isinstance(action, AuditAction) else action,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            reference_no=reference_no,
+            old_values=old_values,
+            new_values=new_values,
+            **kwargs,
+        )
+
+    def log_transaction(
+        self,
+        description: str,
+        *,
+        module: BusinessModule,
+        action: AuditAction,
+        reference_no: str,
+        amount: float,
+        currency: str = "MMK",
+        entity_type: str = "",
+        entity_id: str = "",
+        party: str = "",
+        **kwargs: Any,
+    ) -> AuditEntry:
+        metadata = kwargs.pop("metadata", {}) or {}
+        if party:
+            metadata["party"] = party
+        return self.log(
+            description=description,
+            level=LogLevel.AUDIT.value,
+            module=module.value,
+            action=action.value,
+            reference_no=reference_no,
+            amount=amount,
+            currency=currency,
+            entity_type=entity_type,
+            entity_id=entity_id,
+            metadata=metadata,
+            **kwargs,
+        )
+
+    def log_inventory(
+        self,
+        description: str,
+        *,
+        action: AuditAction,
+        product_id: str,
+        product_name: str = "",
+        quantity: float,
+        unit: str = "pcs",
+        warehouse_id: str = "",
+        reference_no: str = "",
+        **kwargs: Any,
+    ) -> AuditEntry:
+        metadata = kwargs.pop("metadata", {}) or {}
+        metadata.update({"product_name": product_name, "quantity": quantity, "unit": unit, "warehouse_id": warehouse_id})
+        return self.log(
+            description=description,
+            level=LogLevel.AUDIT.value,
+            module=BusinessModule.INVENTORY.value,
+            action=action.value,
+            entity_type="product",
+            entity_id=product_id,
+            reference_no=reference_no,
+            metadata=metadata,
+            **kwargs,
+        )
+
+    def log_service(
+        self,
+        description: str,
+        *,
+        action: AuditAction,
+        job_id: str,
+        customer_id: str = "",
+        technician: str = "",
+        service_type: str = "",
+        status_label: str = "",
+        amount: Optional[float] = None,
+        **kwargs: Any,
+    ) -> AuditEntry:
+        metadata = kwargs.pop("metadata", {}) or {}
+        metadata.update({
+            "customer_id": customer_id,
+            "technician": technician,
+            "service_type": service_type,
+            "status": status_label,
+        })
+        return self.log(
+            description=description,
+            level=LogLevel.AUDIT.value,
+            module=BusinessModule.SERVICE.value,
+            action=action.value,
+            entity_type="service_job",
+            entity_id=job_id,
+            amount=amount,
+            metadata=metadata,
+            **kwargs,
+        )
+
+    def log_security(
+        self,
+        description: str,
+        *,
+        action: AuditAction = AuditAction.LOGIN,
+        user: str = "UNKNOWN",
+        ip: Optional[str] = None,
+        success: bool = True,
+        **kwargs: Any,
+    ) -> AuditEntry:
+        level = LogLevel.SECURITY.value if not success else LogLevel.AUDIT.value
+        check_ip = ip or RequestContext.get().get("ip") or self.default_ip
+
+        if not self.check_rate_limit(check_ip):
+            description = "Rate limit exceeded - possible brute force"
+            level = LogLevel.CRITICAL.value
+            success = False
+
+        return self.log(
+            description=description,
+            level=level,
+            module=BusinessModule.AUTH.value,
+            action=action.value,
+            user=user,
+            ip=check_ip,
+            success=success,
+            **kwargs,
+        )
+
+    def debug(self, message: str, **extra: Any) -> None:
+        self._app_logger.debug(self._format_app_message(message, extra))
+
+    def info(self, message: str, **extra: Any) -> None:
+        self._app_logger.info(self._format_app_message(message, extra))
+
+    def warning(self, message: str, **extra: Any) -> None:
+        self._app_logger.warning(self._format_app_message(message, extra))
+
+    def error(self, message: str, **extra: Any) -> None:
+        self._app_logger.error(self._format_app_message(message, extra))
+
+    def critical(self, message: str, **extra: Any) -> None:
+        self._app_logger.critical(self._format_app_message(message, extra))
+
+    @staticmethod
+    def _format_app_message(message: str, extra: dict[str, Any]) -> str:
+        if not extra:
+            return message
+        return f"{message} | {json.dumps(extra, ensure_ascii=False, default=str)}"
+
+    def auditing(
+        self,
+        description: str,
+        level: str = "NORMAL",
+        user: str = "SYSTEM",
+        method: str = "N/A",
+        endpoint: str = "/",
+        status: int = 200,
+        ip: Optional[str] = None,
+        **kwargs: Any,
+    ) -> AuditEntry:
+        return self.log(
+            description=description,
+            level=level,
+            module=kwargs.pop("module", BusinessModule.SYSTEM.value),
+            action=kwargs.pop("action", AuditAction.READ.value),
+            user=user,
+            method=method,
+            endpoint=endpoint,
+            status=status,
+            ip=ip,
+            **kwargs,
+        )

auditx-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: auditX
+Version: 0.1.0
+Summary: ERP-grade audit logging for trading and service businesses
+Author: Myanmar Smart Business Hub
+License: MIT
+Project-URL: Homepage, https://github.com/MyanmarSmartBusinessHub/auditX
+Project-URL: Documentation, https://github.com/MyanmarSmartBusinessHub/auditX#readme
+Keywords: audit,logging,erp,compliance,trading,inventory
+Classifier: Development Status :: 4 - Beta
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: colorama>=0.4.6
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# auditX
+
+ERP-grade audit logging for **trading** and **service** businesses. Track who did what, when, and where — with structured JSON trails suitable for compliance, SIEM, and multi-branch operations.
+
+## Install
+
+```bash
+pip install auditX
+```
+
+**From source (development):**
+
+```bash
+git clone https://github.com/MyanmarSmartBusinessHub/auditX.git
+cd auditX
+pip install -e .
+```
+
+## Quick start
+
+```python
+from auditx import audit, RequestContext, BusinessModule, AuditAction
+
+# Set user/tenant context once per request or job
+RequestContext.set(
+    user="admin",
+    user_role="manager",
+    company_id="CO-001",
+    branch_id="BR-YGN",
+    ip="192.168.1.10",
+)
+
+# Security / auth
+audit.log_security("User login successful", action=AuditAction.LOGIN, user="admin")
+
+# Trading — sales, purchase, payments
+audit.log_transaction(
+    "Sales invoice posted",
+    module=BusinessModule.SALES,
+    action=AuditAction.POST,
+    reference_no="SI-2026-0042",
+    amount=1_250_000,
+    entity_type="sales_invoice",
+    entity_id="inv-42",
+    party="Golden Trading Co.",
+)
+
+# Inventory
+audit.log_inventory(
+    "Stock issued for sales order",
+    action=AuditAction.TRANSFER,
+    product_id="SKU-1001",
+    product_name="LED Panel 24W",
+    quantity=50,
+    warehouse_id="WH-MAIN",
+    reference_no="SI-2026-0042",
+)
+
+# Service jobs
+audit.log_service(
+    "Service job completed",
+    action=AuditAction.UPDATE,
+    job_id="SVC-889",
+    customer_id="CUST-220",
+    technician="U Kyaw",
+    service_type="AC Maintenance",
+    status_label="completed",
+    amount=85_000,
+)
+
+# Field-level change audit (before/after)
+audit.log_change(
+    "Customer credit limit updated",
+    module=BusinessModule.CRM,
+    action=AuditAction.UPDATE,
+    entity_type="customer",
+    entity_id="CUST-220",
+    old_values={"credit_limit": 500_000},
+    new_values={"credit_limit": 1_000_000},
+)
+```
+
+## Run the demo
+
+```bash
+python -m auditx
+# or after install:
+auditx-demo
+```
+
+## Configuration
+
+```python
+from auditx import configure, create_logger
+
+# Reconfigure the global singleton at app startup
+configure(log_dir="/var/log/my-erp", console=False)
+
+# Or create separate loggers per tenant/service
+tenant_logger = create_logger(log_dir="logs/tenant-acme", console=False)
+tenant_logger.log_transaction(...)
+```
+
+### Log files
+
+| File | Purpose |
+|------|---------|
+| `logs/audit.jsonl` | Immutable audit trail (one JSON object per line) |
+| `logs/security.jsonl` | Auth failures, rate limits, critical security events |
+| `logs/app.log` | General application messages (`audit.info()`, etc.) |
+
+## Flask / FastAPI middleware pattern
+
+```python
+from auditx import RequestContext, audit, AuditAction
+
+def set_audit_context(user, request):
+    RequestContext.set(
+        user=user.username,
+        user_role=user.role,
+        company_id=user.company_id,
+        branch_id=user.branch_id,
+        request_id=request.headers.get("X-Request-ID", ""),
+        ip=request.remote_addr,
+    )
+
+# On login
+audit.log_security("Login", action=AuditAction.LOGIN, user=username, success=True)
+
+# On logout
+RequestContext.clear()
+```
+
+## Database hook (optional)
+
+Persist audit entries to your database:
+
+```python
+def save_to_db(entry):
+    db.execute(
+        "INSERT INTO audit_log (data) VALUES (?)",
+        [json.dumps(entry.to_dict())],
+    )
+
+from auditx import configure
+configure(log_dir="logs", on_audit=save_to_db)
+```
+
+## Public API
+
+| Export | Description |
+|--------|-------------|
+| `audit` | Global logger singleton |
+| `AuditLogger` | Create custom logger instances |
+| `configure()` | Reconfigure the global singleton |
+| `create_logger()` | Factory for new logger instances |
+| `RequestContext` | Thread-local user/tenant context |
+| `AuditEntry` | Structured audit record dataclass |
+| `BusinessModule` | `SALES`, `PURCHASE`, `INVENTORY`, `SERVICE`, etc. |
+| `AuditAction` | `CREATE`, `UPDATE`, `POST`, `PAYMENT`, `LOGIN`, etc. |
+| `LogLevel` | `DEBUG`, `INFO`, `AUDIT`, `SECURITY`, `CRITICAL`, etc. |
+
+## License
+
+MIT

auditx-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+auditx/__init__.py,sha256=TKXAtacKRYIvnt0DC3jPx7c0gG7_3EQCvYDfrO3ia6c,1892
+auditx/__main__.py,sha256=6bMUnEUlpm_KDaWpLDrNJLH_zgy1MaO1ZQ9sJ4FWIZs,2025
+auditx/core.py,sha256=yTNb-DnyTSmRVOos7paM8XO2utjBmcrTzX0L1aSvFJU,18690
+auditx-0.1.0.dist-info/METADATA,sha256=YYkTldmFz0H-_R8QKTkclaZ1NN2I3b_xFTusO3juvZc,5285
+auditx-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+auditx-0.1.0.dist-info/entry_points.txt,sha256=LhIWp6BS3EpIgX2a9Z2pB3CAGIfNTvwlf3KkNZDJCEk,53
+auditx-0.1.0.dist-info/top_level.txt,sha256=pBVlpYKvdJyWQ_hmeEG1vjf9T7gxzcLelfVCwElSo08,7
+auditx-0.1.0.dist-info/RECORD,,

auditx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auditx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+auditx-demo = auditx.__main__:main

auditx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auditx