Metadata-Version: 2.4
Name: jetv-clearing-sdk
Version: 1.0.0
Summary: Official Python SDK for the Clearing economic-principal (EPID) service
License: Apache-2.0
Project-URL: Homepage, https://github.com/jetv/clearing-sdk-python
Project-URL: Source, https://github.com/jetv/clearing-sdk-python
Keywords: clearing,epid,identity,sdk,jetv
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"

# jetv-clearing-sdk

Official Python SDK for the **Clearing** economic-principal (EPID) service.

Clearing assigns every economic principal — humans, services, agents, organizations,
and providers — a stable **EPID** and a canonical kind, and exposes signed, auditable
operations for resolution, sourced writes, and identity unification.

## Install

```bash
pip install jetv-clearing-sdk
```

## Tiers

The SDK is layered so each caller only takes the capability (and trust) it needs:

| Tier | Constructor | Capability |
| --- | --- | --- |
| L1 — read | `ClearingClient.read_only(...)` | resolve EPIDs, read canonical kinds (no signing keys) |
| L2 — source | `ClearingClient.source(...)` | F4-signed `ensure` / `link` / `affiliate` writes |
| L3 — unify | `ClearingClient.unify(...)` | key-proof, verified-attribute, bind, and realm-link flows |

## Quick start (L1)

```python
import asyncio
from clearing_sdk import ClearingClient

async def main():
    client = ClearingClient.read_only(base_url="https://clearing.internal")
    resolved = await client.resolve("user", "alice@example.com")
    print(resolved.epid, resolved.canonical_kind, resolved.status)

asyncio.run(main())
```

## Canonical JSON & signing

For source-authenticated (F4) and unify (L2/L3) operations the SDK produces a
**Go-exact canonical JSON** encoding so signatures verify byte-for-byte against the
server reference implementation, including HTML escaping of `<`, `>`, `&` and
`U+2028` / `U+2029`. Floating-point numbers are rejected in signed bodies to keep
canonicalization deterministic.

## Resilience

The L1 read client ships an in-process TTL cache, single-flight request
deduplication, and a circuit breaker with zero required third-party runtime deps
beyond `httpx` and `cryptography`.

## License

Apache-2.0
