Metadata-Version: 2.4
Name: traaaction
Version: 1.3.0
Summary: Python SDK for Traaaction affiliate tracking and management
Project-URL: Homepage, https://traaaction.com
Project-URL: Documentation, https://traaaction.com/docs
Project-URL: Repository, https://github.com/traaaction/traaaction-python
Project-URL: Issues, https://github.com/traaaction/traaaction-python/issues
Author-email: Traaaction <hello@traaaction.com>
License: MIT
Keywords: affiliate,analytics,conversion,tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: django
Requires-Dist: django>=3.2; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.95; extra == 'fastapi'
Requires-Dist: starlette>=0.27; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Description-Content-Type: text/markdown

# traaaction

Python SDK for [Traaaction](https://traaaction.com) — affiliate tracking for Python web apps.

## Install

```bash
pip install traaaction
```

## Quick start

```python
from traaaction import Traaaction

trac = Traaaction()  # reads TRAAACTION_API_KEY env var
# or: trac = Traaaction(api_key="pk_live_xxx")
```

### Track a lead (signup)

Call this immediately after creating a user in your database:

```python
trac.track.lead(
    click_id=click_id,          # from cookie or URL param
    event_name="sign_up",
    customer_id=str(user.id),   # your app's user ID
    customer_email=user.email,
    customer_name=user.get_full_name(),
)
```

### Stripe checkout metadata

Pass this to `stripe.checkout.Session.create()`:

```python
metadata = trac.stripe_metadata(request, str(user.id))
session = stripe.checkout.Session.create(
    line_items=[...],
    mode="subscription",
    metadata=metadata,
    success_url="...",
)
```

## Django integration

### 1. Install with Django extras

```bash
pip install "traaaction[django]"
```

### 2. Add middleware

```python
# settings.py
MIDDLEWARE = [
    ...
    "traaaction.django.TraacMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    ...
]

# Optional: share cookie across subdomains
TRAC_COOKIE_DOMAIN = ".yourdomain.com"
```

### 3. Track events in views

```python
# views.py
from traaaction import Traaaction
from traaaction.django import get_click_id

trac = Traaaction()

def signup_view(request):
    # ... create user ...

    click_id = get_click_id(request)  # reads middleware session or cookies
    trac.track.lead(
        click_id=click_id,
        event_name="sign_up",
        customer_id=str(user.id),
        customer_email=user.email,
    )
    return redirect("/dashboard")

def checkout_view(request):
    metadata = trac.stripe_metadata(request, str(user.id))
    session = stripe.checkout.Session.create(
        line_items=[...],
        mode="subscription",
        metadata=metadata,
        success_url=request.build_absolute_uri("/dashboard"),
    )
    return redirect(session.url)
```

## Environment variables

| Variable | Description |
|----------|-------------|
| `TRAAACTION_API_KEY` | Your Traaaction publishable key (`pk_live_...`) |
| `TRAC_API_KEY` | Legacy alias (backwards compatible) |

## How it works

1. A seller shares their Traaaction affiliate link (e.g. `traaaction.com/s/mission/abc123`)
2. A customer clicks → lands on your site with `?trac_click_id=clk_xxx`
3. TraacMiddleware captures and persists the click ID (session + cookie)
4. On signup: `track.lead()` links the customer to the seller
5. On purchase: Stripe webhook (configured in Traaaction dashboard) automatically creates the commission

## Links

- [Documentation](https://traaaction.com/docs/sdks/python)
- [Django quickstart](https://traaaction.com/docs/sdks/quickstart/django)
- [Dashboard](https://traaaction.com/dashboard)
