Metadata-Version: 2.4
Name: logvault
Version: 0.2.3
Summary: Audit-Log-as-a-Service client library
Home-page: https://github.com/Rul1an/LogVault
Author: LogVault
Author-email: LogVault <support@logvault.eu>
License-Expression: MIT
Project-URL: Homepage, https://logvault.app
Project-URL: Documentation, https://logvault.app/docs
Project-URL: Repository, https://github.com/Rul1an/logvault-python
Project-URL: Bug Tracker, https://github.com/Rul1an/logvault-python/issues
Project-URL: Changelog, https://github.com/Rul1an/logvault-python/blob/main/CHANGELOG.md
Keywords: audit,logging,compliance,soc2,gdpr,iso27001,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# LogVault Python SDK

[![PyPI version](https://img.shields.io/pypi/v/logvault.svg)](https://pypi.org/project/logvault/)
[![Python versions](https://img.shields.io/pypi/pyversions/logvault.svg)](https://pypi.org/project/logvault/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official Python client for [LogVault](https://logvault.app) — Audit-Log-as-a-Service for B2B SaaS. SOC 2, GDPR, and ISO 27001 compliant. Hosted in the EU.

## Installation

```bash
pip install logvault
```

## Quick Start

```python
from logvault import Client

client = Client("your-api-key")

# Log an audit event
event = client.log(
    action="user.login",
    user_id="user_123",
    resource="auth",
    metadata={"ip": "192.168.1.1", "method": "password"}
)

print(f"Logged: {event['id']}")
```

## Features

- **Sync & Async** — Both `Client` and `AsyncClient` available
- **Automatic Retries** — Exponential backoff with jitter
- **Input Validation** — Action format and payload size checks
- **Error Handling** — Typed exceptions for auth, rate limits, validation
- **Replay Protection** — Optional nonce support

## Usage

### Async Client

```python
import asyncio
from logvault import AsyncClient

async def main():
    async with AsyncClient("your-api-key") as client:
        event = await client.log(
            action="document.create",
            user_id="user_456",
            resource="document:789",
            metadata={"title": "Q4 Report"}
        )

asyncio.run(main())
```

### List Events

```python
# Get recent events
response = client.list_events(page=1, page_size=50)

for event in response['events']:
    print(f"{event['timestamp']} - {event['action']}")

# Filter by user or action
user_events = client.list_events(user_id="user_123")
login_events = client.list_events(action="user.login")
```

### Error Handling

```python
from logvault import Client, AuthenticationError, RateLimitError, APIError

client = Client("your-api-key")

try:
    event = client.log(action="user.login", user_id="user_123")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except APIError as e:
    print(f"API error: {e.status_code}")
```

### Configuration Options

```python
client = Client(
    api_key="your-api-key",
    base_url="https://api.logvault.eu",  # Default
    timeout=30,                           # Request timeout (seconds)
    enable_nonce=True,                    # Replay protection
    max_retries=3                         # Retry attempts
)
```

## Action Format

Actions follow the pattern `entity.verb`:

| Category | Examples |
|----------|----------|
| Auth | `user.login`, `user.logout`, `user.password_reset` |
| Documents | `document.create`, `document.read`, `document.delete` |
| Permissions | `permission.grant`, `permission.revoke`, `role.assign` |
| Data | `data.export`, `data.delete` |

## Requirements

- Python 3.8+
- `requests` (sync client)
- `aiohttp` (async client)

## Links

- [Documentation](https://logvault.app/docs)
- [API Reference](https://logvault.app/docs/api)
- [GitHub](https://github.com/Rul1an/logvault-python)
- [PyPI](https://pypi.org/project/logvault/)

## License

MIT — see [LICENSE](LICENSE) for details.
