Metadata-Version: 2.5
Name: ratum
Version: 0.1.0
Summary: Python-SDK für die ratum Integrations-API (ADR-016)
Author: Talent Factory GmbH
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: typing-extensions>=4.6
Description-Content-Type: text/markdown

# ratum — Python-SDK

Python-Client für die ratum Integrations-API ([ADR-016](../../docs/ADR/ADR-016-oeffentliche-integrations-api-sdk.md)).
Sync und async, Python ≥ 3.11, `httpx`.

- **Low-Level-Client** `ratum.generated`: generiert mit `openapi-python-client` aus der
  eingecheckten [`openapi.json`](../../openapi.json). Nicht von Hand ändern.
- **Komfortschicht** `Ratum` / `AsyncRatum`: `upload_document`, `create_and_send`
  (setzt `Idempotency-Key` automatisch), `wait_for_completion`, dazu
  `verify_webhook_signature`, Retries bei 429/5xx mit `Retry-After` und typisierte Exceptions
  aus dem RFC-9457-`code`.

> Status `0.1.0`, noch nicht auf PyPI. Installation aus dem Repo:
> `pip install "ratum @ git+https://github.com/talent-factory/ratum#subdirectory=sdk/python"`

## Quickstart

```python
from ratum import Ratum

with Ratum("ratum_test_…") as client:  # base_url=… für Staging/lokal
    doc = client.create_and_send(
        "vertrag.pdf",
        signers=[
            {
                "email": "anna@example.ch",
                "fields": [
                    {
                        "field_type": "signature",
                        "page": 1,
                        "x": 60,
                        "y": 700,
                        "width": 200,
                        "height": 50,
                        "page_width": 595,
                        "page_height": 842,
                    }
                ],
            }
        ],
    )
    done = client.wait_for_completion(doc.id, timeout=3600)
    print(done.status, done.failure_code)
```

Async: `AsyncRatum` mit denselben Methoden (`async with`, `await`). Lauffähige Beispiele:
[`examples/quickstart.py`](examples/quickstart.py), [`examples/quickstart_async.py`](examples/quickstart_async.py).

`create_and_send` lädt die Datei presigned hoch, ruft `/complete` auf und gibt den aktuellen
Dokumentstand zurück. Versendet wird serverseitig, sobald Scan und ggf. DOCX-Konvertierung
durch sind. Wer den Aufruf nach einem Absturz ohne Doppelversand wiederholen will, übergibt
einen eigenen, stabilen `idempotency_key` (z. B. die eigene Auftrags-ID). Das schützt, solange
das Backend die Antwort speichert (24 h); nach Ablauf der Upload-URL (derzeit 15 min) scheitert
die Wiederholung aber mit `UploadError`, obwohl das Dokument womöglich schon versendet ist —
dann zuerst `get_document` prüfen.

`wait_for_completion` gibt das Dokument im Endzustand zurück (`signed`, `declined`, `failed`,
`archived`), auch bei `failed`; der Grund steht in `failure_code`. `archived` sagt nichts über
den Ausgang (auch Entwürfe lassen sich archivieren) — dafür die Signer-Status prüfen. Läuft die
Frist ab, wirft es `WaitTimeoutError` mit dem letzten Stand in `.document`. Für lange
Signierfristen sind Webhooks die bessere Wahl.

### Anker statt Koordinaten, eigene Zustellung

```python
doc = client.create_and_send(
    "vertrag.docx",  # enthält z. B. {{ratum:signature:1}} und {{ratum:date:1}}
    signers=[{"email": "anna@example.ch"}],  # Felder kommen aus den Ankern
    anchors=True,  # oder {"sizes": {"signature": {"width": 200, "height": 60}}}
    delivery="none",  # ratum mailt dem Signer nicht
)
# Nach Webhook `signer.activated` (oder per Polling) den Link holen und selbst zustellen:
link = client.get_signing_link(doc.id, doc.signers[0].id)
```

Fehlt ein Anker, endet das Dokument mit `status=failed` und `failure_code=anchor_not_found`.
Jeder `get_signing_link`-Aufruf entwertet den vorherigen Link. Das versiegelte PDF nach
`signed`: `client.download_sealed_document(doc.id)` (kurz nach `signed` evtl. noch 404).

## Webhooks

Endpoints verwalten (Scope `webhooks:manage`, max. 3):

```python
endpoint = client.create_webhook("https://example.ch/ratum-hook", events=["document.completed"])
secret = endpoint.secret  # nur in dieser Antwort — sicher ablegen
client.send_test_webhook(endpoint.id)  # webhook.ping
client.list_webhook_deliveries(endpoint.id)  # Zustell-Log
client.rotate_webhook_secret(endpoint.id)  # neues Secret, wirkt sofort
```

