Metadata-Version: 2.4
Name: oriflux-sdk
Version: 0.1.0
Summary: Oriflux API analytics — zero-dependency ASGI middleware with client-side 60 s aggregation
Project-URL: Homepage, https://sponge-theory.ai
Author-email: Sponge Theory <contact@sponge-theory.io>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# oriflux-sdk

API analytics middleware for [Oriflux](https://sponge-theory.ai) — zero
dependencies, MIT-licensed, < 1 ms per request.

```bash
pip install oriflux-sdk
```

```python
from oriflux_sdk import OrifluxMiddleware

app.add_middleware(OrifluxMiddleware, api_key="ofx_ing_…")  # FastAPI / Starlette / any ASGI
```

That's the whole integration. The middleware aggregates client-side in 60 s
windows (Apitally pattern): request counts, error counts, latency histograms
and payload sizes keyed by templated endpoint, method, status code, consumer
and caller IP — the IP is what lets Oriflux resolve caller geography at
ingestion (then discard it; it is never stored). Cardinality is capped at
~2 000 keys per window with an explicit overflow bucket.

**Your API is never impacted**: recording is in-memory dict arithmetic,
flushing happens on a daemon thread with a 3 s timeout, failures are dropped
(never retried, never raised), and a circuit breaker pauses flushing entirely
while Oriflux is unreachable.

## Options

| Option | Default | Purpose |
|---|---|---|
| `api_key` | — (required) | the source's ingest key |
| `endpoint` | `https://in.oriflux.sponge-theory.dev` | self-hosted / first-party proxy target |
| `consumer` | `None` | `callable(scope) -> str` to attribute traffic to an API consumer |
| `flush_interval_s` | `60` | aggregation window |
| `max_keys` | `2000` | cardinality cap per window |
