proofage 0.3.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {proofage-0.3.0 → proofage-0.4.0}/AGENTS.md +10 -7
- {proofage-0.3.0 → proofage-0.4.0}/CHANGELOG.md +20 -0
- {proofage-0.3.0 → proofage-0.4.0}/PKG-INFO +1 -1
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/__init__.py +9 -1
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_version.py +1 -1
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/models.py +41 -0
- proofage-0.4.0/src/proofage/openapi.json +1982 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/_payloads.py +16 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/verifications.py +77 -6
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_api_contract.py +3 -22
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_upload.py +10 -9
- proofage-0.4.0/tests/test_verifications.py +275 -0
- proofage-0.3.0/src/proofage/openapi.json +0 -1795
- proofage-0.3.0/tests/test_verifications.py +0 -141
- {proofage-0.3.0 → proofage-0.4.0}/.gitignore +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/LICENSE +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/README.md +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/examples/README.md +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/examples/aiogram_bot/bot.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/examples/django_view/views.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/examples/fastapi_app/main.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/pyproject.toml +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_async_client.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_client.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_config.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_signing.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_transport.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/errors.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/__init__.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/_common.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/django.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/fastapi.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/flask.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/py.typed +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/__init__.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/workspace.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/src/proofage/webhooks.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/__init__.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/conftest.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/fixtures/hmac-vectors.json +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/integration_support.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_config.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_downloads.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_errors.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_examples.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_django.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_fastapi.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_flask.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_models.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_package.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_signing.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_transport.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_webhooks.py +0 -0
- {proofage-0.3.0 → proofage-0.4.0}/tests/test_workspace.py +0 -0
|
@@ -88,6 +88,8 @@ GET /v1/..."), naming the fields but never their values.
|
|
|
88
88
|
|
|
89
89
|
## Endpoints
|
|
90
90
|
|
|
91
|
+
Keyword arguments the ProofAge widget sends (`fingerprint`, `page_url`, the browser fields of `accept_consent`, the capture fields and `type="liveness_selfie"` of `upload_media`) are deprecated: they still work, raise `DeprecationWarning`, and are not part of this contract.
|
|
92
|
+
|
|
91
93
|
### GET /workspace — `client.workspace.get()` → `WorkspaceInfo`
|
|
92
94
|
Request: none.
|
|
93
95
|
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 }`
|
|
@@ -97,7 +99,7 @@ Request: none.
|
|
|
97
99
|
Response: `{ id: int, version: int, text_sha256: str, url: str }` (`version` is informational: accept consent with `id` and `text_sha256`)
|
|
98
100
|
|
|
99
101
|
### POST /verifications — `client.verifications.create(**kwargs)` → `CreatedVerification`
|
|
100
|
-
Request (all optional keywords): `
|
|
102
|
+
Request (all optional keywords): `callback_url: url(<=2048), external_id: str(<=255), external_metadata: dict, metadata: dict`.
|
|
101
103
|
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.
|
|
102
104
|
Errors: `402` `PaymentRequiredError`; `422` `ValidationError`.
|
|
103
105
|
|
|
@@ -109,11 +111,11 @@ Request: none.
|
|
|
109
111
|
Response: same as create **without** `url`.
|
|
110
112
|
|
|
111
113
|
### POST /verifications/{verification}/consent — `client.verifications.accept_consent(verification_id, *, consent_version_id, text_sha256, ...)` → `AcceptConsentResult`
|
|
112
|
-
Request: `consent_version_id: int, text_sha256: str(64 hex)
|
|
114
|
+
Request: `consent_version_id: int, text_sha256: str(64 hex)`. `consent_version_id` / `text_sha256` are `id` / `text_sha256` from `workspace.consent()`. Custom capture flows only.
|
|
113
115
|
Response: `{ consent_version_id: int, consent_accepted_at: datetime }`
|
|
114
116
|
|
|
115
117
|
### POST /verifications/{verification}/media — `client.verifications.upload_media(verification_id, *, file, type, ...)` → `None`
|
|
116
|
-
Request (multipart): `file: bytes | pathlib.Path | binary file object (image, <=10 MB; documents >=200px per edge)`, `type: "selfie"|"
|
|
118
|
+
Request (multipart): `file: bytes | pathlib.Path | binary file object (image, <=10 MB; documents >=200px per edge)`, `type: "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`). A text-mode file raises `TypeError`; an invalid `type`/`side`/`document` combination raises `ValueError`, both before any request. Requires consent accepted first.
|
|
117
119
|
Response: `200` with an **empty body**; returns `None`.
|
|
118
120
|
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`.
|
|
119
121
|
|
|
@@ -123,7 +125,9 @@ Response: `200` with an **empty body**. Error: `422` `{ error: { code, message }
|
|
|
123
125
|
|
|
124
126
|
### GET /verifications/{verification}/document — `client.verifications.document(verification_id)` → `VerificationDocument`
|
|
125
127
|
Request: none.
|
|
126
|
-
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.
|
|
128
|
+
Response: `{ document: { type: DocumentResultType|str|None, issuing_country: str|None, fields: { first_name: str|None, last_name: str|None, date_of_birth: date|None, document_number: str|None, middle_name: str|None, gender: DocumentGender|str|None, nationality: str|None, place_of_birth: str|None, issue_date: date|None, expiry_date: date|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.
|
|
129
|
+
|
|
130
|
+
Document semantics. `None` means the field was not read or is not printed on that document (a passport has no address, many cards print no place of birth, the German identity card prints no sex). `type` is an open enum (`passport`, `id`, `driver_license`, `residence_permit`, `other`; an unknown value arrives as a plain string): `other` is declared and not yet produced, and `id` is the same value the upload endpoint takes. `issuing_country` and `nationality` are ISO 3166-1 alpha-2 (`XK` for Kosovo) and can differ, for example on a residence permit. `gender` is `F`, `M` or `X` (`DocumentGender`, open); `X` is declared for documents that state an unspecified sex and is not yet produced, and `gender` is `None` on a Mexican voter card or driving licence created before 20 August 2026 17:00 UTC. `date_of_birth`, `issue_date` and `expiry_date` are dates: a document that prints only the month or year of expiry reports the last day of that period, a partially printed birth or issue date is `None`, and a permanent document (for example `PERMANENTE`) has a `None` `expiry_date`. `place_of_birth` is the printed text. Age workspaces receive only `type`, `issuing_country` and `first_name`, `last_name`, `date_of_birth`, `document_number`; on them the other six keys are absent and read as `None`.
|
|
127
131
|
|
|
128
132
|
### GET /verifications/{verification}/media/{media} — `download_media()` / `download_media_to()`
|
|
129
133
|
`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.
|
|
@@ -212,6 +216,5 @@ and `User-Agent: ProofAge-Python/{version} (Python {x.y.z})` unless you pass `us
|
|
|
212
216
|
## Keeping this in sync
|
|
213
217
|
|
|
214
218
|
This contract is drift-tested against `openapi.json` by `tests/test_api_contract.py`, so it stays
|
|
215
|
-
aligned with the API. Maintainers refreshing it after an API change: see the
|
|
216
|
-
|
|
217
|
-
the single source of truth for all SDKs.
|
|
219
|
+
aligned with the API. Maintainers refreshing it after an API change: see the checklist for
|
|
220
|
+
carrying an API change to every client, `.ai/guidelines/api-changes.md` in the ProofAge app repo.
|
|
@@ -4,6 +4,26 @@ All notable changes to this project are documented here. The project follows
|
|
|
4
4
|
[Semantic Versioning](https://semver.org/); while the version is 0.x, a minor
|
|
5
5
|
release may change the API and a patch release never does.
|
|
6
6
|
|
|
7
|
+
## 0.4.0 — 2026-09-30
|
|
8
|
+
|
|
9
|
+
- **Added:** `verifications.document()` returns `document.type` and `document.issuing_country` on
|
|
10
|
+
every workspace, and on identity (KYC) workspaces six more `DocumentFields`: `middle_name`,
|
|
11
|
+
`gender`, `nationality`, `place_of_birth`, `issue_date` and `expiry_date`. All default to `None`,
|
|
12
|
+
so an older API body and an age-workspace body (where the six keys are absent) still parse.
|
|
13
|
+
`type` and `gender` are open enums (`DocumentResultType`, `DocumentGender`): an unknown value
|
|
14
|
+
arrives as a plain string.
|
|
15
|
+
|
|
16
|
+
## 0.3.1 — 2026-09-29
|
|
17
|
+
|
|
18
|
+
- **Deprecated:** the keyword arguments only the ProofAge widget sends: `fingerprint` and `page_url`
|
|
19
|
+
on `create()`, the browser fields of `accept_consent()` (`device`, `in_app_browser`,
|
|
20
|
+
`camera_permission`, `camera_policy_allowed`, `in_iframe`, `referrer`), and the capture fields and
|
|
21
|
+
`type="liveness_selfie"` of `upload_media()`. They are not part of the public API; the API still
|
|
22
|
+
accepts them, so they keep working and now raise `DeprecationWarning`. They will be removed in a
|
|
23
|
+
future minor release. `AGENTS.md` documents only the public contract.
|
|
24
|
+
- **Changed:** the bundled `openapi.json` is synced from the published docs, and
|
|
25
|
+
`scripts/sync_spec.py` reads `https://docs.proofage.xyz/openapi.json` by default.
|
|
26
|
+
|
|
7
27
|
## 0.3.0 — 2026-09-28
|
|
8
28
|
|
|
9
29
|
- **Added:** webhook integrations as extras: `proofage[fastapi]`, `proofage[django]` and
|
|
@@ -18,7 +18,13 @@ from .errors import (
|
|
|
18
18
|
ValidationError,
|
|
19
19
|
WebhookVerificationError,
|
|
20
20
|
)
|
|
21
|
-
from .models import
|
|
21
|
+
from .models import (
|
|
22
|
+
BlockFaceReasonCode,
|
|
23
|
+
DocumentGender,
|
|
24
|
+
DocumentResultType,
|
|
25
|
+
VerificationStatus,
|
|
26
|
+
WebhookEvent,
|
|
27
|
+
)
|
|
22
28
|
from .webhooks import verify_webhook, verify_webhook_signature
|
|
23
29
|
|
|
24
30
|
__all__ = [
|
|
@@ -26,6 +32,8 @@ __all__ = [
|
|
|
26
32
|
"AuthenticationError",
|
|
27
33
|
"BlockFaceReasonCode",
|
|
28
34
|
"ConfigurationError",
|
|
35
|
+
"DocumentGender",
|
|
36
|
+
"DocumentResultType",
|
|
29
37
|
"NotFoundError",
|
|
30
38
|
"PaymentRequiredError",
|
|
31
39
|
"PermissionDeniedError",
|
|
@@ -126,15 +126,56 @@ class AcceptConsentResult(ProofAgeModel):
|
|
|
126
126
|
consent_accepted_at: datetime
|
|
127
127
|
|
|
128
128
|
|
|
129
|
+
class DocumentResultType(_ApiEnum):
|
|
130
|
+
"""The document types a result reports. `other` is declared and not yet produced."""
|
|
131
|
+
|
|
132
|
+
PASSPORT = "passport"
|
|
133
|
+
ID = "id"
|
|
134
|
+
DRIVER_LICENSE = "driver_license"
|
|
135
|
+
RESIDENCE_PERMIT = "residence_permit"
|
|
136
|
+
OTHER = "other"
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
DocumentKind = Annotated[DocumentResultType | str, Field(union_mode="left_to_right")]
|
|
140
|
+
"""A known document type as the enum member, an unknown one as the raw string."""
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
class DocumentGender(_ApiEnum):
|
|
144
|
+
"""The sex a document states. `X` (unspecified) is declared and not yet produced."""
|
|
145
|
+
|
|
146
|
+
F = "F"
|
|
147
|
+
M = "M"
|
|
148
|
+
X = "X"
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
DocumentSex = Annotated[DocumentGender | str, Field(union_mode="left_to_right")]
|
|
152
|
+
"""A known value as the enum member, an unknown one as the raw string."""
|
|
153
|
+
|
|
154
|
+
|
|
129
155
|
class DocumentFields(ProofAgeModel):
|
|
156
|
+
"""Identity (KYC) workspaces receive all ten fields; age workspaces only the first four
|
|
157
|
+
listed here as required. The six KYC-only keys are absent there, so they default to None."""
|
|
158
|
+
|
|
130
159
|
first_name: str | None
|
|
131
160
|
last_name: str | None
|
|
132
161
|
date_of_birth: date | None
|
|
133
162
|
document_number: str | None
|
|
163
|
+
middle_name: str | None = None
|
|
164
|
+
gender: DocumentSex | None = None
|
|
165
|
+
nationality: str | None = None
|
|
166
|
+
"""ISO 3166-1 alpha-2 (`XK` for Kosovo); can differ from `issuing_country`."""
|
|
167
|
+
place_of_birth: str | None = None
|
|
168
|
+
"""The printed text, not normalised."""
|
|
169
|
+
issue_date: date | None = None
|
|
170
|
+
expiry_date: date | None = None
|
|
171
|
+
"""A month or year of expiry is reported as the last day of that period."""
|
|
134
172
|
|
|
135
173
|
|
|
136
174
|
class Document(ProofAgeModel):
|
|
137
175
|
fields: DocumentFields
|
|
176
|
+
type: DocumentKind | None = None
|
|
177
|
+
issuing_country: str | None = None
|
|
178
|
+
"""ISO 3166-1 alpha-2 (`XK` for Kosovo)."""
|
|
138
179
|
|
|
139
180
|
|
|
140
181
|
class MediaItem(ProofAgeModel):
|