Metadata-Version: 2.4
Name: logvault
Version: 0.2.2
Summary: Audit-Log-as-a-Service client library
Home-page: https://github.com/Rul1an/LogVault
Author: LogVault
Author-email: LogVault <support@logvault.io>
License: MIT
Project-URL: Homepage, https://logvault.io
Project-URL: Documentation, https://logvault.io/docs
Project-URL: Repository, https://github.com/Rul1an/LogVault
Project-URL: Bug Tracker, https://github.com/Rul1an/LogVault/issues
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: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
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.21.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: requires-python

# LogVault Python SDK

Official Python client for [LogVault](https://logvault.io) - Audit-Log-as-a-Service for SOC 2, GDPR, and ISO 27001 compliance.

## Installation

```bash
pip install logvault
```

## Quick Start

```python
import logvault

# Initialize client
client = logvault.Client("lv_live_...")

# Log an event (that's it!)
event = client.log(
    action="user.login",
    user_id="user_123",
    resource="app",
    metadata={"ip": "1.2.3.4", "method": "password"}
)

print(f"✅ Event logged: {event['id']}")
```

## Usage

### Basic Example

```python
import logvault

# Create client
client = logvault.Client(api_key="lv_live_...")

# Log different types of events
client.log(
    action="user.login",
    user_id="user_123",
    resource="app"
)

client.log(
    action="document.delete",
    user_id="user_456",
    resource="document:789",
    metadata={"reason": "GDPR request"}
)

client.log(
    action="permission.grant",
    user_id="admin_001",
    resource="user:456",
    metadata={"role": "admin", "granted_by": "admin_001"}
)
```

### With Context Manager

```python
import logvault

with logvault.Client("lv_live_...") as client:
    event = client.log(
        action="user.login",
        user_id="user_123"
    )
    print(f"Logged: {event['id']}")
# Client automatically closed
```

### Async/Await Support

```python
import logvault
import asyncio

async def main():
    async with logvault.AsyncClient("lv_live_...") as client:
        event = await client.log(
            action="user.login",
            user_id="user_123"
        )
        print(f"Logged: {event['id']}")

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']} by {event['user_id']}")

# Filter by user
user_events = client.list_events(user_id="user_123")

# Filter by action
login_events = client.list_events(action="user.login")
```

### Custom Timestamp

```python
from datetime import datetime

client.log(
    action="document.create",
    user_id="user_123",
    resource="document:456",
    timestamp=datetime(2025, 1, 1, 12, 0, 0)
)
```

### Replay Protection (Nonce)

```python
# Enable nonce for replay attack prevention
client = logvault.Client(
    api_key="lv_live_...",
    enable_nonce=True
)

client.log(action="user.login", user_id="user_123")
# Each request includes a unique nonce
```

### Custom API URL (Self-Hosted)

```python
client = logvault.Client(
    api_key="lv_live_...",
    base_url="https://logvault.mycompany.com"
)
```

## Error Handling

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

client = logvault.Client("lv_live_...")

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} seconds")
except APIError as e:
    print(f"API error: {e.status_code} - {e}")
```

## Action Format

Actions must follow the format: `entity.verb`

### Examples

**Authentication:**

- `user.login`
- `user.logout`
- `user.password_reset`

**Documents:**

- `document.create`
- `document.read`
- `document.update`
- `document.delete`

**Permissions:**

- `permission.grant`
- `permission.revoke`
- `role.assign`

**Data:**

- `data.export`
- `data.delete` (GDPR)

## Configuration

### Environment Variables

```bash
# Use environment variable for API key
export LOGVAULT_API_KEY="lv_live_..."
```

```python
import os
import logvault

client = logvault.Client(os.getenv("LOGVAULT_API_KEY"))
```

### Test Mode

```python
# Use test API key for development
client = logvault.Client("lv_test_...")

# Test events won't count toward your quota
```

## Requirements

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

## Links

- **Website:** https://logvault.io
- **Documentation:** https://logvault.io/docs
- **GitHub:** https://github.com/Rul1an/LogVault
- **Support:** support@logvault.io

## License

MIT License - see [LICENSE](LICENSE) for details.
