ontiver 0.1.0__tar.gz

ontiver-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: ontiver
+Version: 0.1.0
+Summary: Official Python SDK for the Ontiver API
+Author: Ontiver
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://ontiver.com
+Project-URL: Documentation, https://docs.ontiver.com
+Project-URL: Repository, https://github.com/joinverza/Ontiver
+Keywords: ontiver,kyc,aml,identity,proofs,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == "build"
+Requires-Dist: twine>=5; extra == "build"
+
+# Ontiver Python SDK
+
+Official Python SDK for integrating Ontiver verification, screening, proofs, and webhooks into enterprise backends.
+
+The dashboard remains the control plane for API keys, scopes, billing, team roles, webhooks, and audit logs. The SDK is the integration layer for Django, Flask, FastAPI, workers, and internal services.
+
+## Install Locally
+
+From this repository:
+
+```bash
+cd sdks/python
+python -m pip install -e ".[test]"
+```
+
+After publication:
+
+```bash
+python -m pip install ontiver
+```
+
+## Configuration
+
+Create an API key from the Ontiver enterprise dashboard and store it in your secret manager.
+
+```bash
+ONTIVER_API_KEY=prod_xxx
+ONTIVER_BASE_URL=https://api.ontiver.com
+ONTIVER_ENVIRONMENT=production
+ONTIVER_WEBHOOK_SECRET=whsec_xxx
+```
+
+Use sandbox keys in non-production environments:
+
+```bash
+ONTIVER_API_KEY=sb_xxx
+ONTIVER_ENVIRONMENT=sandbox
+```
+
+## Quickstart
+
+```python
+from ontiver import OntiverClient
+
+client = OntiverClient.from_env()
+
+startup_check = client.validate_api_key()
+print(startup_check["valid"])
+```
+
+## Verification
+
+SDK v1 routes flexible verification payloads to:
+
+```text
+POST /api/v1/banking/kyc/individual/verify
+GET  /api/v1/banking/kyc/individual/{verificationId}
+```
+
+```python
+result = client.verifications.create(
+    {
+        "customerId": "cust_123",
+        "firstName": "Ada",
+        "lastName": "Okafor",
+        "country": "NG",
+        "idDocumentType": "passport",
+        "idDocumentNumber": "A12345678",
+    },
+    idempotency_key="verify-cust-123",
+)
+
+status = client.verifications.get(result["verificationId"])
+```
+
+## Screening
+
+```python
+screening = client.screening.sanctions_check(
+    first_name="Ada",
+    last_name="Okafor",
+    nationality="NG",
+    idempotency_key="sanctions-cust-123",
+)
+```
+
+Supported methods:
+
+- `client.screening.pep_check(...)`
+- `client.screening.sanctions_check(...)`
+- `client.screening.adverse_media_check(first_name, last_name, ...)`
+
+## Proofs
+
+```python
+proof = client.proofs.get_for_verification("ver_123")
+
+verified = client.proofs.verify(
+    proof_id=proof["proofId"],
+    proof=proof.get("proof"),
+)
+```
+
+Supported methods:
+
+- `client.proofs.generate(...)`
+- `client.proofs.get_for_verification(verification_id)`
+- `client.proofs.verify(proof_id, proof=None)`
+- `client.proofs.disclose(proof_id, fields=[...])`
+
+## Webhooks
+
+Register a webhook:
+
+```python
+webhook = client.webhooks.register(
+    "https://example.com/webhooks/ontiver",
+    ["verification.completed", "proof.issued"],
+)
+
+# Store this once. It will not be returned by list endpoints.
+secret = webhook["secret"]
+```
+
+Verify webhook signatures using the raw request body:
+
+```python
+from ontiver.webhooks import verify_webhook_signature
+
+is_valid = verify_webhook_signature(raw_body, request.headers["X-Ontiver-Signature"], secret)
+```
+
+Header format:
+
+```text
+X-Ontiver-Signature: sha256=<hex_digest>
+```
+
+## Raw Request Escape Hatch
+
+Use `raw_request()` for routes that do not have first-class wrappers yet:
+
+```python
+result = client.raw_request(
+    "POST",
+    "/aml/smile-checks",
+    json={"fullName": "Ada Okafor", "countries": ["NG"]},
+    idempotency_key="aml-cust-123",
+)
+```
+
+## Errors
+
+Catch specific exceptions:
+
+```python
+from ontiver import AuthenticationError, PermissionDeniedError, RateLimitError, ValidationError
+
+try:
+    client.validate_api_key()
+except AuthenticationError:
+    ...
+except PermissionDeniedError:
+    ...
+except RateLimitError:
+    ...
+except ValidationError:
+    ...
+```
+
+The SDK redacts API keys, bearer tokens, webhook secrets, and secret prefixes from exception messages.
+
+## Security Notes
+
+- Never commit API keys or webhook secrets.
+- Store production secrets in a secret manager.
+- Use least-privilege API key scopes.
+- Use sandbox keys outside production.
+- Verify webhook signatures over the raw body bytes before parsing JSON.
+- Do not log raw identity documents, ID numbers, biometric payloads, or full provider payloads.
+
+## Build And Publish
+
+Build locally:
+
+```bash
+cd sdks/python
+python -m pip install -e ".[test]"
+pytest
+python -m pip install ".[build]"
+python -m build
+python -m twine check dist/*
+```
+
+Publish first to TestPyPI:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a clean environment:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ontiver
+```
+
+Publish to PyPI after TestPyPI install passes:
+
+```bash
+python -m twine upload dist/*
+```
+
+Target package name: `ontiver`.

ontiver-0.1.0/README.md

@@ -0,0 +1,213 @@
+# Ontiver Python SDK
+
+Official Python SDK for integrating Ontiver verification, screening, proofs, and webhooks into enterprise backends.
+
+The dashboard remains the control plane for API keys, scopes, billing, team roles, webhooks, and audit logs. The SDK is the integration layer for Django, Flask, FastAPI, workers, and internal services.
+
+## Install Locally
+
+From this repository:
+
+```bash
+cd sdks/python
+python -m pip install -e ".[test]"
+```
+
+After publication:
+
+```bash
+python -m pip install ontiver
+```
+
+## Configuration
+
+Create an API key from the Ontiver enterprise dashboard and store it in your secret manager.
+
+```bash
+ONTIVER_API_KEY=prod_xxx
+ONTIVER_BASE_URL=https://api.ontiver.com
+ONTIVER_ENVIRONMENT=production
+ONTIVER_WEBHOOK_SECRET=whsec_xxx
+```
+
+Use sandbox keys in non-production environments:
+
+```bash
+ONTIVER_API_KEY=sb_xxx
+ONTIVER_ENVIRONMENT=sandbox
+```
+
+## Quickstart
+
+```python
+from ontiver import OntiverClient
+
+client = OntiverClient.from_env()
+
+startup_check = client.validate_api_key()
+print(startup_check["valid"])
+```
+
+## Verification
+
+SDK v1 routes flexible verification payloads to:
+
+```text
+POST /api/v1/banking/kyc/individual/verify
+GET  /api/v1/banking/kyc/individual/{verificationId}
+```
+
+```python
+result = client.verifications.create(
+    {
+        "customerId": "cust_123",
+        "firstName": "Ada",
+        "lastName": "Okafor",
+        "country": "NG",
+        "idDocumentType": "passport",
+        "idDocumentNumber": "A12345678",
+    },
+    idempotency_key="verify-cust-123",
+)
+
+status = client.verifications.get(result["verificationId"])
+```
+
+## Screening
+
+```python
+screening = client.screening.sanctions_check(
+    first_name="Ada",
+    last_name="Okafor",
+    nationality="NG",
+    idempotency_key="sanctions-cust-123",
+)
+```
+
+Supported methods:
+
+- `client.screening.pep_check(...)`
+- `client.screening.sanctions_check(...)`
+- `client.screening.adverse_media_check(first_name, last_name, ...)`
+
+## Proofs
+
+```python
+proof = client.proofs.get_for_verification("ver_123")
+
+verified = client.proofs.verify(
+    proof_id=proof["proofId"],
+    proof=proof.get("proof"),
+)
+```
+
+Supported methods:
+
+- `client.proofs.generate(...)`
+- `client.proofs.get_for_verification(verification_id)`
+- `client.proofs.verify(proof_id, proof=None)`
+- `client.proofs.disclose(proof_id, fields=[...])`
+
+## Webhooks
+
+Register a webhook:
+
+```python
+webhook = client.webhooks.register(
+    "https://example.com/webhooks/ontiver",
+    ["verification.completed", "proof.issued"],
+)
+
+# Store this once. It will not be returned by list endpoints.
+secret = webhook["secret"]
+```
+
+Verify webhook signatures using the raw request body:
+
+```python
+from ontiver.webhooks import verify_webhook_signature
+
+is_valid = verify_webhook_signature(raw_body, request.headers["X-Ontiver-Signature"], secret)
+```
+
+Header format:
+
+```text
+X-Ontiver-Signature: sha256=<hex_digest>
+```
+
+## Raw Request Escape Hatch
+
+Use `raw_request()` for routes that do not have first-class wrappers yet:
+
+```python
+result = client.raw_request(
+    "POST",
+    "/aml/smile-checks",
+    json={"fullName": "Ada Okafor", "countries": ["NG"]},
+    idempotency_key="aml-cust-123",
+)
+```
+
+## Errors
+
+Catch specific exceptions:
+
+```python
+from ontiver import AuthenticationError, PermissionDeniedError, RateLimitError, ValidationError
+
+try:
+    client.validate_api_key()
+except AuthenticationError:
+    ...
+except PermissionDeniedError:
+    ...
+except RateLimitError:
+    ...
+except ValidationError:
+    ...
+```
+
+The SDK redacts API keys, bearer tokens, webhook secrets, and secret prefixes from exception messages.
+
+## Security Notes
+
+- Never commit API keys or webhook secrets.
+- Store production secrets in a secret manager.
+- Use least-privilege API key scopes.
+- Use sandbox keys outside production.
+- Verify webhook signatures over the raw body bytes before parsing JSON.
+- Do not log raw identity documents, ID numbers, biometric payloads, or full provider payloads.
+
+## Build And Publish
+
+Build locally:
+
+```bash
+cd sdks/python
+python -m pip install -e ".[test]"
+pytest
+python -m pip install ".[build]"
+python -m build
+python -m twine check dist/*
+```
+
+Publish first to TestPyPI:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a clean environment:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ontiver
+```
+
+Publish to PyPI after TestPyPI install passes:
+
+```bash
+python -m twine upload dist/*
+```
+
+Target package name: `ontiver`.

ontiver-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ontiver"
+version = "0.1.0"
+description = "Official Python SDK for the Ontiver API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Ontiver" }]
+keywords = ["ontiver", "kyc", "aml", "identity", "proofs", "webhooks"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+build = ["build>=1.2", "twine>=5"]
+
+[project.urls]
+Homepage = "https://ontiver.com"
+Documentation = "https://docs.ontiver.com"
+Repository = "https://github.com/joinverza/Ontiver"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ontiver = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ontiver-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ontiver-0.1.0/src/ontiver/__init__.py

@@ -0,0 +1,33 @@
+from .client import OntiverClient
+from .errors import (
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    OntiverAPIError,
+    OntiverConfigError,
+    OntiverError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+    WebhookSignatureError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OntiverClient",
+    "OntiverError",
+    "OntiverConfigError",
+    "OntiverAPIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "ValidationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ServerError",
+    "TimeoutError",
+    "NetworkError",
+    "WebhookSignatureError",
+]

ontiver-0.1.0/src/ontiver/client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .config import OntiverConfig
+from .http import OntiverHTTPClient
+from .resources.proofs import ProofsResource
+from .resources.screening import ScreeningResource
+from .resources.verifications import VerificationsResource
+from .resources.webhook_management import WebhookManagementResource
+
+
+class OntiverClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        environment: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        webhook_secret: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.config = OntiverConfig.from_env(
+            api_key=api_key,
+            base_url=base_url,
+            environment=environment,
+            webhook_secret=webhook_secret,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = OntiverHTTPClient(self.config, client=http_client)
+        self.webhooks = WebhookManagementResource(self._http)
+        self.verifications = VerificationsResource(self._http)
+        self.screening = ScreeningResource(self._http)
+        self.proofs = ProofsResource(self._http)
+
+    @classmethod
+    def from_env(cls) -> "OntiverClient":
+        return cls()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "OntiverClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def validate_api_key(self) -> dict[str, Any]:
+        return self._http.request("GET", "/api-keys/validate/current")
+
+    def raw_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        return self._http.request(
+            method,
+            path,
+            json=json,
+            params=params,
+            headers=headers,
+            idempotency_key=idempotency_key,
+            unwrap=False,
+        )

ontiver-0.1.0/src/ontiver/config.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from .errors import OntiverConfigError
+
+
+DEFAULT_BASE_URL = "https://api.ontiver.com"
+VALID_ENVIRONMENTS = {"production", "sandbox"}
+LOCAL_HOSTS = {"localhost", "127.0.0.1", "0.0.0.0", "::1"}
+
+
+@dataclass(frozen=True)
+class OntiverConfig:
+    api_key: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    environment: str = "production"
+    webhook_secret: str | None = None
+    timeout: float = 30
+    max_retries: int = 2
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        environment: str | None = None,
+        webhook_secret: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+    ) -> "OntiverConfig":
+        return cls(
+            api_key=api_key if api_key is not None else os.getenv("ONTIVER_API_KEY"),
+            base_url=base_url or os.getenv("ONTIVER_BASE_URL") or DEFAULT_BASE_URL,
+            environment=environment or os.getenv("ONTIVER_ENVIRONMENT") or "production",
+            webhook_secret=webhook_secret if webhook_secret is not None else os.getenv("ONTIVER_WEBHOOK_SECRET"),
+            timeout=timeout,
+            max_retries=max_retries,
+        ).validated()
+
+    def validated(self) -> "OntiverConfig":
+        environment = str(self.environment or "").strip().lower()
+        if environment not in VALID_ENVIRONMENTS:
+            raise OntiverConfigError("environment must be 'production' or 'sandbox'")
+        base_url = normalize_base_url(self.base_url)
+        return OntiverConfig(
+            api_key=str(self.api_key).strip() if self.api_key else None,
+            base_url=base_url,
+            environment=environment,
+            webhook_secret=str(self.webhook_secret).strip() if self.webhook_secret else None,
+            timeout=float(self.timeout),
+            max_retries=max(0, int(self.max_retries)),
+        )
+
+
+def normalize_base_url(value: str | None) -> str:
+    raw = str(value or DEFAULT_BASE_URL).strip().rstrip("/")
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise OntiverConfigError("base_url must be an absolute HTTP(S) URL")
+    hostname = (parsed.hostname or "").lower()
+    if parsed.scheme != "https" and hostname not in LOCAL_HOSTS:
+        raise OntiverConfigError("HTTPS is required for non-local Ontiver API base URLs")
+    return raw