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.
Files changed (54) hide show
  1. {proofage-0.3.0 → proofage-0.4.0}/AGENTS.md +10 -7
  2. {proofage-0.3.0 → proofage-0.4.0}/CHANGELOG.md +20 -0
  3. {proofage-0.3.0 → proofage-0.4.0}/PKG-INFO +1 -1
  4. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/__init__.py +9 -1
  5. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_version.py +1 -1
  6. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/models.py +41 -0
  7. proofage-0.4.0/src/proofage/openapi.json +1982 -0
  8. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/_payloads.py +16 -0
  9. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/verifications.py +77 -6
  10. {proofage-0.3.0 → proofage-0.4.0}/tests/test_api_contract.py +3 -22
  11. {proofage-0.3.0 → proofage-0.4.0}/tests/test_upload.py +10 -9
  12. proofage-0.4.0/tests/test_verifications.py +275 -0
  13. proofage-0.3.0/src/proofage/openapi.json +0 -1795
  14. proofage-0.3.0/tests/test_verifications.py +0 -141
  15. {proofage-0.3.0 → proofage-0.4.0}/.gitignore +0 -0
  16. {proofage-0.3.0 → proofage-0.4.0}/LICENSE +0 -0
  17. {proofage-0.3.0 → proofage-0.4.0}/README.md +0 -0
  18. {proofage-0.3.0 → proofage-0.4.0}/examples/README.md +0 -0
  19. {proofage-0.3.0 → proofage-0.4.0}/examples/aiogram_bot/bot.py +0 -0
  20. {proofage-0.3.0 → proofage-0.4.0}/examples/django_view/views.py +0 -0
  21. {proofage-0.3.0 → proofage-0.4.0}/examples/fastapi_app/main.py +0 -0
  22. {proofage-0.3.0 → proofage-0.4.0}/pyproject.toml +0 -0
  23. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_async_client.py +0 -0
  24. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_client.py +0 -0
  25. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_config.py +0 -0
  26. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_signing.py +0 -0
  27. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/_transport.py +0 -0
  28. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/errors.py +0 -0
  29. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/__init__.py +0 -0
  30. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/_common.py +0 -0
  31. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/django.py +0 -0
  32. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/fastapi.py +0 -0
  33. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/integrations/flask.py +0 -0
  34. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/py.typed +0 -0
  35. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/__init__.py +0 -0
  36. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/resources/workspace.py +0 -0
  37. {proofage-0.3.0 → proofage-0.4.0}/src/proofage/webhooks.py +0 -0
  38. {proofage-0.3.0 → proofage-0.4.0}/tests/__init__.py +0 -0
  39. {proofage-0.3.0 → proofage-0.4.0}/tests/conftest.py +0 -0
  40. {proofage-0.3.0 → proofage-0.4.0}/tests/fixtures/hmac-vectors.json +0 -0
  41. {proofage-0.3.0 → proofage-0.4.0}/tests/integration_support.py +0 -0
  42. {proofage-0.3.0 → proofage-0.4.0}/tests/test_config.py +0 -0
  43. {proofage-0.3.0 → proofage-0.4.0}/tests/test_downloads.py +0 -0
  44. {proofage-0.3.0 → proofage-0.4.0}/tests/test_errors.py +0 -0
  45. {proofage-0.3.0 → proofage-0.4.0}/tests/test_examples.py +0 -0
  46. {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_django.py +0 -0
  47. {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_fastapi.py +0 -0
  48. {proofage-0.3.0 → proofage-0.4.0}/tests/test_integration_flask.py +0 -0
  49. {proofage-0.3.0 → proofage-0.4.0}/tests/test_models.py +0 -0
  50. {proofage-0.3.0 → proofage-0.4.0}/tests/test_package.py +0 -0
  51. {proofage-0.3.0 → proofage-0.4.0}/tests/test_signing.py +0 -0
  52. {proofage-0.3.0 → proofage-0.4.0}/tests/test_transport.py +0 -0
  53. {proofage-0.3.0 → proofage-0.4.0}/tests/test_webhooks.py +0 -0
  54. {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): `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).
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)`, 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.
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"|"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.
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 SDK contract-sync
216
- runbook in the ProofAge app repo (`developer-docs/README.md`, "Keeping the SDK clients in sync"),
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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: proofage
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Python client for the ProofAge age and identity verification API
5
5
  Project-URL: Homepage, https://proofage.xyz
6
6
  Project-URL: Repository, https://github.com/ProofAge/python-sdk
@@ -18,7 +18,13 @@ from .errors import (
18
18
  ValidationError,
19
19
  WebhookVerificationError,
20
20
  )
21
- from .models import BlockFaceReasonCode, VerificationStatus, WebhookEvent
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",
@@ -1,3 +1,3 @@
1
1
  """The single source of the package version: hatchling and the SDK headers both read it."""
2
2
 
3
- __version__ = "0.3.0"
3
+ __version__ = "0.4.0"
@@ -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):