proofage 0.1.0__tar.gz

proofage-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage

proofage-0.1.0/AGENTS.md

@@ -0,0 +1,202 @@
+# ProofAge Python SDK — API contract for agents
+
+This package wraps the ProofAge v1 HTTP API. Methods live on `client.workspace` and
+`client.verifications`; `AsyncProofAge` has the same methods, awaited. Responses are Pydantic
+models from `proofage.models`, and they are lenient: a field the SDK does not know yet is kept in
+`model.model_extra`, and a status the SDK does not know yet arrives as a plain `str` instead of a
+`VerificationStatus` member (compare with `==`, not `is`). `model.model_dump(mode="json")` gives a
+plain dict. A machine-readable spec ships next to this file as `openapi.json` (authoritative for
+endpoints and request bodies; where it does not describe a response, the shapes below are
+authoritative).
+
+All requests send `X-API-Key` and `X-HMAC-Signature`. Request bodies use **snake_case** to match
+the API. Responses are never wrapped in `data`.
+
+## Configuration
+
+Argument → environment variable → default. The environment variables use the **Laravel/PHP
+SDK's units**, so one `.env` serves both; constructor arguments are seconds as floats.
+
+| Argument | Environment | Default | Notes |
+|---|---|---|---|
+| `api_key` | `PROOFAGE_API_KEY` | required | Workspace API key |
+| `secret_key` | `PROOFAGE_SECRET_KEY` | required | Used only to sign; never sent, never in `repr` |
+| `base_url` | `PROOFAGE_BASE_URL` | `https://api.proofage.xyz` | API origin without the version; a trailing `/v1` is stripped; a non-http(s) URL, a query or a fragment raises `ConfigurationError` |
+| `version` | `PROOFAGE_VERSION` | `v1` | |
+| `timeout` | `PROOFAGE_TIMEOUT` (seconds) | `30.0` | httpx per-operation timeout (connect, each read, each write), not a deadline for the whole request. Node reads this variable in milliseconds |
+| `retry_attempts` | `PROOFAGE_RETRY_ATTEMPTS` | `3` | Attempts for interactive requests |
+| `retry_delay` | `PROOFAGE_RETRY_DELAY` (**milliseconds**) | `1.0` s | Linear backoff unit; `PROOFAGE_RETRY_DELAY=1000` is one second |
+| `download_retry_attempts` | `PROOFAGE_DOWNLOAD_RETRY_ATTEMPTS` | `1` | Media downloads; only transport failures are retried |
+| `http_client` | — | owned | Your `httpx.Client` / `httpx.AsyncClient`; the SDK never closes it |
+| `sdk_tokens` | — | `()` | `name/version` tokens for a package wrapping this SDK (see "SDK identification") |
+| `user_agent` | — | SDK default | Replaces the User-Agent; `X-ProofAge-Sdk` is still sent |
+
+## Errors
+
+Every non-2xx response raises. All request errors extend `ProofAgeError`, which carries
+`status_code`, `message`, `code` (the API's machine-readable code, when sent), `error_data` and the
+raw `response_body`:
+
+```
+ProofAgeError
+├── AuthenticationError     401
+├── PaymentRequiredError    402  code PAYMENT_METHOD_REQUIRED; error_data has free_verifications_remaining, trial_ends_at, trial_active
+├── PermissionDeniedError   403
+├── NotFoundError           404
+├── ValidationError         422  .errors: dict[str, list[str]]; media rejections carry .code (e.g. FACE_NOT_FOUND)
+├── RateLimitError          429  .retry_after: float | None, raised after the retries run out
+├── ServerError             5xx
+└── TransportError          no response (DNS, connection, TLS, timeout); __cause__ is the httpx exception
+ConfigurationError           raised when a client is built
+WebhookVerificationError     see "Outbound webhook"
+```
+
+The API uses four error body shapes; the client reads all of them:
+
+- `{ error: { code, message } }` — most errors (401 auth, 429 `RATE_LIMIT`, submit 422, media download 404). `error_data` is the inner object.
+- `{ code, message, ...extra }` — flat: `402 PAYMENT_METHOD_REQUIRED` (extra: `free_verifications_remaining`, `trial_ends_at`, `trial_active`) and media-quality rejections on upload (`422`, e.g. `FACE_NOT_FOUND`; `500 VALIDATION_SERVICE_UNAVAILABLE`). `error_data` is the whole body.
+- `{ message, errors }` — request validation (`422`). `code` is `None`; `errors` has the fields.
+- `{ message }` — `403` (verification not in your workspace) and `404` (`Resource not found`).
+
+A 2xx with an empty body returns `None` from the methods typed `-> None`; where a model is
+promised, an empty or non-JSON 2xx raises `ProofAgeError` (a non-JSON one almost always means
+`base_url` points at a website rather than the API).
+
+Retries: GETs retry on 408, 429, 5xx, timeouts and transport errors. POSTs retry **only** on 429
+and on errors raised before anything was sent (`httpx.ConnectError`, `httpx.ConnectTimeout`) —
+never on 5xx or after sending began (`WriteError`, `WriteTimeout`, `ReadError`, `ReadTimeout`,
+`RemoteProtocolError`), where the server may already have created the verification or stored the
+upload. A 429 waits for `Retry-After` (seconds or an HTTP date) when present, up to 60 seconds —
+a longer one raises `RateLimitError` at once with `retry_after` set — else `retry_delay * attempt`.
+A 2xx whose body does not match the model raises `ProofAgeError` ("Unexpected response shape from
+GET /v1/..."), naming the fields but never their values.
+
+## Auth / HMAC
+
+- `X-API-Key`: workspace API key (plaintext; the server SHA256-hashes it).
+- `X-HMAC-Signature`: hex HMAC-SHA256 with the workspace secret key over a canonical string:
+  - JSON / no-file requests: `METHOD + /{version}/{path} + ?query + rawJsonBody` (direct
+    concatenation, no delimiter; the query part only when there is one, keys sorted and values
+    RFC 3986-encoded). The body is serialised once, compact, and sent as exactly the signed bytes;
+    an empty payload is the empty string, never `{}`.
+  - Multipart (file) requests: `METHOD/{version}/{path}\n{fields}\n{comma-joined sorted sha256(file) hashes}`,
+    where `{fields}` is PHP `http_build_query(ksort($fields), '', '&', PHP_QUERY_RFC3986)` — keys
+    sorted, values `rawurlencode`d (so `! ' ( ) *` are percent-encoded too). The client signs
+    exactly what it sends: `None` fields are dropped, numbers are `str(n)`, booleans `"1"`/`"0"`,
+    dicts and lists compact JSON strings. Golden vectors: `tests/fixtures/hmac-vectors.json` in the
+    source repository.
+
+## Endpoints
+
+### GET /workspace — `client.workspace.get()` → `WorkspaceInfo`
+Request: none.
+Response: `{ id: str, name: str, flow_type: str, mode: str, age_mode: str|None, age_threshold: int|None, verification_type: str, redirect_url: str|None, webhook_url: str|None, allow_expired_documents: bool, allow_duplicate_accounts: bool }`
+
+### GET /consent — `client.workspace.consent()` → `ConsentInfo`
+Request: none.
+Response: `{ id: int, version: str, text_sha256: str, url: str }`
+
+### POST /verifications — `client.verifications.create(**kwargs)` → `CreatedVerification`
+Request (all optional keywords): `fingerprint: str(64), callback_url: url(<=2048), external_id: str(<=255), external_metadata: dict, metadata: dict, page_url: str(<=8192)` (`page_url`: the page the verification was started on; only scheme, host and path are kept).
+Response (`201`): `{ id, external_id, external_metadata, redirect_url, status, reason, duplicate_check: DuplicateCheck, erasure: Erasure|None, consent_accepted_at, created_at, updated_at, url }` — `url` is the hosted session the person opens.
+Errors: `402` `PaymentRequiredError`; `422` `ValidationError`.
+
+- `DuplicateCheck`: `{ checked: bool, duplicate_count: int, duplicates: [ { verification_id: str, external_id: str|None, similarity_score: float, verified_at: datetime|None } ] }` — always present.
+- `Erasure`: `{ erased_at: datetime, scope: "personal_data", reason: str|None, requested_via: "customer"|"proofage"|"retention"|None }` — `None` until the verification's personal data is erased. `reason` is an erasure reason code (`data_subject_request`, `customer_request`, `retention_policy`, `test_data`, `other`) or `None` if unrecorded.
+
+### GET /verifications/{verification} — `client.verifications.get(verification_id)` → `Verification`
+Request: none.
+Response: same as create **without** `url`.
+
+### POST /verifications/{verification}/consent — `client.verifications.accept_consent(verification_id, *, consent_version_id, text_sha256, ...)` → `AcceptConsentResult`
+Request: `consent_version_id: int, text_sha256: str(64 hex)`, optional `device: { platform, screen, language, timezone, hardware_concurrency, device_memory }, in_app_browser: str|None, camera_permission: "granted"|"denied"|"prompt"|"unsupported"|None, camera_policy_allowed: bool|None, in_iframe: bool|None, referrer: str|None`. `consent_version_id` / `text_sha256` are `id` / `text_sha256` from `workspace.consent()`. Custom capture flows only.
+Response: `{ consent_version_id: int, consent_accepted_at: datetime }`
+
+### POST /verifications/{verification}/media — `client.verifications.upload_media(verification_id, *, file, type, ...)` → `None`
+Request (multipart): `file: bytes | pathlib.Path | binary file object (image, <=10 MB; documents >=200px per edge)`, `type: "selfie"|"liveness_selfie"|"document"`, `side: "front"|"back"` and `document: "id"|"driver_license"|"passport"|"residence_permit"` (both required when `type="document"`), optional `filename` (default: the path's name, else `upload.bin`), `fingerprint: str(64), head_turn_step: int(0..10), capture_resolution: str|dict, device_info: str|dict, liveness_telemetry: str|list`. Dicts and lists are sent as JSON strings. A text-mode file raises `TypeError`; an invalid `type`/`side`/`document` combination raises `ValueError`, both before any request. Requires consent accepted first.
+Response: `200` with an **empty body**; returns `None`.
+Errors: `422` `ValidationError` with `.code` when the image is rejected (e.g. `FACE_NOT_FOUND`) or `.errors` for invalid fields; `500` `ServerError` `VALIDATION_SERVICE_UNAVAILABLE`.
+
+### POST /verifications/{verification}/submit — `client.verifications.submit(verification_id)` → `None`
+Request: none.
+Response: `200` with an **empty body**. Error: `422` `{ error: { code, message } }` (e.g. `MISSING_REQUIRED_MEDIA`).
+
+### GET /verifications/{verification}/document — `client.verifications.document(verification_id)` → `VerificationDocument`
+Request: none.
+Response: `{ document: { fields: { first_name: str|None, last_name: str|None, date_of_birth: date|None, document_number: str|None } }, media: [ { id: str, type: "selfie"|"document_front"|"document_back", url: str|None } ], meta: { attempt_id: str|None } }`. `url` is None once the media has been purged or is past retention.
+
+### GET /verifications/{verification}/media/{media} — `download_media()` / `download_media_to()`
+`with client.verifications.download_media(verification_id, media_id) as chunks:` yields the image bytes as an iterator (`async with` and an async iterator on `AsyncProofAge`); `client.verifications.download_media_to(verification_id, media_id, path)` streams to disk and returns the `Path`, writing to a temporary sibling and renaming only after a 2xx, so a failure never leaves a partial file. `media_id` is `media[].id` from `document()`; check its `url` is not None first. Requests send `Accept: application/json, */*;q=0.8` so errors come back as JSON. Error: `404` `NotFoundError` with `code == "MEDIA_NOT_FOUND"`. An HTTP status is never retried, 429 included; a transport failure is retried `download_retry_attempts` times, only before the first byte.
+
+### GET /verifications/{verification}/estimation — `client.verifications.estimation(verification_id)` → `AgeEstimation`
+Request: none.
+Response: `{ verification_id: str, attempt_id: str|None, age_threshold: { minimum: int|None, passed: bool|None, confidence: float|None }, gender: { value: 0|1|None, confidence: float|None }|None }` (gender value: 0=female, 1=male).
+
+### POST /verifications/{verification}/blocked-face — `client.verifications.block_face(verification_id, *, reason_code=None, reason=None)` → `None`
+Request: `reason_code: BlockFaceReasonCode | str`, `reason: str(<=1000)`.
+Response: `204 No Content`.
+
+Every `verification_id` and `media_id` must be a ProofAge id (letters, digits, `-`, `_`); anything else raises `ValueError` before a request is built.
+
+## Enums
+
+- `status` (`VerificationStatus`): `created`, `started`, `submitted`, `resubmission_requested`, `approved`, `declined`, `abandoned`, `expired`, `review`, or `documents_required` (the last is surfaced from the latest attempt's state, not a verification status). Open: an unknown value arrives as `str`.
+- `reason_code` (`BlockFaceReasonCode`): `presentation_attack` (spoof: screen, print or mask), `fraudulent_document` (forged, edited, or not a real document), `scam_or_abuse` (identity may be genuine — blocked for behaviour on your platform), `underage`, `other` (explain in `reason`). Optional over the API, mandatory in the ProofAge consoles: send it whenever a person made the decision, or the block cannot be told apart from an automated one in reporting.
+- `reason` (on `declined` / `resubmission_requested`): dotted codes from the server's reason catalog — illustrative examples: `aml.blocklist.face_match`, `document.face.mismatch`, `verification.age_threshold.failed`. Treat `reason` as an open string.
+
+## Outbound webhook (ProofAge → your `callback_url` / workspace webhook URL)
+
+Headers: `X-Auth-Client` (api key), `X-Timestamp` (unix seconds), `X-HMAC-Signature`
+(= hex HMAC-SHA256 of `{timestamp}.{rawJsonBody}` with the active secret key),
+`X-ProofAge-Webhook-Delivery-Id` (the same on every automatic retry of one delivery, a new one on a
+manual resend — de-duplicate on it).
+
+```python
+from proofage import WebhookVerificationError, verify_webhook
+
+try:
+    # api_key=, secret_key= and tolerance= fall back to the environment
+    event = verify_webhook(raw_body, headers)
+except WebhookVerificationError as error:
+    ...  # answer error.http_status; error.code says which check failed
+```
+
+- `verify_webhook(raw_body, headers, *, api_key=None, secret_key=None, tolerance=None)` → `WebhookEvent`; `verify_webhook_signature(...)` → `None` (checks only). Keys and tolerance fall back to `PROOFAGE_API_KEY`, `PROOFAGE_SECRET_KEY`, `PROOFAGE_WEBHOOK_TOLERANCE` (default 300 seconds, in both directions).
+- Pass the body **exactly as received** (`bytes` or `str`). A body whose only change is whitespace is still accepted (the canonical compact JSON is tried once), but one that lost PHP's `\/` escapes is not.
+- Error codes, in check order: `MISSING_SIGNATURE`, `MISSING_TIMESTAMP`, `MISSING_AUTH_CLIENT` (401); `CONFIGURATION_ERROR` (500, keys missing — checked after the three headers); `INVALID_AUTH_CLIENT`, `MISSING_TIMESTAMP` for a non-integer timestamp, `TIMESTAMP_TOO_OLD`, `INVALID_SIGNATURE` (401); `INVALID_PAYLOAD` (400, correctly signed but not a webhook event; the message names the fields, never the body's values).
+- `WebhookEvent`:
+
+```
+{
+  "verification_id": str,
+  "status": VerificationStatus | str,
+  "external_id": str|None,
+  "external_metadata": dict|None,
+  "reason": str|None,                          # a code only on resubmission_requested / declined
+  "timestamp": datetime,
+  "duplicate_detected": bool (default False),  # the three duplicate_* keys appear together
+  "duplicate_count": int|None,
+  "duplicate_of": { "verification_id": str, "external_id": str|None }|None,
+  "fingerprint_signals": dict|None,
+  "manual_moderation": {                       # after a console approve/decline
+    "action": "approve"|"decline", "reason": str, "source": "tenant_admin"|"landlord_admin",
+    "performed_by": { "id": int, "name": str|None, "email": str|None, "role": str|None },
+    "source_status": str|None, "source_reason": str|None
+  }|None,
+  "delivery_id": str|None                      # from X-ProofAge-Webhook-Delivery-Id
+}
+```
+
+## SDK identification
+
+Every request carries `X-ProofAge-Sdk: [wrapper tokens ]python/{version}` (wrappers pass
+`sdk_tokens=["telegram-bot/1.2.0"]`, outermost first; a wrapper token named `python` is dropped)
+and `User-Agent: ProofAge-Python/{version} (Python {x.y.z})` unless you pass `user_agent` or your
+`http_client` carries its own. Neither header is part of the signature.
+
+## Keeping this in sync
+
+This contract is drift-tested against `openapi.json` by `tests/test_api_contract.py`, so it stays
+aligned with the API. Maintainers refreshing it after an API change: see the SDK contract-sync
+runbook in the ProofAge app repo (`developer-docs/README.md`, "Keeping the SDK clients in sync"),
+the single source of truth for all SDKs.

proofage-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows
+[Semantic Versioning](https://semver.org/); while the version is 0.x, a minor
+release may change the API and a patch release never does.
+
+## 0.1.0 — 2026-09-28
+
+First release.
+
+- `ProofAge` and `AsyncProofAge` clients for every `/v1` endpoint.
+- Pydantic v2 response models; unknown fields and statuses never break parsing.
+- Typed errors for the API's four error body shapes.
+- Retries that never repeat a POST the server may already have acted on.
+- Webhook verification (`verify_webhook`, `verify_webhook_signature`).
+- `X-ProofAge-Sdk` and User-Agent identification on every request.
+- Supports Python 3.10–3.14.

proofage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProofAge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proofage-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.5
+Name: proofage
+Version: 0.1.0
+Summary: Python client for the ProofAge age and identity verification API
+Project-URL: Homepage, https://proofage.xyz
+Project-URL: Repository, https://github.com/ProofAge/python-sdk
+Project-URL: Changelog, https://github.com/ProofAge/python-sdk/blob/main/CHANGELOG.md
+Author-email: ProofAge <support@proofage.xyz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: age verification,identity verification,kyc,proofage,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Description-Content-Type: text/markdown
+
+# proofage — ProofAge for Python
+
+Python client for [ProofAge](https://proofage.xyz), the age and identity verification API. It
+gives you a sync and an async client for every `/v1` endpoint, typed Pydantic models, typed errors
+and webhook verification — enough to go from `pip install` to a verified result in a few minutes,
+from a backend, a Telegram bot or an AI agent.
+
+## Install
+
+```bash
+pip install proofage
+# or
+uv add proofage
+```
+
+## Quick start
+
+Set `PROOFAGE_API_KEY` and `PROOFAGE_SECRET_KEY` (from your workspace in the ProofAge console),
+then:
+
+```python
+from proofage import ProofAge
+
+with ProofAge() as client:
+    verification = client.verifications.create(
+        external_id="candidate-42",
+        callback_url="https://your-app.example/verified",
+    )
+    print(verification.url)  # send the person here
+
+    # later, or when the webhook arrives
+    print(client.verifications.get(verification.id).status)
+```
+
+The person opens `verification.url` on their phone, ProofAge runs the checks, and you learn the
+outcome from a webhook (below) or by calling `get()`.
+
+## Async
+
+`AsyncProofAge` has the same methods, awaited — the natural choice in aiogram bots, FastAPI and
+other asyncio code:
+
+```python
+from proofage import AsyncProofAge
+
+async with AsyncProofAge() as client:
+    verification = await client.verifications.create(external_id="tg-12345")
+```
+
+## Receiving results (webhooks)
+
+ProofAge POSTs the outcome to your workspace's webhook URL. Verify it with the **raw** request
+body — not a re-serialised copy of its JSON — and answer 2xx.
+
+FastAPI:
+
+```python
+from fastapi import FastAPI, Request, Response
+from proofage import WebhookVerificationError, verify_webhook
+
+app = FastAPI()
+
+
+@app.post("/webhooks/proofage")
+async def proofage_webhook(request: Request) -> Response:
+    try:
+        event = verify_webhook(await request.body(), request.headers)
+    except WebhookVerificationError as error:
+        return Response(status_code=error.http_status)
+    print(event.verification_id, event.status, event.reason)
+    return Response(status_code=200)
+```
+
+Django:
+
+```python
+from django.http import HttpResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from proofage import WebhookVerificationError, verify_webhook
+
+
+@csrf_exempt
+@require_POST
+def proofage_webhook(request):
+    try:
+        event = verify_webhook(request.body, request.headers)
+    except WebhookVerificationError as error:
+        return HttpResponse(status=error.http_status)
+    ...
+    return HttpResponse(status=200)
+```
+
+A delivery can arrive more than once: de-duplicate on `event.delivery_id`, which stays the same
+on every automatic retry. Ready-made FastAPI, Django and Flask integrations are coming in 0.1.x.
+
+## Statuses
+
+`event.status` and `verification.status` are `VerificationStatus` members (`APPROVED`,
+`DECLINED`, `RESUBMISSION_REQUESTED`, `REVIEW`, …). A status this version does not know yet
+arrives as a plain string instead of raising, so compare with `==`:
+
+```python
+from proofage import VerificationStatus
+
+if event.status == VerificationStatus.APPROVED:
+    ...
+```
+
+Unknown fields are kept too, in `model.model_extra`; `model.model_dump(mode="json")` gives a plain
+dict.
+
+## Errors
+
+```python
+from proofage import PaymentRequiredError, ProofAgeError, RateLimitError, ValidationError
+
+try:
+    client.verifications.create(external_id="x" * 300)
+except ValidationError as error:
+    print(error.errors)  # {"external_id": ["..."]}
+except PaymentRequiredError:
+    print("Add a payment method to the workspace")
+except RateLimitError as error:
+    print("Try again in", error.retry_after, "seconds")
+except ProofAgeError as error:
+    print(error.status_code, error.code, error.message)
+```
+
+`AuthenticationError` (401), `PaymentRequiredError` (402), `PermissionDeniedError` (403),
+`NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429), `ServerError` (5xx) and
+`TransportError` (no response) all extend `ProofAgeError`. `ConfigurationError` is raised when a
+client is built with missing or invalid settings. A response whose shape this SDK version does not
+recognise raises `ProofAgeError` naming the fields (never their values).
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `api_key` | `PROOFAGE_API_KEY` | required |
+| `secret_key` | `PROOFAGE_SECRET_KEY` | required |
+| `base_url` | `PROOFAGE_BASE_URL` | `https://api.proofage.xyz` |
+| `version` | `PROOFAGE_VERSION` | `v1` |
+| `timeout` | `PROOFAGE_TIMEOUT` (seconds) | `30.0` |
+| `retry_attempts` | `PROOFAGE_RETRY_ATTEMPTS` | `3` |
+| `retry_delay` | `PROOFAGE_RETRY_DELAY` (**milliseconds**) | `1.0` seconds |
+| `download_retry_attempts` | `PROOFAGE_DOWNLOAD_RETRY_ATTEMPTS` | `1` |
+| `http_client` | — | an owned `httpx` client |
+
+The environment variables use the same names and units as the ProofAge Laravel and PHP SDKs, so
+one `.env` serves all of them (the Node SDK reads `PROOFAGE_TIMEOUT` in milliseconds). Constructor
+arguments are seconds.
+
+`timeout` limits each network operation (connecting, each read, each write), not the whole
+request. Pass your own `httpx.Client` / `httpx.AsyncClient` as `http_client` for proxies or custom
+TLS; the SDK never closes a client you pass in.
+
+## Retries
+
+- A GET is retried on 408, 429, 5xx, timeouts and connection failures.
+- A POST is retried only on 429 and when the connection never opened. It is never retried on a
+  5xx or once sending began, because the server may already have created the verification.
+- A 429 waits for its `Retry-After`, up to 60 seconds; a longer `Retry-After` raises `RateLimitError`
+  at once (with `retry_after` set) instead of blocking your thread. Otherwise the wait grows by
+  `retry_delay` per attempt.
+- Media downloads never retry an HTTP status; run them from a queue and let its backoff wait.
+
+## Media
+
+```python
+document = client.verifications.document(verification_id)
+for item in document.media:
+    if item.url is not None:  # None once purged or past retention
+        client.verifications.download_media_to(verification_id, item.id, f"{item.id}.jpg")
+```
+
+## Hosted flow first
+
+`accept_consent`, `upload_media` and `submit` exist for custom capture flows. Most integrations
+only create a session, send the person to its `url`, and read the result.
+
+## For packages that wrap this SDK
+
+A plugin or bot template built on this SDK can name itself in the `X-ProofAge-Sdk` header, which
+helps ProofAge support tell integrations apart:
+
+```python
+ProofAge(sdk_tokens=["telegram-bot/1.2.0"])  # X-ProofAge-Sdk: telegram-bot/1.2.0 python/0.1.0
+```
+
+`user_agent=` replaces the default `ProofAge-Python/<version> (Python <x.y.z>)` User-Agent.
+
+## Supported versions
+
+A Python version stays supported for 12 months after its upstream end of life, or until httpx or
+Pydantic stop supporting it, whichever comes first. A version leaves only in a minor release,
+announced one release ahead in the changelog.
+
+| Python | Upstream end of life | Supported by `proofage` until |
+|---|---|---|
+| 3.10 | 2026-10 | 2027-10 |
+| 3.11 | 2027-10 | 2028-10 |
+| 3.12 | 2028-10 | 2029-10 |
+| 3.13 | 2029-10 | 2030-10 |
+| 3.14 | 2030-10 | 2031-10 |
+
+## AI agents
+
+The package ships `AGENTS.md` next to its code: the full request and response contract of every
+method, written for coding agents. Agents that speak MCP can also use the ProofAge MCP server
+directly.
+
+## License
+
+MIT