didit-sdk 0.1.0__tar.gz

didit_sdk-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python & bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Distribution & packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing & quality
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# Private workspace & audit roadmap
+.roadmap.md
+.audit/
+
+# IDE & OS
+.vscode/
+.idea/
+.DS_Store
+*.swp
+*.swo

didit_sdk-0.1.0/LICENSE

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

didit_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.5
+Name: didit-sdk
+Version: 0.1.0
+Summary: Unofficial Python SDK for Didit (didit.me) Identity Verification & KYC
+Project-URL: Homepage, https://github.com/agustin18/didit-sdk
+Project-URL: Documentation, https://github.com/agustin18/didit-sdk#readme
+Project-URL: Repository, https://github.com/agustin18/didit-sdk
+Project-URL: Issues, https://github.com/agustin18/didit-sdk/issues
+Author-email: Agustin Saiz <agustinsaiz02@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: biometrics,didit,fastapi,identity-verification,kyc,sdk,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.25.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# didit-sdk
+
+[![CI](https://github.com/agustin18/didit-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/agustin18/didit-sdk/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/didit-sdk.svg)](https://pypi.org/project/didit-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/didit-sdk.svg)](https://pypi.org/project/didit-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Official-grade, community-maintained Python SDK for [Didit](https://didit.me) Identity Verification & KYC.
+
+> [!IMPORTANT]
+> **Legal Disclaimer**: This is an independent, community-driven open-source project and is **not** officially affiliated with, endorsed by, or sponsored by Didit Protocol Inc. All trademarks, service marks, and company names are the property of their respective owners.
+
+---
+
+## Highlights
+
+- **Ergonomic Sync & Async**: Dual-client architecture built on top of high-performance `httpx`.
+- **Strictly Typed & Validated**: 100% type annotations (PEP 561 compliant with `py.typed`) and robust Pydantic v2 domain models.
+- **Cryptographic Security**: Constant-time HMAC-SHA256 signature verification supporting canonical JSON float-normalization (`X-Signature-V2`) and replay-attack protection via timestamp freshness windows.
+- **FastAPI Integration**: Plug-and-play `DiditWebhookGuard` dependency for securing webhook endpoints with zero boilerplate.
+- **Zero-Network Simulation Mode**: Built-in `SimulatedDidit` and `SimulatedAsyncDidit` to run unit tests and local end-to-end user flows completely offline without live credentials.
+- **Resilient Error Hierarchy**: Typed exceptions (`DiditAuthenticationError`, `DiditRateLimitError`, `DiditNotFoundError`, `DiditServerError`) with automated rate-limit retry duration parsing.
+
+---
+
+## Installation
+
+```bash
+# Core SDK (httpx + pydantic)
+pip install didit-sdk
+
+# With FastAPI integration
+pip install "didit-sdk[fastapi]"
+```
+
+---
+
+## Quickstart
+
+### 1. Synchronous Client
+
+```python
+from didit import Didit, SessionStatus
+
+# Initialize client (falls back to DIDIT_API_KEY environment variable if omitted)
+client = Didit(api_key="your_api_key", webhook_secret="your_webhook_secret")
+
+# Create a verification session
+session = client.sessions.create(
+    vendor_data="user_12345",
+    workflow_id="wf_kyc_standard",
+    callback="https://yourapp.com/kyc/complete",
+    language="es",
+)
+
+print(f"Verification URL: {session.url}")
+print(f"Session ID: {session.session_id}")
+
+# Fetch verification decision immediately:
+decision = client.sessions.get_decision(session.session_id)
+
+# Or poll until a terminal outcome (Approved or Declined) is reached:
+decision = client.sessions.poll_decision(session.session_id, timeout=60.0, interval=2.0)
+if decision.status == SessionStatus.APPROVED:
+    print(f"User approved! Document: {decision.document.document_number}")
+```
+
+### 2. Asynchronous Client (`asyncio`)
+
+```python
+import asyncio
+from didit import AsyncDidit, SessionStatus
+
+
+async def main():
+    async with AsyncDidit(api_key="your_api_key") as client:
+        session = await client.sessions.create(
+            vendor_data="user_987",
+            workflow_id="wf_kyc_standard",
+        )
+        print(f"Session URL: {session.url}")
+
+        decision = await client.sessions.get_decision(session.session_id)
+        if decision.status.is_terminal:
+            print(f"Final outcome: {decision.status}")
+
+
+asyncio.run(main())
+```
+
+---
+
+## Securing Webhooks with FastAPI
+
+Didit dispatches signed HTTP POST events upon verification completion. `didit-sdk` provides a dedicated FastAPI dependency to verify signatures in constant time and prevent replay attacks:
+
+```python
+from fastapi import FastAPI, Depends
+from didit import WebhookPayload, SessionStatus
+from didit.integrations.fastapi import DiditWebhookGuard
+
+app = FastAPI()
+
+# Guard reads secret from argument or DIDIT_WEBHOOK_SECRET env var
+webhook_guard = DiditWebhookGuard(secret="whsec_...")
+
+
+@app.post("/api/v1/webhooks/didit")
+async def handle_didit_event(
+    payload: WebhookPayload = Depends(webhook_guard),
+):
+    print(f"Received event for session: {payload.session_id}")
+
+    if payload.status == SessionStatus.APPROVED:
+        # Mark user verified in your database
+        ...
+    elif payload.status == SessionStatus.DECLINED:
+        # Handle rejection
+        ...
+
+    return {"received": True}
+```
+
+---
+
+## Testing & Offline Simulation
+
+Developing without live credentials or mock servers? Use the built-in simulator:
+
+```python
+from didit import SimulatedDidit, SessionStatus
+
+# Create in-memory client
+sim = SimulatedDidit(webhook_secret="test_secret")
+
+# 1. Create a simulated session
+session = sim.sessions.create(vendor_data="dev_user", workflow_id="wf_dev")
+assert session.session_id.startswith("sim_")
+
+# 2. Simulate user passing identity check
+sim.approve_session(session.session_id)
+
+decision = sim.sessions.get_decision(session.session_id)
+assert decision.status == SessionStatus.APPROVED
+
+# 3. Generate signed webhook payloads to test your local receiver
+raw_body, headers = sim.generate_webhook_event(session.session_id)
+# headers contain valid X-Signature-V2 and fresh X-Timestamp!
+```
+
+---
+
+## Exception Handling
+
+All client errors inherit from `DiditError`:
+
+```python
+from didit import Didit
+from didit.errors import (
+    DiditAuthenticationError,
+    DiditNotFoundError,
+    DiditRateLimitError,
+    DiditServerError,
+)
+
+client = Didit()
+
+try:
+    decision = client.sessions.get_decision("non_existent_session")
+except DiditNotFoundError:
+    print("Session not found")
+except DiditRateLimitError as exc:
+    print(f"Rate limited. Retry after {exc.retry_after} seconds.")
+except DiditAuthenticationError:
+    print("Invalid API key")
+except DiditServerError as exc:
+    print(f"Didit server error ({exc.status_code}): {exc.response_body}")
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `DIDIT_API_KEY` | *None* (Required) | Your Didit secret API key |
+| `DIDIT_BASE_URL` | `https://verification.didit.me/v3` | Didit API base URL |
+| `DIDIT_WEBHOOK_SECRET` | *None* | Shared webhook HMAC secret |
+| `DIDIT_TIMEOUT` | `30.0` | HTTP request timeout in seconds |
+| `DIDIT_MAX_RETRIES` | `2` | Maximum retry attempts for transient errors |
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/agustin18/didit-sdk.git
+cd didit-sdk
+
+# Install dependencies with uv
+uv sync --extra dev
+
+# Run unit tests with 100% coverage gate
+uv run pytest --cov=didit --cov-report=term-missing
+
+# Lint & Format check
+uv run ruff check .
+uv run ruff format --check .
+
+# Strict type check
+uv run mypy src/didit
+```
+
+---
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).

didit_sdk-0.1.0/README.md

@@ -0,0 +1,221 @@
+# didit-sdk
+
+[![CI](https://github.com/agustin18/didit-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/agustin18/didit-sdk/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/didit-sdk.svg)](https://pypi.org/project/didit-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/didit-sdk.svg)](https://pypi.org/project/didit-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Official-grade, community-maintained Python SDK for [Didit](https://didit.me) Identity Verification & KYC.
+
+> [!IMPORTANT]
+> **Legal Disclaimer**: This is an independent, community-driven open-source project and is **not** officially affiliated with, endorsed by, or sponsored by Didit Protocol Inc. All trademarks, service marks, and company names are the property of their respective owners.
+
+---
+
+## Highlights
+
+- **Ergonomic Sync & Async**: Dual-client architecture built on top of high-performance `httpx`.
+- **Strictly Typed & Validated**: 100% type annotations (PEP 561 compliant with `py.typed`) and robust Pydantic v2 domain models.
+- **Cryptographic Security**: Constant-time HMAC-SHA256 signature verification supporting canonical JSON float-normalization (`X-Signature-V2`) and replay-attack protection via timestamp freshness windows.
+- **FastAPI Integration**: Plug-and-play `DiditWebhookGuard` dependency for securing webhook endpoints with zero boilerplate.
+- **Zero-Network Simulation Mode**: Built-in `SimulatedDidit` and `SimulatedAsyncDidit` to run unit tests and local end-to-end user flows completely offline without live credentials.
+- **Resilient Error Hierarchy**: Typed exceptions (`DiditAuthenticationError`, `DiditRateLimitError`, `DiditNotFoundError`, `DiditServerError`) with automated rate-limit retry duration parsing.
+
+---
+
+## Installation
+
+```bash
+# Core SDK (httpx + pydantic)
+pip install didit-sdk
+
+# With FastAPI integration
+pip install "didit-sdk[fastapi]"
+```
+
+---
+
+## Quickstart
+
+### 1. Synchronous Client
+
+```python
+from didit import Didit, SessionStatus
+
+# Initialize client (falls back to DIDIT_API_KEY environment variable if omitted)
+client = Didit(api_key="your_api_key", webhook_secret="your_webhook_secret")
+
+# Create a verification session
+session = client.sessions.create(
+    vendor_data="user_12345",
+    workflow_id="wf_kyc_standard",
+    callback="https://yourapp.com/kyc/complete",
+    language="es",
+)
+
+print(f"Verification URL: {session.url}")
+print(f"Session ID: {session.session_id}")
+
+# Fetch verification decision immediately:
+decision = client.sessions.get_decision(session.session_id)
+
+# Or poll until a terminal outcome (Approved or Declined) is reached:
+decision = client.sessions.poll_decision(session.session_id, timeout=60.0, interval=2.0)
+if decision.status == SessionStatus.APPROVED:
+    print(f"User approved! Document: {decision.document.document_number}")
+```
+
+### 2. Asynchronous Client (`asyncio`)
+
+```python
+import asyncio
+from didit import AsyncDidit, SessionStatus
+
+
+async def main():
+    async with AsyncDidit(api_key="your_api_key") as client:
+        session = await client.sessions.create(
+            vendor_data="user_987",
+            workflow_id="wf_kyc_standard",
+        )
+        print(f"Session URL: {session.url}")
+
+        decision = await client.sessions.get_decision(session.session_id)
+        if decision.status.is_terminal:
+            print(f"Final outcome: {decision.status}")
+
+
+asyncio.run(main())
+```
+
+---
+
+## Securing Webhooks with FastAPI
+
+Didit dispatches signed HTTP POST events upon verification completion. `didit-sdk` provides a dedicated FastAPI dependency to verify signatures in constant time and prevent replay attacks:
+
+```python
+from fastapi import FastAPI, Depends
+from didit import WebhookPayload, SessionStatus
+from didit.integrations.fastapi import DiditWebhookGuard
+
+app = FastAPI()
+
+# Guard reads secret from argument or DIDIT_WEBHOOK_SECRET env var
+webhook_guard = DiditWebhookGuard(secret="whsec_...")
+
+
+@app.post("/api/v1/webhooks/didit")
+async def handle_didit_event(
+    payload: WebhookPayload = Depends(webhook_guard),
+):
+    print(f"Received event for session: {payload.session_id}")
+
+    if payload.status == SessionStatus.APPROVED:
+        # Mark user verified in your database
+        ...
+    elif payload.status == SessionStatus.DECLINED:
+        # Handle rejection
+        ...
+
+    return {"received": True}
+```
+
+---
+
+## Testing & Offline Simulation
+
+Developing without live credentials or mock servers? Use the built-in simulator:
+
+```python
+from didit import SimulatedDidit, SessionStatus
+
+# Create in-memory client
+sim = SimulatedDidit(webhook_secret="test_secret")
+
+# 1. Create a simulated session
+session = sim.sessions.create(vendor_data="dev_user", workflow_id="wf_dev")
+assert session.session_id.startswith("sim_")
+
+# 2. Simulate user passing identity check
+sim.approve_session(session.session_id)
+
+decision = sim.sessions.get_decision(session.session_id)
+assert decision.status == SessionStatus.APPROVED
+
+# 3. Generate signed webhook payloads to test your local receiver
+raw_body, headers = sim.generate_webhook_event(session.session_id)
+# headers contain valid X-Signature-V2 and fresh X-Timestamp!
+```
+
+---
+
+## Exception Handling
+
+All client errors inherit from `DiditError`:
+
+```python
+from didit import Didit
+from didit.errors import (
+    DiditAuthenticationError,
+    DiditNotFoundError,
+    DiditRateLimitError,
+    DiditServerError,
+)
+
+client = Didit()
+
+try:
+    decision = client.sessions.get_decision("non_existent_session")
+except DiditNotFoundError:
+    print("Session not found")
+except DiditRateLimitError as exc:
+    print(f"Rate limited. Retry after {exc.retry_after} seconds.")
+except DiditAuthenticationError:
+    print("Invalid API key")
+except DiditServerError as exc:
+    print(f"Didit server error ({exc.status_code}): {exc.response_body}")
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `DIDIT_API_KEY` | *None* (Required) | Your Didit secret API key |
+| `DIDIT_BASE_URL` | `https://verification.didit.me/v3` | Didit API base URL |
+| `DIDIT_WEBHOOK_SECRET` | *None* | Shared webhook HMAC secret |
+| `DIDIT_TIMEOUT` | `30.0` | HTTP request timeout in seconds |
+| `DIDIT_MAX_RETRIES` | `2` | Maximum retry attempts for transient errors |
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/agustin18/didit-sdk.git
+cd didit-sdk
+
+# Install dependencies with uv
+uv sync --extra dev
+
+# Run unit tests with 100% coverage gate
+uv run pytest --cov=didit --cov-report=term-missing
+
+# Lint & Format check
+uv run ruff check .
+uv run ruff format --check .
+
+# Strict type check
+uv run mypy src/didit
+```
+
+---
+
+## License
+
+This project is licensed under the terms of the [MIT License](LICENSE).

didit_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,134 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "didit-sdk"
+version = "0.1.0"
+description = "Unofficial Python SDK for Didit (didit.me) Identity Verification & KYC"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Agustin Saiz", email = "agustinsaiz02@gmail.com" }
+]
+keywords = [
+    "didit",
+    "kyc",
+    "identity-verification",
+    "biometrics",
+    "fastapi",
+    "sdk",
+    "webhooks"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security :: Cryptography",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.100.0",
+]
+all = [
+    "fastapi>=0.100.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0.0",
+    "respx>=0.21.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "fastapi>=0.100.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/agustin18/didit-sdk"
+Documentation = "https://github.com/agustin18/didit-sdk#readme"
+Repository = "https://github.com/agustin18/didit-sdk"
+Issues = "https://github.com/agustin18/didit-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/didit"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+exclude = [
+    ".roadmap.md",
+    ".audit",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --strict-markers"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+source = ["src/didit"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+]
+ignore = []
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["fastapi.Depends", "fastapi.params.Depends"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+show_error_codes = true