Metadata-Version: 2.4
Name: auditledge
Version: 0.1.1
Summary: Official Python SDK for Auditledge — Audit Log API for SaaS developers
Home-page: https://auditledge.com
Author: Auditledge
Author-email: hello@auditledge.com
Keywords: audit,audit-log,audit-trail,saas,compliance
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-python
Dynamic: summary

# auditledge-python

Official Python SDK for [Auditledge](https://auditledge.com) — the audit log API for SaaS developers.

Add **"who did what and when"** to your app in minutes.

## Install

```bash
pip install auditledge
```

## Quickstart

```python
from auditledge import AuditLedge

client = AuditLedge('your_api_key')

# Log an event
client.log({
    'actor': {'id': 'user_123', 'name': 'Alice', 'email': 'alice@example.com'},
    'action': 'invoice.deleted',
    'resource': {'type': 'invoice', 'id': 'inv_456', 'name': 'Invoice #1042'},
    'organization_id': 'org_789',
    'metadata': {'ip': '192.168.1.1'}
})

# Query events
result = client.query({
    'organization_id': 'org_789',
    'limit': 50
})
print(result['events'])   # list of events
print(result['total'])    # total matching count

# Query with filters
result = client.query({
    'actor_id': 'user_123',
    'action': 'invoice',        # partial match
    'start_date': '2026-01-01T00:00:00Z',
    'end_date': '2026-12-31T23:59:59Z',
})

# Export as CSV
csv_data = client.export({'format': 'csv', 'organization_id': 'org_789'})

# Export as JSON
events = client.export({'format': 'json', 'organization_id': 'org_789'})

# Check quota usage
info = client.usage()
print(info['plan'])              # 'free', 'starter', or 'growth'
print(info['events_this_month']) # events logged this month
print(info['events_limit'])      # monthly cap
```

## Django / FastAPI Example

```python
from auditledge import AuditLedge

audit = AuditLedge('your_api_key')

def delete_invoice(request, invoice_id):
    invoice = Invoice.objects.get(id=invoice_id)
    invoice.delete()

    audit.log({
        'actor': {'id': str(request.user.id), 'name': request.user.get_full_name()},
        'action': 'invoice.deleted',
        'resource': {'type': 'invoice', 'id': str(invoice_id)},
        'organization_id': str(request.user.organization_id),
        'metadata': {'ip': request.META.get('REMOTE_ADDR')}
    })
```

## Reference

### `AuditLedge(api_key, base_url=None, timeout=30)`

| Param | Description |
|---|---|
| `api_key` | Your Auditledge API key |
| `base_url` | Override the API base URL (optional) |
| `timeout` | HTTP request timeout in seconds (default 30) |

### `log(event)` → dict

Log an audit event. All fields marked **required** will raise `AuditLedgeError` locally before the request is made.

| Field | Required | Description |
|---|---|---|
| `actor.id` | Yes | ID of the user or service performing the action |
| `actor.name` | No | Display name |
| `actor.email` | No | Email address |
| `action` | Yes | Dot-notation string, e.g. `invoice.deleted` |
| `resource.type` | Yes | Resource type, e.g. `invoice` |
| `resource.id` | Yes | Resource ID |
| `resource.name` | No | Display name |
| `organization_id` | No | Defaults to the key's organisation |
| `metadata` | No | Any additional key/value data |
| `timestamp` | No | ISO 8601 string — defaults to now |

### `query(filters)` → dict

| Filter | Description |
|---|---|
| `organization_id` | Filter by organisation |
| `actor_id` | Exact match on actor ID |
| `actor_name` | Partial match on actor name |
| `action` | Partial match on action string |
| `resource_type` | Exact match on resource type |
| `search` | Full-text search across action, actor name, and resource type |
| `start_date` | ISO 8601 — events on or after this date |
| `end_date` | ISO 8601 — events on or before this date |
| `limit` | Max results (default 20) |
| `offset` | Pagination offset (default 0) |

Returns `{ events: [...], total: int, limit: int, offset: int }`.

### `get(event_id)` → dict

Fetch a single event by ID.

### `export(options)` → str or list

| Option | Description |
|---|---|
| `format` | `'csv'` or `'json'` (default `'json'`) |
| `organization_id` | Filter by organisation |
| `start_date` | ISO 8601 start date |
| `end_date` | ISO 8601 end date |

Returns a `str` for CSV, or a list of event dicts for JSON.

### `usage()` → dict

Returns `{ plan, events_this_month, events_limit, retention_days }`.

## Links

- 🌐 Website: [auditledge.com](https://auditledge.com)
- 📖 Docs: [docs.auditledge.com](https://docs.auditledge.com)
- 🐛 Issues: [github.com/auditledge/auditledge-python/issues](https://github.com/auditledge/auditledge-python/issues)

## License

MIT
