python/README.md

# hightrusted CAPTURE — Python SDK

> **Status:** v0.1 Preview — API stabil, SDK in aktiver Entwicklung

Offizielles Python-SDK für die [hightrusted CAPTURE API](https://capture.hightrusted.net) —
forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

**Made in Germany.** Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter
in der Verarbeitungskette. Quelloffen unter MIT-Lizenz.

## Was die CAPTURE API tut

Sie nimmt eine URL entgegen, rendert die Seite vollständig (inkl. JavaScript),
liefert sie als PDF/A-3 zurück und versieht das Ergebnis mit einem qualifizierten
Zeitstempel. Das Ergebnis ist gerichtsverwertbar und Jahre später noch
verifizierbar — auch nachdem die Original-Seite längst offline ist.

## Installation

```bash
pip install hightrusted-capture
```

## Quickstart

```python
from hightrusted_capture import Client

client = Client(api_key="ht_live_...")

# Synchron — wartet bis zu 30 s auf das fertige PDF
capture = client.capture(url="https://example.com")

print(capture["id"])
print(capture["verify_url"])
print(capture["timestamp"]["issued_at"])

# PDF herunterladen
client.download_pdf(capture["id"], "./beweis.pdf")
```

## Drei Aufruf-Modi

### Synchron (Default)
```python
capture = client.capture(url="https://example.com")
# Blocks bis zu 30 s, gibt fertige Capture zurück
```

### Asynchron mit Polling
```python
capture = client.capture_async(
    url="https://example.com",
    reference="case-001",
    wait_for_ready=True,   # Default — pollt bis ready
    max_wait=60.0,
)
```

### Webhook
```python
job = client.capture_webhook(
    url="https://example.com",
    webhook_url="https://your-app.tld/webhooks/capture",
    reference="case-001",
)
# job["status"] == "queued"
# Server liefert das fertige Capture per HTTP-POST aus
```

## Verifikation (kostenlos, ohne Quota)

```python
# Per Capture-ID
result = client.verify(source="cap_...")

# Per Verify-URL
result = client.verify(source="https://verify.hightrusted.net/c/...")

# Per PDF-Upload (Datei oder File-Objekt)
result = client.verify(pdf="./beweis.pdf")

print(result["valid"])           # True
print(result["audit_log"]["chain_valid"])  # True
```

## Webhook-Signatur prüfen

```python
from flask import Flask, request
from hightrusted_capture import verify_webhook_signature

@app.post("/webhooks/capture")
def webhook():
    body = request.get_data()  # raw bytes!
    sig = request.headers.get("X-Hightrusted-Signature", "")
    if not verify_webhook_signature(body, sig, "wh_secret_..."):
        return {"error": "invalid_signature"}, 401
    payload = json.loads(body)
    # ...
```

## Fehler-Behandlung

```python
from hightrusted_capture import (
    Client,
    InvalidApiKeyError,
    QuotaExceededError,
    RateLimitedError,
    UnreachableUrlError,
)

try:
    capture = client.capture(url="https://example.com")
except InvalidApiKeyError:
    print("API-Key ungültig")
except QuotaExceededError:
    print("Monats-Quota erschöpft")
except RateLimitedError as e:
    print(f"Zu viele Anfragen, retry in {e.retry_after_seconds}s")
except UnreachableUrlError:
    print("Quelle nicht erreichbar")
```

## API-Key

Bearer-Token mit API-Key. Erzeugen unter
https://capture.hightrusted.net/dashboard/api-keys

```python
client = Client(api_key="ht_live_...")
# alternativ via Umgebungsvariable HIGHTRUSTED_API_KEY
```

## Rate Limits

Limits pro API-Key. Bei Überschreitung: HTTP 429 mit `Retry-After`-Header.
Das SDK respektiert den Header automatisch (`max_retries` ist Default 3).

| Plan      | req/min | Calls/Monat |
|-----------|---------|-------------|
| Developer | 5       | 100         |
| Starter   | 30      | 300         |
| Growth    | 120     | 2.000       |
| Scale     | 600     | 10.000      |

## Voraussetzungen

- Python 3.9 oder höher
- `requests` (wird automatisch installiert)

## Entwicklung

```bash
git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/python.git
cd python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Roadmap

- [x] v0.1 — Basis-Client (sync + async + webhook), Verify, Download, typisierte Errors
- [ ] v0.2 — Async/Await-Variante mit `httpx`, retry-after-Helper
- [ ] v0.3 — Streaming für große PDFs
- [ ] v1.0 — Stabile API, semantische Versionierung

## Verwandte Repositorys

**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):

- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec (Single Source of Truth)
- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen
- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK
- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK

**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):

- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal) — gemeinsame Konventionen
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper

## Support

- **Doku:** https://capture.hightrusted.net/api/docs
- **Status-Page:** https://status.hightrusted.net
- **Developer Support:** developers@hightrusted.net
- **Sicherheitslücken:** siehe [SECURITY.md](./SECURITY.md)

## Lizenz

MIT — siehe [LICENSE](./LICENSE).

---

**hightrusted GmbH** — *The European Trust Infrastructure.*
Made in Germany. DSGVO-nativ. eIDAS-konform.