uverify 0.1.0__tar.gz

uverify-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+*.tgz
+__pycache__/
+*.egg-info/
+build/
+.venv/
+vendor/
+composer.lock
+.phpunit.result.cache
+.dart_tool/
+.packages
+pubspec.lock
+.DS_Store

uverify-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: uverify
+Version: 0.1.0
+Summary: Official Python library for the UVerify API: BVN, NIN and ID checks, liveness, face match, ID documents and AML screening for Nigeria.
+Project-URL: Homepage, https://uverify.com.ng
+Project-URL: Documentation, https://uverify.com.ng/docs
+Project-URL: Source, https://github.com/elastodev/uverify-sdks
+Author: Elasto Web Services Limited
+License: MIT
+Keywords: aml,bvn,face-match,kyc,liveness,nigeria,nin,uverify
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# UVerify for Python
+
+The official Python library for [UVerify](https://uverify.com.ng): BVN, NIN, driver’s licence and voter’s card checks, liveness and face match, ID documents, AML screening and CAC, for Nigerian businesses.
+
+```bash
+pip install uverify
+```
+
+Python 3.8 or later. No dependencies.
+
+## Quick start
+
+```python
+from uverify import UVerify
+
+uverify = UVerify("uvk_test_...")  # or set UVERIFY_API_KEY; uvk_test_ is the free sandbox
+
+v = uverify.identity.nin(id_number="12345678901", first_name="Adaeze", last_name="Okafor")
+if v["status"] == "verified":
+    print(v["data"], v["field_matches"])
+```
+
+In the sandbox the last two digits of the ID number choose the result: `00` not found, `99` registry error, `98` face mismatch, anything else verified.
+
+## A live customer, end to end
+
+```python
+session = uverify.liveness.create_session(redirect_url="https://yourapp.com/kyc/done")
+# send the person to session["url"]; when they come back:
+v = uverify.identity.bvn_face_match(
+    id_number="22212345678", first_name="Adaeze", last_name="Okafor",
+    liveness_session_id=session["id"],
+    aml_screening=True,
+)
+if v["status"] == "verified" and v["face_match"]["status"] == "matched" and v["aml_screening"]["status"] == "clear":
+    ...  # approve
+```
+
+## Everything else
+
+```python
+uverify.identity.bvn(id_number=..., first_name=..., last_name=...)       # also drivers_license, voters_card, tin
+uverify.identity.nin_face_match(id_number=..., selfie_image=open("me.jpg", "rb").read())
+uverify.business.cac(id_number="RC123456", aml_screening=True)
+
+uverify.documents.verify(front_image=open("nin.jpg", "rb").read(), document_type="nin_card")
+uverify.aml.screen(name="Adaeze Okafor", date_of_birth="1990-01-15")
+uverify.aml.monitors.create(name="Adaeze Okafor")
+link = uverify.kyc.create_link(customer_name="Ada", require_document=True)   # send link["url"]
+
+uverify.verifications.list(status="verified")
+uverify.account.balance()
+```
+
+Responses are plain dicts, exactly as in the [API reference](https://uverify.com.ng/docs).
+
+## Errors
+
+```python
+from uverify import UVerifyError
+
+try:
+    uverify.identity.nin(id_number=id_number)
+except UVerifyError as e:
+    if e.code == "insufficient_balance":
+        ...
+    print(e.code, e.message, e.request_id, e.details)
+```
+
+A check that finds nothing isn’t an error: it returns `status: "not_found"` (and you aren’t charged).
+
+## Retries
+
+Timeouts, connection errors, 5xx and rate limits are retried twice with backoff (`max_retries`, `timeout`). Every check carries a `reference` (generated if you don’t pass one), so a retry never charges twice, and if the first attempt went through you get that result.
+
+## Webhooks
+
+```python
+from uverify import construct_event, UVerifySignatureError
+
+@app.post("/webhooks/uverify")          # Flask/FastAPI/Django: use the raw body
+def hook():
+    try:
+        event = construct_event(request.get_data(), request.headers.get("UVerify-Signature"), WEBHOOK_SECRET)
+    except UVerifySignatureError:
+        return "", 400
+    if event["type"] == "verification.completed":
+        ...
+    return "", 200
+```
+
+Deliveries can repeat: dedupe on `event["id"]`.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests                       # offline
+UVERIFY_TEST_KEY=uvk_test_... python -m unittest tests.test_sandbox
+```
+
+MIT licence.

uverify-0.1.0/README.md

@@ -0,0 +1,101 @@
+# UVerify for Python
+
+The official Python library for [UVerify](https://uverify.com.ng): BVN, NIN, driver’s licence and voter’s card checks, liveness and face match, ID documents, AML screening and CAC, for Nigerian businesses.
+
+```bash
+pip install uverify
+```
+
+Python 3.8 or later. No dependencies.
+
+## Quick start
+
+```python
+from uverify import UVerify
+
+uverify = UVerify("uvk_test_...")  # or set UVERIFY_API_KEY; uvk_test_ is the free sandbox
+
+v = uverify.identity.nin(id_number="12345678901", first_name="Adaeze", last_name="Okafor")
+if v["status"] == "verified":
+    print(v["data"], v["field_matches"])
+```
+
+In the sandbox the last two digits of the ID number choose the result: `00` not found, `99` registry error, `98` face mismatch, anything else verified.
+
+## A live customer, end to end
+
+```python
+session = uverify.liveness.create_session(redirect_url="https://yourapp.com/kyc/done")
+# send the person to session["url"]; when they come back:
+v = uverify.identity.bvn_face_match(
+    id_number="22212345678", first_name="Adaeze", last_name="Okafor",
+    liveness_session_id=session["id"],
+    aml_screening=True,
+)
+if v["status"] == "verified" and v["face_match"]["status"] == "matched" and v["aml_screening"]["status"] == "clear":
+    ...  # approve
+```
+
+## Everything else
+
+```python
+uverify.identity.bvn(id_number=..., first_name=..., last_name=...)       # also drivers_license, voters_card, tin
+uverify.identity.nin_face_match(id_number=..., selfie_image=open("me.jpg", "rb").read())
+uverify.business.cac(id_number="RC123456", aml_screening=True)
+
+uverify.documents.verify(front_image=open("nin.jpg", "rb").read(), document_type="nin_card")
+uverify.aml.screen(name="Adaeze Okafor", date_of_birth="1990-01-15")
+uverify.aml.monitors.create(name="Adaeze Okafor")
+link = uverify.kyc.create_link(customer_name="Ada", require_document=True)   # send link["url"]
+
+uverify.verifications.list(status="verified")
+uverify.account.balance()
+```
+
+Responses are plain dicts, exactly as in the [API reference](https://uverify.com.ng/docs).
+
+## Errors
+
+```python
+from uverify import UVerifyError
+
+try:
+    uverify.identity.nin(id_number=id_number)
+except UVerifyError as e:
+    if e.code == "insufficient_balance":
+        ...
+    print(e.code, e.message, e.request_id, e.details)
+```
+
+A check that finds nothing isn’t an error: it returns `status: "not_found"` (and you aren’t charged).
+
+## Retries
+
+Timeouts, connection errors, 5xx and rate limits are retried twice with backoff (`max_retries`, `timeout`). Every check carries a `reference` (generated if you don’t pass one), so a retry never charges twice, and if the first attempt went through you get that result.
+
+## Webhooks
+
+```python
+from uverify import construct_event, UVerifySignatureError
+
+@app.post("/webhooks/uverify")          # Flask/FastAPI/Django: use the raw body
+def hook():
+    try:
+        event = construct_event(request.get_data(), request.headers.get("UVerify-Signature"), WEBHOOK_SECRET)
+    except UVerifySignatureError:
+        return "", 400
+    if event["type"] == "verification.completed":
+        ...
+    return "", 200
+```
+
+Deliveries can repeat: dedupe on `event["id"]`.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests                       # offline
+UVERIFY_TEST_KEY=uvk_test_... python -m unittest tests.test_sandbox
+```
+
+MIT licence.

uverify-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uverify"
+version = "0.1.0"
+description = "Official Python library for the UVerify API: BVN, NIN and ID checks, liveness, face match, ID documents and AML screening for Nigeria."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Elasto Web Services Limited" }]
+keywords = ["uverify", "kyc", "bvn", "nin", "liveness", "face-match", "aml", "nigeria"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://uverify.com.ng"
+Documentation = "https://uverify.com.ng/docs"
+Source = "https://github.com/elastodev/uverify-sdks"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uverify"]

uverify-0.1.0/src/uverify/__init__.py

@@ -0,0 +1,8 @@
+"""Official Python library for the UVerify API (https://uverify.com.ng/docs)."""
+
+from .client import VERSION, UVerify
+from .errors import UVerifyConnectionError, UVerifyError, UVerifySignatureError
+from .webhooks import construct_event, sign_payload
+
+__version__ = VERSION
+__all__ = ["UVerify", "UVerifyError", "UVerifyConnectionError", "UVerifySignatureError", "construct_event", "sign_payload", "__version__"]

uverify-0.1.0/src/uverify/client.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import platform
+import random
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+from . import webhooks as _webhooks
+from .errors import UVerifyConnectionError, UVerifyError
+
+VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://api.uverify.com.ng/v1"
+IMAGE_FIELDS = ("selfie_image", "front_image", "back_image")
+
+#: (method, url, headers, body, timeout seconds) -> (status, headers, body bytes)
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Dict[str, str], bytes]]
+
+ImageInput = Union[bytes, bytearray, str]
+Json = Dict[str, Any]
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Dict[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+    except urllib.error.HTTPError as e:  # 4xx/5xx still carry a JSON body
+        with e:
+            return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read()
+
+
+def _new_reference(prefix: str) -> str:
+    return f"{prefix}_{secrets.token_urlsafe(9)}"
+
+
+def _b64(v: ImageInput) -> str:
+    return v if isinstance(v, str) else base64.b64encode(bytes(v)).decode()
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * 2**attempt) * (0.75 + random.random() * 0.5)
+
+
+class _DuplicateOnRetry(Exception):
+    def __init__(self, err: UVerifyError) -> None:
+        self.err = err
+
+
+class UVerify:
+    """The UVerify API client.
+
+    >>> from uverify import UVerify
+    >>> uverify = UVerify(api_key="uvk_test_...")
+    >>> v = uverify.identity.nin(id_number="12345678901")
+    >>> v["status"]
+    'verified'
+    """
+
+    webhooks = _webhooks
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        key = api_key or os.environ.get("UVERIFY_API_KEY", "")
+        if not key:
+            raise ValueError("UVerify: pass api_key (uvk_test_... or uvk_live_...) or set UVERIFY_API_KEY.")
+        self._key = key
+        self._base = (base_url or os.environ.get("UVERIFY_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._transport = transport or _urllib_transport
+        self.identity = _Identity(self)
+        self.business = _Business(self)
+        self.verifications = _Verifications(self)
+        self.liveness = _Liveness(self)
+        self.documents = _Documents(self)
+        self.aml = _Aml(self)
+        self.kyc = _Kyc(self)
+        self.account = _Account(self)
+
+    @property
+    def environment(self) -> str:
+        """``"test"`` for a sandbox key, ``"live"`` for a live one."""
+        return "live" if "_live_" in self._key else "test"
+
+    # ── transport ──────────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, *, query: Optional[Json] = None, body: Optional[Json] = None, retryable: Optional[bool] = None) -> Any:
+        url = self._base + path
+        q = {k: ("true" if v is True else "false" if v is False else v) for k, v in (query or {}).items() if v is not None}
+        if q:
+            url += "?" + urllib.parse.urlencode(q)
+        data = json.dumps({k: v for k, v in body.items() if v is not None}).encode() if body is not None else None
+        headers = {
+            "authorization": f"Bearer {self._key}",
+            "accept": "application/json",
+            "user-agent": f"uverify-python/{VERSION} python/{platform.python_version()}",
+        }
+        if data is not None:
+            headers["content-type"] = "application/json"
+        can_retry = (method == "GET") if retryable is None else retryable
+
+        attempt = 0
+        while True:
+            try:
+                status, rh, raw = self._transport(method, url, headers, data, self._timeout)
+            except Exception as e:  # timeout, DNS, reset
+                if can_retry and attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise UVerifyConnectionError(f"Couldn't reach UVerify: {e}") from e
+
+            try:
+                payload = json.loads(raw.decode() or "null")
+            except ValueError:
+                payload = None
+            if 200 <= status < 300 and not (isinstance(payload, dict) and payload.get("success") is False):
+                return payload.get("data", payload) if isinstance(payload, dict) else payload
+
+            e_obj = (payload or {}).get("error") or {} if isinstance(payload, dict) else {}
+            err = UVerifyError(
+                e_obj.get("message") or f"UVerify returned HTTP {status}.",
+                code=e_obj.get("code") or ("internal_error" if status >= 500 else "http_error"),
+                status=status,
+                request_id=(payload or {}).get("request_id") if isinstance(payload, dict) else rh.get("x-request-id"),
+                details=e_obj.get("details"),
+            )
+            rate_limited = status == 429 and err.code == "rate_limited"
+            if can_retry and attempt < self._max_retries and (rate_limited or (status >= 500 and status != 501)):
+                after = (err.details or {}).get("retry_after_seconds") if isinstance(err.details, dict) else None
+                time.sleep(min(float(after), 60.0) if rate_limited and after else _backoff(attempt))
+                attempt += 1
+                continue
+            if attempt > 0 and err.code == "duplicate_reference":
+                raise _DuplicateOnRetry(err)
+            raise err
+
+    def _prepare(self, params: Json, prefix: str) -> Json:
+        body = dict(params)
+        body.setdefault("reference", None)
+        if not body["reference"]:
+            body["reference"] = _new_reference(prefix)
+        for f in IMAGE_FIELDS:
+            if body.get(f) is not None:
+                body[f] = _b64(body[f])
+        return body
+
+    def _check(self, path: str, params: Json) -> Json:
+        """An identity/business check: always carries a reference, so a retry never charges twice."""
+        body = self._prepare(params, "sdk")
+        try:
+            return self._request("POST", path, body=body, retryable=True)
+        except _DuplicateOnRetry as d:
+            # The first attempt went through but its answer was lost: return that result.
+            found = self.verifications.list(reference=body["reference"], per_page=1)
+            if found["items"]:
+                return self.verifications.get(found["items"][0]["id"])
+            raise d.err from None
+
+    def _create(self, path: str, params: Json, prefix: str) -> Json:
+        try:
+            return self._request("POST", path, body=self._prepare(params, prefix), retryable=True)
+        except _DuplicateOnRetry as d:
+            raise d.err from None
+
+
+def _q(v: str) -> str:
+    return urllib.parse.quote(v, safe="")
+
+
+class _Resource:
+    def __init__(self, client: UVerify) -> None:
+        self._c = client
+
+
+class _Identity(_Resource):
+    def bvn(self, *, id_number: str, first_name: str, last_name: str, **kw: Any) -> Json:
+        """BVN lookup. Names are required by the registry. Also: dob, include_photo, reference, aml_screening, aml_monitoring."""
+        return self._c._check("/identity/bvn", {"id_number": id_number, "first_name": first_name, "last_name": last_name, **kw})
+
+    def bvn_face_match(self, *, id_number: str, first_name: str, last_name: str, liveness_session_id: Optional[str] = None, selfie_image: Optional[ImageInput] = None, **kw: Any) -> Json:
+        """BVN lookup + face match. Send liveness_session_id (recommended) or selfie_image (bytes or base64)."""
+        return self._c._check("/identity/bvn/face-match", {"id_number": id_number, "first_name": first_name, "last_name": last_name, "liveness_session_id": liveness_session_id, "selfie_image": selfie_image, **kw})
+
+    def nin(self, *, id_number: str, **kw: Any) -> Json:
+        return self._c._check("/identity/nin", {"id_number": id_number, **kw})
+
+    def nin_face_match(self, *, id_number: str, liveness_session_id: Optional[str] = None, selfie_image: Optional[ImageInput] = None, **kw: Any) -> Json:
+        return self._c._check("/identity/nin/face-match", {"id_number": id_number, "liveness_session_id": liveness_session_id, "selfie_image": selfie_image, **kw})
+
+    def drivers_license(self, *, id_number: str, first_name: str, last_name: str, **kw: Any) -> Json:
+        return self._c._check("/identity/drivers-license", {"id_number": id_number, "first_name": first_name, "last_name": last_name, **kw})
+
+    def drivers_license_face_match(self, *, id_number: str, first_name: str, last_name: str, liveness_session_id: Optional[str] = None, selfie_image: Optional[ImageInput] = None, **kw: Any) -> Json:
+        return self._c._check("/identity/drivers-license/face-match", {"id_number": id_number, "first_name": first_name, "last_name": last_name, "liveness_session_id": liveness_session_id, "selfie_image": selfie_image, **kw})
+
+    def voters_card(self, *, id_number: str, first_name: str, last_name: str, **kw: Any) -> Json:
+        return self._c._check("/identity/voters-card", {"id_number": id_number, "first_name": first_name, "last_name": last_name, **kw})
+
+    def voters_card_face_match(self, *, id_number: str, first_name: str, last_name: str, liveness_session_id: Optional[str] = None, selfie_image: Optional[ImageInput] = None, **kw: Any) -> Json:
+        return self._c._check("/identity/voters-card/face-match", {"id_number": id_number, "first_name": first_name, "last_name": last_name, "liveness_session_id": liveness_session_id, "selfie_image": selfie_image, **kw})
+
+    def tin(self, *, id_number: str, reference: Optional[str] = None) -> Json:
+        return self._c._check("/identity/tin", {"id_number": id_number, "reference": reference})
+
+
+class _Business(_Resource):
+    def cac(self, *, id_number: str, **kw: Any) -> Json:
+        """CAC lookup (RC/BN/IT number). aml_screening=True screens the company and each director."""
+        return self._c._check("/business/cac", {"id_number": id_number, **kw})
+
+
+class _Verifications(_Resource):
+    def list(self, **params: Any) -> Json:
+        """Filters: type, service, status, reference, page, per_page."""
+        return self._c._request("GET", "/verifications", query=params)
+
+    def get(self, id: str) -> Json:
+        """One verification, with its record."""
+        return self._c._request("GET", f"/verifications/{_q(id)}")
+
+
+class _Liveness(_Resource):
+    def create_session(self, **params: Any) -> Json:
+        """A hosted camera check: send the person to session["url"], then pass session["id"] to a face match."""
+        return self._c._create("/liveness/sessions", params, "lv")
+
+    def get_session(self, id: str) -> Json:
+        return self._c._request("GET", f"/liveness/sessions/{_q(id)}")
+
+    def simulate(self, id: str, *, outcome: str, face: Optional[str] = None) -> Json:
+        """Sandbox only: finish a session without a camera (passed, failed or expired)."""
+        return self._c._request("POST", f"/liveness/sessions/{_q(id)}/simulate", body={"outcome": outcome, "face": face})
+
+
+class _Documents(_Resource):
+    def verify(self, *, front_image: ImageInput, **params: Any) -> Json:
+        """Read and check a photo of an ID. Images: bytes or base64. Also: back_image, document_type, liveness_session_id, selfie_image, verify_with_registry, reference."""
+        return self._c._create("/documents/verify", {"front_image": front_image, **params}, "doc")
+
+    def get(self, id: str) -> Json:
+        return self._c._request("GET", f"/documents/{_q(id)}")
+
+
+class _Monitors(_Resource):
+    def create(self, *, name: str, **params: Any) -> Json:
+        """Screen a name now and keep watching it (billed monthly)."""
+        return self._c._create("/aml/monitors", {"name": name, **params}, "amon")
+
+    def list(self, **params: Any) -> Json:
+        return self._c._request("GET", "/aml/monitors", query=params)
+
+    def get(self, id: str) -> Json:
+        return self._c._request("GET", f"/aml/monitors/{_q(id)}")
+
+    def stop(self, id: str) -> Json:
+        return self._c._request("DELETE", f"/aml/monitors/{_q(id)}", retryable=True)
+
+
+class _Aml(_Resource):
+    def __init__(self, client: UVerify) -> None:
+        super().__init__(client)
+        self.monitors = _Monitors(client)
+
+    def screen(self, *, name: str, **params: Any) -> Json:
+        """Screen a person or organisation (entity_type="entity") against the UN, OFAC, UK, EU and Nigeria lists."""
+        return self._c._create("/aml/screen", {"name": name, **params}, "aml")
+
+    def get_screening(self, id: str) -> Json:
+        return self._c._request("GET", f"/aml/screenings/{_q(id)}")
+
+    def lists(self) -> Any:
+        return self._c._request("GET", "/aml/lists")
+
+
+class _Kyc(_Resource):
+    def create_link(self, **params: Any) -> Json:
+        """A hosted verification link: send link["url"] to your customer."""
+        return self._c._create("/kyc/requests", params, "kyc")
+
+    def get_link(self, id: str) -> Json:
+        return self._c._request("GET", f"/kyc/requests/{_q(id)}")
+
+    def list_links(self, **params: Any) -> Json:
+        return self._c._request("GET", "/kyc/requests", query=params)
+
+
+class _Account(_Resource):
+    def balance(self) -> Json:
+        return self._c._request("GET", "/balance")
+
+    def pricing(self) -> Any:
+        return self._c._request("GET", "/pricing")

uverify-0.1.0/src/uverify/errors.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class UVerifyError(Exception):
+    """Every API error. Branch on ``code``: it's stable (https://uverify.com.ng/docs#responses)."""
+
+    def __init__(self, message: str, *, code: str, status: int, request_id: Optional[str] = None, details: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        #: e.g. validation_error, insufficient_balance, duplicate_reference, rate_limited
+        self.code = code
+        #: HTTP status (0 when no response arrived)
+        self.status = status
+        #: Quote this to UVerify support to trace the request
+        self.request_id = request_id
+        #: Field errors for validation_error; retry_after_seconds for rate_limited; ...
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"UVerifyError(code={self.code!r}, status={self.status}, message={self.message!r}, request_id={self.request_id!r})"
+
+
+class UVerifyConnectionError(UVerifyError):
+    """The request didn't complete (timeout, DNS, connection reset). Safe to retry with the same reference."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="connection_error", status=0)
+
+
+class UVerifySignatureError(Exception):
+    """A webhook failed signature or timestamp verification. Don't trust its body."""

uverify-0.1.0/src/uverify/webhooks.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional, Union
+
+from .errors import UVerifySignatureError
+
+
+def construct_event(raw_body: Union[bytes, str], signature_header: Optional[str], secret: str, tolerance_seconds: int = 300) -> Dict[str, Any]:
+    """Verify a webhook and return its event (a dict: id, type, created_at, environment, data).
+
+    Pass the raw request body exactly as received, the ``UVerify-Signature``
+    header and your endpoint's signing secret (``whsec_...``). Raises
+    :class:`UVerifySignatureError` if the signature doesn't match or the event
+    is older than ``tolerance_seconds`` (a replay). Deliveries can repeat:
+    dedupe on ``event["id"]``.
+    """
+    if not signature_header:
+        raise UVerifySignatureError("Missing UVerify-Signature header.")
+    if not secret:
+        raise UVerifySignatureError("Missing webhook secret.")
+    parts = dict(p.strip().split("=", 1) for p in signature_header.split(",") if "=" in p)
+    t, v1 = parts.get("t"), parts.get("v1")
+    if not t or not v1 or not t.isdigit():
+        raise UVerifySignatureError("Malformed UVerify-Signature header.")
+    body = raw_body.decode("utf-8") if isinstance(raw_body, (bytes, bytearray)) else raw_body
+    expected = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, v1):
+        raise UVerifySignatureError("Signature does not match. Check the secret and that you passed the raw body.")
+    if tolerance_seconds > 0 and abs(time.time() - int(t)) > tolerance_seconds:
+        raise UVerifySignatureError("Signature is too old (possible replay).")
+    try:
+        return json.loads(body)
+    except ValueError as e:
+        raise UVerifySignatureError("Body is not JSON.") from e
+
+
+def sign_payload(body: str, secret: str, timestamp: Optional[int] = None) -> str:
+    """Sign a payload the way UVerify does, for your own tests."""
+    t = int(time.time()) if timestamp is None else timestamp
+    return f"t={t},v1={hmac.new(secret.encode(), f'{t}.{body}'.encode(), hashlib.sha256).hexdigest()}"

uverify-0.1.0/tests/test_client.py

@@ -0,0 +1,187 @@
+import base64
+import json
+import os
+import sys
+import time
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from uverify import UVerify, UVerifyConnectionError, UVerifyError, UVerifySignatureError, construct_event, sign_payload  # noqa: E402
+from uverify import client as client_mod  # noqa: E402
+
+client_mod._backoff = lambda attempt: 0.0  # no real waiting in tests
+
+
+def ok(data, status=200):
+    return status, {"content-type": "application/json"}, json.dumps({"success": True, "data": data, "request_id": "req_1"}).encode()
+
+
+def fail(status, code, message="nope", details=None):
+    return status, {}, json.dumps({"success": False, "error": {"code": code, "message": message, "details": details}, "request_id": "req_err"}).encode()
+
+
+class Fake:
+    """A transport that answers from handlers in order, recording each call."""
+
+    def __init__(self, *handlers):
+        self.handlers = handlers
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        call = {"method": method, "url": url, "headers": headers, "body": json.loads(body) if body else None}
+        self.calls.append(call)
+        h = self.handlers[min(len(self.calls) - 1, len(self.handlers) - 1)]
+        r = h(call)
+        if r == "network-error":
+            raise OSError("connection reset")
+        return r
+
+
+def client(t, **kw):
+    return UVerify("uvk_test_abc", base_url="https://api.test/v1", transport=t, **kw)
+
+
+class Requests(unittest.TestCase):
+    def test_auth_reference_and_unwrap(self):
+        t = Fake(lambda c: ok({"id": "v1", "status": "verified"}))
+        v = client(t).identity.nin(id_number="12345678901")
+        self.assertEqual(v, {"id": "v1", "status": "verified"})
+        self.assertEqual(t.calls[0]["url"], "https://api.test/v1/identity/nin")
+        self.assertEqual(t.calls[0]["headers"]["authorization"], "Bearer uvk_test_abc")
+        self.assertTrue(t.calls[0]["headers"]["user-agent"].startswith("uverify-python/"))
+        self.assertTrue(t.calls[0]["body"]["reference"].startswith("sdk_"))
+
+    def test_own_reference_and_no_nones(self):
+        t = Fake(lambda c: ok({}))
+        client(t).identity.bvn(id_number="22212345678", first_name="Ada", last_name="Okafor", reference="mine-1", dob=None)
+        self.assertEqual(t.calls[0]["body"], {"id_number": "22212345678", "first_name": "Ada", "last_name": "Okafor", "reference": "mine-1"})
+
+    def test_bytes_images_become_base64(self):
+        t = Fake(lambda c: ok({}))
+        client(t).identity.nin_face_match(id_number="1", selfie_image=b"jpeg-bytes")
+        client(t).documents.verify(front_image=bytes([1, 2, 3]), back_image="already-base64")
+        self.assertEqual(t.calls[0]["body"]["selfie_image"], base64.b64encode(b"jpeg-bytes").decode())
+        self.assertEqual(t.calls[1]["body"]["front_image"], "AQID")
+        self.assertEqual(t.calls[1]["body"]["back_image"], "already-base64")
+
+    def test_list_query(self):
+        t = Fake(lambda c: ok({"items": [], "pagination": {}}))
+        client(t).verifications.list(status="verified", page=2)
+        self.assertEqual(t.calls[0]["url"], "https://api.test/v1/verifications?status=verified&page=2")
+
+    def test_environment_and_key(self):
+        self.assertEqual(UVerify("uvk_live_x").environment, "live")
+        self.assertEqual(UVerify("uvk_test_x").environment, "test")
+        was = os.environ.pop("UVERIFY_API_KEY", None)
+        with self.assertRaises(ValueError):
+            UVerify()
+        if was:
+            os.environ["UVERIFY_API_KEY"] = was
+
+
+class Errors(unittest.TestCase):
+    def test_error_fields(self):
+        t = Fake(lambda c: fail(400, "validation_error", "One or more fields are invalid.", ["id_number must be the 11-digit NIN"]))
+        with self.assertRaises(UVerifyError) as cm:
+            client(t).identity.nin(id_number="x")
+        e = cm.exception
+        self.assertEqual((e.code, e.status, e.request_id, e.details), ("validation_error", 400, "req_err", ["id_number must be the 11-digit NIN"]))
+
+    def test_4xx_not_retried(self):
+        t = Fake(lambda c: fail(402, "insufficient_balance"))
+        with self.assertRaises(UVerifyError):
+            client(t).identity.nin(id_number="1")
+        self.assertEqual(len(t.calls), 1)
+
+
+class Retries(unittest.TestCase):
+    def test_5xx_then_ok_same_reference(self):
+        t = Fake(lambda c: fail(503, "internal_error"), lambda c: ok({"id": "v1"}))
+        self.assertEqual(client(t).identity.nin(id_number="1"), {"id": "v1"})
+        self.assertEqual(t.calls[0]["body"]["reference"], t.calls[1]["body"]["reference"])
+
+    def test_rate_limit(self):
+        t = Fake(lambda c: fail(429, "rate_limited", "slow", {"retry_after_seconds": 0}), lambda c: ok({"balance": 5}))
+        self.assertEqual(client(t).account.balance(), {"balance": 5})
+        self.assertEqual(len(t.calls), 2)
+
+    def test_recovers_lost_answer(self):
+        t = Fake(
+            lambda c: "network-error",
+            lambda c: fail(409, "duplicate_reference"),
+            lambda c: ok({"items": [{"id": "v9"}], "pagination": {}}) if "/verifications?" in c["url"] else fail(500, "x"),
+            lambda c: ok({"id": "v9", "data": {"first_name": "ADA"}}) if c["url"].endswith("/verifications/v9") else fail(500, "x"),
+        )
+        v = client(t).identity.nin(id_number="1")
+        self.assertEqual(v["id"], "v9")
+        self.assertIn(f"reference={t.calls[0]['body']['reference']}", t.calls[2]["url"])
+
+    def test_gives_up(self):
+        t = Fake(lambda c: "network-error")
+        with self.assertRaises(UVerifyConnectionError):
+            client(t, max_retries=1).identity.nin(id_number="1")
+        self.assertEqual(len(t.calls), 2)
+
+    def test_simulate_not_retried(self):
+        t = Fake(lambda c: fail(500, "internal_error"))
+        with self.assertRaises(UVerifyError):
+            client(t).liveness.simulate("s1", outcome="passed")
+        self.assertEqual(len(t.calls), 1)
+
+
+class Webhooks(unittest.TestCase):
+    secret = "whsec_test123"
+    body = json.dumps({"id": "evt_1", "type": "verification.completed", "created_at": "2026-09-30T10:00:00Z", "environment": "live", "data": {"id": "v1"}})
+
+    def test_valid(self):
+        e = construct_event(self.body, sign_payload(self.body, self.secret), self.secret)
+        self.assertEqual(e["id"], "evt_1")
+        self.assertEqual(UVerify.webhooks.construct_event(self.body.encode(), sign_payload(self.body, self.secret), self.secret)["type"], "verification.completed")
+
+    def test_rejects(self):
+        sig = sign_payload(self.body, self.secret)
+        for args in [(self.body.replace("v1", "v2"), sig, self.secret), (self.body, sig, "whsec_other"), (self.body, None, self.secret), (self.body, "v1=abc", self.secret)]:
+            with self.assertRaises(UVerifySignatureError):
+                construct_event(*args)
+        old = sign_payload(self.body, self.secret, int(time.time()) - 3600)
+        with self.assertRaises(UVerifySignatureError):
+            construct_event(self.body, old, self.secret)
+        self.assertEqual(construct_event(self.body, old, self.secret, tolerance_seconds=0)["id"], "evt_1")
+
+    def test_matches_node_and_server(self):
+        # Same inputs as the Node SDK's test: identical signatures across languages.
+        import hashlib
+        import hmac
+        t = 1790590000
+        expected = hmac.new(self.secret.encode(), f"{t}.{self.body}".encode(), hashlib.sha256).hexdigest()
+        self.assertEqual(sign_payload(self.body, self.secret, t), f"t={t},v1={expected}")
+
+
+class Contract(unittest.TestCase):
+    def test_covers_every_public_route(self):
+        routes = json.loads((Path(__file__).resolve().parents[2] / "contract" / "public-api.json").read_text())["routes"]
+        seen = set()
+
+        def transport(method, url, headers, body, timeout):
+            path = url.split("/v1", 1)[1].split("?")[0].replace("/id-x", "/{id}")
+            seen.add(f"{method} {path}")
+            return ok({"items": [], "pagination": {}})
+
+        u = client(transport)
+        p = dict(id_number="1", first_name="A", last_name="B")
+        u.identity.bvn(**p); u.identity.bvn_face_match(**p, liveness_session_id="s"); u.identity.nin(id_number="1"); u.identity.nin_face_match(id_number="1", liveness_session_id="s")
+        u.identity.drivers_license(**p); u.identity.drivers_license_face_match(**p, liveness_session_id="s"); u.identity.voters_card(**p); u.identity.voters_card_face_match(**p, liveness_session_id="s")
+        u.identity.tin(id_number="1"); u.business.cac(id_number="RC1")
+        u.verifications.list(); u.verifications.get("id-x"); u.account.balance(); u.account.pricing()
+        u.liveness.create_session(); u.liveness.get_session("id-x"); u.liveness.simulate("id-x", outcome="passed")
+        u.documents.verify(front_image="x"); u.documents.get("id-x")
+        u.aml.screen(name="A B"); u.aml.get_screening("id-x"); u.aml.lists()
+        u.aml.monitors.create(name="A B"); u.aml.monitors.list(); u.aml.monitors.get("id-x"); u.aml.monitors.stop("id-x")
+        u.kyc.create_link(); u.kyc.list_links(); u.kyc.get_link("id-x")
+        self.assertEqual([r for r in routes if r not in seen], [])
+
+
+if __name__ == "__main__":
+    unittest.main()

uverify-0.1.0/tests/test_http.py

@@ -0,0 +1,68 @@
+"""The real urllib transport, against a local HTTP server (no network)."""
+import json
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from uverify import UVerify, UVerifyError  # noqa: E402
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *a):  # quiet
+        pass
+
+    def _send(self, status, obj):
+        body = json.dumps(obj).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if self.headers.get("authorization") != "Bearer uvk_test_local":
+            return self._send(401, {"success": False, "error": {"code": "invalid_api_key", "message": "Bad key"}, "request_id": "req_401"})
+        self._send(200, {"success": True, "data": {"balance": 1234.5, "currency": "NGN"}, "request_id": "req_ok"})
+
+    def do_POST(self):
+        n = int(self.headers.get("content-length") or 0)
+        body = json.loads(self.rfile.read(n) or b"{}")
+        if body.get("id_number") == "bad":
+            return self._send(400, {"success": False, "error": {"code": "validation_error", "message": "Invalid", "details": ["id_number must be the 11-digit NIN"]}, "request_id": "req_400"})
+        self._send(200, {"success": True, "data": {"id": "v1", "status": "verified", "echo": body}, "request_id": "req_ok"})
+
+
+class RealHttp(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_port}/v1"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def test_get_and_post(self):
+        u = UVerify("uvk_test_local", base_url=self.base)
+        self.assertEqual(u.account.balance()["balance"], 1234.5)
+        v = u.identity.nin(id_number="12345678901")
+        self.assertEqual(v["status"], "verified")
+        self.assertTrue(v["echo"]["reference"].startswith("sdk_"))
+
+    def test_error_bodies_are_read(self):
+        with self.assertRaises(UVerifyError) as cm:
+            UVerify("uvk_test_local", base_url=self.base).identity.nin(id_number="bad")
+        self.assertEqual((cm.exception.code, cm.exception.status, cm.exception.request_id), ("validation_error", 400, "req_400"))
+        with self.assertRaises(UVerifyError) as cm:
+            UVerify("uvk_test_wrong", base_url=self.base).account.balance()
+        self.assertEqual(cm.exception.code, "invalid_api_key")
+
+
+if __name__ == "__main__":
+    unittest.main()

uverify-0.1.0/tests/test_sandbox.py

@@ -0,0 +1,44 @@
+"""The real API, in sandbox (free). Runs only with UVERIFY_TEST_KEY=uvk_test_... set."""
+import os
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from uverify import UVerify, UVerifyError  # noqa: E402
+
+KEY = os.environ.get("UVERIFY_TEST_KEY", "")
+JPEG = bytes.fromhex("ffd8ffe000104a46494600010100000100010000ffdb004300080606070605080707070909080a0c140d0c0b0b0c1912130f141d1a1f1e1d1a1c1c20242e2720222c231c1c2837292c30313434341f27393d38323c2e333432ffc0000b080001000101011100ffc4001400010000000000000000000000000000000affc40014100100000000000000000000000000000000ffda0008010100003f002a9fffd9")
+
+
+@unittest.skipUnless(KEY.startswith("uvk_test_"), "set UVERIFY_TEST_KEY to run against the sandbox")
+class Sandbox(unittest.TestCase):
+    def setUp(self):
+        self.u = UVerify(KEY, base_url=os.environ.get("UVERIFY_BASE_URL"))
+
+    def test_nin(self):
+        self.assertEqual(self.u.identity.nin(id_number="12345678942")["status"], "verified")
+        self.assertEqual(self.u.identity.nin(id_number="12345678900")["status"], "not_found")
+
+    def test_liveness_face_match(self):
+        s = self.u.liveness.create_session()
+        self.u.liveness.simulate(s["id"], outcome="passed")
+        v = self.u.identity.nin_face_match(id_number="12345678942", liveness_session_id=s["id"])
+        self.assertEqual((v["face_match"]["status"], v["face_match"]["liveness"]), ("matched", "passed"))
+
+    def test_the_rest(self):
+        self.assertEqual(self.u.documents.verify(front_image=JPEG, document_type="nin_card")["status"], "verified")
+        self.assertEqual(self.u.aml.screen(name="Adaeze Okafor")["status"], "clear")
+        link = self.u.kyc.create_link(customer_name="SDK Test")
+        self.assertEqual(self.u.kyc.get_link(link["id"])["status"], "pending")
+        self.assertIsInstance(self.u.account.balance()["balance"], (int, float))
+
+    def test_validation_error(self):
+        with self.assertRaises(UVerifyError) as cm:
+            self.u.identity.nin(id_number="abc")
+        self.assertEqual(cm.exception.code, "validation_error")
+
+
+if __name__ == "__main__":
+    unittest.main()