Metadata-Version: 2.4
Name: traceiq-py
Version: 0.1.0
Summary: TraceIQ server-side SDK for Python — capture backend events with trustworthy properties.
Author: TraceIQ
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# traceiq (Python)

Server-side TraceIQ SDK for Python (3.8+). Pure standard library — no dependencies.
Events are queued and flushed in batches by a background thread, so your code never
blocks on the network.

## Install

```bash
pip install traceiq
```

## Quickstart

```python
from traceiq import Client

traceiq = Client(
    project_id="YOUR_PROJECT_ID",
    write_key="YOUR_WRITE_KEY",              # keep server keys secret
    endpoint="https://your-traceiq-api.example.com",  # defaults to http://localhost:4000
)

# A trustworthy revenue event, straight from your payments service:
traceiq.capture(
    "payout_succeeded",
    user_id="user_123",
    properties={"amount": 50000, "currency": "NGN"},
)

traceiq.identify("user_123", traits={"email": "a@b.com", "kyc_tier": 2})
traceiq.group("org_9", user_id="user_123", traits={"plan": "growth"})

traceiq.shutdown()  # flush before a short-lived process exits
```

The client also registers an `atexit` flush, so long-running services generally don't
need to call `shutdown()` explicitly.

## API

| Method | Purpose |
| --- | --- |
| `capture(event, user_id=None, anonymous_id=None, properties=None, context=None, timestamp=None)` | Track an event. |
| `identify(user_id, traits=None, timestamp=None)` | Create/update a user profile. |
| `group(organization_id, user_id=None, anonymous_id=None, traits=None, timestamp=None)` | Associate a user with an account. |
| `flush()` | Send everything queued now (blocks). |
| `shutdown()` | Stop the worker and flush. |

## Options

`endpoint`, `flush_at` (20), `flush_interval` (10.0s), `max_retries` (3),
`timeout` (10.0s), `debug` (False), `on_error` (callback).

Delivery is at-most-once; a batch that fails after `max_retries` is dropped and passed
to `on_error`. `properties["amount"]` (a number) powers the dashboard's revenue metrics.
