Metadata-Version: 2.4
Name: tradeproof
Version: 0.1.0
Summary: Official Python SDK for the TradeProof contractor-license API (v1, MVP).
Author: TradeProof
License: Apache-2.0
Project-URL: Homepage, https://tradeproof.net
Project-URL: Source, https://github.com/edcadet10/tradeproof-python
Project-URL: Documentation, https://docs.tradeproof.net
Keywords: tradeproof,contractor,license,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff==0.15.14; extra == "dev"
Requires-Dist: black==26.5.1; extra == "dev"

# tradeproof — Python SDK

Official Python SDK for the [TradeProof](https://tradeproof.net) contractor-license API
(`/v1`). Hand-written, typed, and dependency-light (just `httpx`).

```bash
pip install tradeproof
```

## Quickstart

```python
from tradeproof import TradeProof

with TradeProof(api_key="tp_read_...") as client:
    results = client.licenses.search("roofing contractors in texas", limit=5)
    for hit in results.hits:
        print(hit.license_number, hit.business_name, hit.state)

    record = client.licenses.get("TX", "tdlr", "ABC123")
    print(record.status, record.expiration_date)
```

See [`examples/quickstart.py`](examples/quickstart.py) for an end-to-end example you can run
against staging (`TRADEPROOF_BASE_URL`).

## MVP scope — these features only

This is the `0.1.0` MVP. It intentionally covers a small, stable surface and **nothing
else**:

- **Authentication** — API key (`tp_...`) or JWT bearer token; both sent as
  `Authorization: Bearer`.
- **License lookup** — `client.licenses.get(...)`, `.lookup(...)`, `.search(...)`,
  `.list(...)`, `.coverage()`.
- **Watchlist CRUD** — `client.watchlist.list() / .add() / .remove()` (org-scoped; also
  needs `internal_auth_token=`).
- **Webhook subscription CRUD** — `client.webhooks.create() / .list() / .get() /
  .update() / .delete()`.
- **HMAC signature verification** — `tradeproof.verify(body, signature, secret)` for the
  `X-TradeProof-Signature` header on inbound webhooks.

Everything else in the API (billing, audits, insurance/COI, notifications, Procore, admin)
is out of scope for the MVP and lands in later minor releases.

## Authentication

```python
TradeProof(api_key="tp_read_...")          # programmatic API key
TradeProof(bearer_token="<jwt>")           # OIDC/JWT bearer
TradeProof(api_key="tp_...", internal_auth_token="...")  # org-scoped surfaces (watchlist)
```

## Webhook signature verification (HMAC)

`verify()` is the cryptographic primitive that authenticates a webhook body — it confirms
the payload was signed with your subscription secret and is within the replay-tolerance
window. It does not assert anything about a contractor.

```python
import tradeproof

ok = tradeproof.verify(request.body, request.headers["X-TradeProof-Signature"], secret)
if not ok:
    abort(400)
```

The signature is `t=<unix>,v1=<hex>` where `v1 = HMAC-SHA256(secret, f"{t}.{body}")`; during
secret rotation several `v1=` values may be present and any valid one is accepted.

## Errors & retries

Non-2xx responses raise typed exceptions (`NotFoundError`, `AuthenticationError`,
`RateLimitError`, ...), all subclasses of `tradeproof.APIError`. The client automatically
retries on `429` (honouring `Retry-After`) and `5xx`, up to `max_retries` (default 2).

## Roadmap to 1.0

| Milestone | Adds |
| --- | --- |
| `0.2.0` | Async client (`AsyncTradeProof`), auto-pagination iterators |
| `0.3.0` | Insurance/COI + audit-report read surfaces |
| `0.4.0` | Notifications + billing read surfaces |
| `1.0.0` | Full `/v1` coverage, frozen public surface, stability commitment |

## Versioning & stability

Pre-1.0 the SDK follows tight semantic-versioning discipline so you can pin safely:

- **`0.1.x`** — bug-fix patches only; no breaking changes.
- **`0.2.0`, `0.3.0`, ...** — additive minor releases; existing calls keep working.
- **`1.0.0`** — the stability commitment: the public surface is frozen and any future
  breaking change ships with a **12-month deprecation window** and a migration note.

Until `1.0.0`, pin a minor range (e.g. `tradeproof>=0.1,<0.2`).

## License

Apache-2.0.
