Metadata-Version: 2.4
Name: skawr-analytics
Version: 0.1.0
Summary: Official SKAWR Analytics SDK for Python — server-side event tracking.
Project-URL: Homepage, https://analytics.skawr.com
Project-URL: Repository, https://github.com/LuqtahTech/skawr-analytics
Author: SKAWR
License: MIT
Keywords: analytics,server-side,skawr,tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: requests>=2.28; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: httpx
Requires-Dist: httpx>=0.24; extra == 'httpx'
Provides-Extra: requests
Requires-Dist: requests>=2.28; extra == 'requests'
Description-Content-Type: text/markdown

# skawr-analytics (Python)

Server-side SDK for SKAWR Analytics. Stateless, pluggable HTTP backend, type-hinted, Python 3.9+.

## Install

```bash
pip install skawr-analytics
# Or with the default `requests` backend bundled:
pip install 'skawr-analytics[requests]'
```

## Quickstart

```python
from skawr_analytics import Skawr

skawr = Skawr(api_key="ska_xxxxxxxxxxxx")

# In your request handler:
skawr.track(
    "order_placed",
    user_id=request.user.id,
    properties={"value": 99.50, "currency": "SAR"},
)

# On login:
skawr.identify(
    user_id="u_42",
    anonymous_id=request.cookies.get("skawr_anon"),
    properties={"plan": "pro"},
)
```

## Configuration

```python
Skawr(
    api_key="ska_...",                                # required
    endpoint="https://analytics-api.skawr.com",        # override
    timeout=5.0,                                       # seconds
    default_properties={"app": "api", "env": "prod"},  # merged into every event
    http_post=my_async_post,                           # plug in httpx, custom transport, mocks
)
```

## API

```python
skawr.track(
    event_name,
    user_id=None,
    anonymous_id=None,
    session_id=None,
    properties=None,
    timestamp=None,                                    # datetime / float / str / None
    page_url=None,
    referrer_url=None,
    utm_source=None,
    utm_medium=None,
    utm_campaign=None,
) -> int  # HTTP status

skawr.identify(user_id, anonymous_id, properties=None) -> int
```

`timestamp` accepts `datetime` (naive treated as UTC), POSIX float, or ISO-8601 string. Defaults to `datetime.now(UTC)`.

## Custom HTTP backend

Pass any callable with signature `(url, headers, body) -> response_with_status_code`. Useful for:

- **httpx** — for async or HTTP/2:
  ```python
  import httpx
  client = httpx.Client(timeout=5.0)
  def post(url, headers, body):
      return client.post(url, headers=headers, content=body)
  Skawr(api_key="...", http_post=post)
  ```
- **Tests** — record requests, return canned responses.
- **Custom retry / queue** — wrap a worker that buffers and retries on failure.

## Why server-side?

- **Trusted user_ids.** Browser clients can't be trusted with revenue events; do those server-side.
- **Backend-only events.** Webhook receipts, payment confirmations, scheduled jobs.
- **Defense-in-depth.** Send the same event from both browser and server; dedupe later.

## Development

```bash
pip install -e '.[dev]'
pytest
ruff check src
mypy src
```

## License

MIT.