Empfangen und prüfen:

```python
from ratum import SIGNATURE_HEADER, WebhookSignatureError, verify_webhook_signature


def handle(request):  # Django; Flask: request.get_data(), FastAPI: await request.body()
    try:
        event = verify_webhook_signature(
            request.body,  # unveränderter Raw-Body
            request.headers.get(SIGNATURE_HEADER),
            secret="…",  # Secret des Endpoints
        )
    except WebhookSignatureError:
        return 400
    ...  # event["id"] zum Deduplizieren, event["type"], event["data"]
```

Header `Ratum-Signature: t=<unix>,v1=<hex>`, HMAC-SHA256 über `"<t>.<body>"`; Zeitstempel
ausserhalb ±5 min werden abgelehnt (`tolerance=` anpassbar). Ein leeres `secret` ist ein
Konfigurationsfehler (`ValueError`), nicht „alles erlaubt".

## Fehler und Retries

| Exception | `code` |
|---|---|
| `InvalidRequestError` | `bad_request`, `validation_error`, `method_not_allowed`, `payload_too_large`, `idempotency_key_required`, `idempotency_key_invalid`, `webhook_url_rejected` |
| `AuthenticationError` | `unauthenticated` |
| `PermissionDeniedError` | `plan_required`, `insufficient_scope`, `forbidden` |
| `NotFoundError` | `not_found` |
| `ConflictError` | `conflict`, `not_ready`, `idempotency_key_reused` (HTTP 422), `idempotency_key_in_use` |
| `DocumentProcessingError` | `scan_infected`, `scan_failed`, `conversion_failed`, `anchor_not_found`, `anchor_scan_failed` |
| `QuotaExceededError` | `quota_exceeded` (Freemium-Monatslimit, 402) |
| `RateLimitError` | `rate_limited` (Rate-/Tageslimit, Cooldown; 429) |
| `ServerError` | `internal_error`, jeder 5xx |

Alle oben erben von `APIError` (`.status`, `.code`, `.detail`, `.problem`, `.errors`,
`.headers`, `.retry_after`, `.body_text`). Unbekannte Codes einer neueren API werden über den
HTTP-Status zugeordnet. Antworten ohne `code` (z. B. HTML einer Bot-Abwehr oder eines Proxys)
werden zu einem generischen `APIError` mit dem Anfang des Bodys in der Meldung — bzw. zu
`ServerError` (5xx) und `RateLimitError` (429).

Ausserdem, direkt unter `RatumError`:

| Exception | Wann |
|---|---|
| `APIConnectionError` / `APITimeoutError` | Netzwerkfehler bzw. Timeout, auch nach den Retries (Ursache in `__cause__`) |
| `UploadError` | presigned Upload in den Storage fehlgeschlagen (inkl. Redirect) |
| `WaitTimeoutError` | `wait_for_completion` abgelaufen (`.document`) |
| `WebhookSignatureError` | Webhook-Signatur ungültig |

Eine Antwort, die das SDK nicht lesen kann (z. B. ein neuer `status`-Wert einer neueren API),
wird zu `RatumError` mit Hinweis auf ein SDK-Update. `except RatumError` fängt damit alles.

Retries (Default `max_retries=2`):

- 429 immer;
- 500/502/503/504 und Netzwerkfehler nur bei GET/HEAD/PUT/DELETE/OPTIONS oder mit
  `Idempotency-Key`, damit nichts doppelt ausgeführt wird;
- 409 `idempotency_key_in_use` mit `Retry-After` (erster Versuch läuft serverseitig noch).

Gewartet wird `Retry-After` (Sekunden oder HTTP-Datum), sonst exponentiell ab 0,5 s mit Jitter.
Verlangt der Server mehr als 30 s, wartet das SDK nicht, sondern wirft sofort (`retry_after`
am Fehler). Gilt auch für den Low-Level-Client unter `client.api` — dort aber nur die zum
Client passenden Funktionen nutzen (`Ratum.api` → `sync…`, `AsyncRatum.api` → `asyncio…`);
sie werfen ebenfalls statt `ProblemDetails` zurückzugeben.

Proxy: `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`/`NO_PROXY` aus der Umgebung wie bei httpx. Ein
eigener `transport=` ersetzt das.

## Entwicklung

```bash
just sdk-py-generate   # nach jeder Änderung an openapi.json (`just be-openapi`)
just sdk-py-check      # Drift-Check, ruff, mypy, pytest + Coverage ≥ 90 % (Komfortschicht)
```

Generator (`openapi-python-client`) und `ruff` sind exakt gepinnt, damit die Generierung
reproduzierbar ist; CI vergleicht den eingecheckten Code mit einer frischen Generierung.
