a3api 0.1.0__tar.gz

a3api-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Serverless
+.serverless/
+
+# IDE
+.idea/
+.vscode/
+
+# Claude local settings (may contain credentials)
+.claude/settings.local.json
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# TypeScript incremental
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Next.js
+.next/
+out/
+
+# AWS Amplify
+amplify-builds/
+
+# Benchmark generated datasets
+**/benchmarks/benchmark_dataset_*.json
+**/benchmarks/benchmark_results_*.json
+
+# Lambda packaging artifacts
+**/benchmarks/package/
+function.zip
+
+# Terraform
+**/.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfplan
+**/placeholder.zip
+secrets.auto.tfvars

a3api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A3 API Team
+
+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.

a3api-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: a3api
+Version: 0.1.0
+Summary: Official Python client for the A3 Age Assurance API
+Project-URL: Homepage, https://www.a3api.io
+Project-URL: Documentation, https://www.a3api.io/docs
+Project-URL: Repository, https://github.com/a3api/a3api-python
+Author: A3 API Team
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a3,ab-1043,age-assurance,age-verification,coppa
+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.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# a3api
+
+Official Python client for the [A3 Age Assurance API](https://www.a3api.io).
+
+Typed, async-ready, with built-in retries — supports Python 3.9+.
+
+## Installation
+
+```bash
+pip install a3api
+```
+
+## Quick Start
+
+```python
+from a3api import A3Client, AssessAgeRequest, OsSignal
+
+client = A3Client(api_key="your-api-key")
+
+response = client.assess_age(AssessAgeRequest(
+    os_signal=OsSignal.AGE_18_PLUS,
+    user_country_code="US",
+))
+
+print(response.verdict)           # CONSISTENT
+print(response.confidence_score)  # 0.95
+print(response.verification_token)
+```
+
+### Async
+
+```python
+from a3api import AsyncA3Client, AssessAgeRequest, OsSignal
+
+async with AsyncA3Client(api_key="your-api-key") as client:
+    response = await client.assess_age(AssessAgeRequest(
+        os_signal=OsSignal.AGE_18_PLUS,
+        user_country_code="US",
+    ))
+```
+
+### With Behavioral Signals
+
+```python
+from a3api import (
+    A3Client, AssessAgeRequest, OsSignal,
+    BehavioralMetrics, DeviceContext,
+)
+
+client = A3Client(api_key="your-api-key")
+
+response = client.assess_age(AssessAgeRequest(
+    os_signal=OsSignal.AGE_13_15,
+    user_country_code="US",
+    behavioral_metrics=BehavioralMetrics(
+        avg_touch_precision=0.82,
+        scroll_velocity=340.0,
+        form_completion_time_ms=12000.0,
+    ),
+    device_context=DeviceContext(
+        os_version="iOS 17.2",
+        device_model="iPhone 15",
+        is_high_contrast_enabled=False,
+        screen_scale_factor=3.0,
+    ),
+))
+```
+
+## Error Handling
+
+```python
+from a3api import (
+    A3Client, A3AuthenticationError,
+    A3RateLimitError, A3ValidationError, A3ConnectionError,
+)
+
+try:
+    response = client.assess_age(request)
+except A3AuthenticationError:
+    # Invalid or missing API key (401)
+    pass
+except A3RateLimitError as e:
+    # Too many requests (429) — e.retry_after has the wait time
+    pass
+except A3ValidationError as e:
+    # Bad request (400) — e.validation_errors has details
+    pass
+except A3ConnectionError:
+    # Network or timeout error
+    pass
+```
+
+## Configuration
+
+```python
+client = A3Client(
+    api_key="your-api-key",
+    base_url="https://api.a3api.io",  # default
+    timeout=30.0,                      # seconds, default
+    max_retries=2,                     # default
+)
+```
+
+## License
+
+MIT

a3api-0.1.0/README.md

@@ -0,0 +1,106 @@
+# a3api
+
+Official Python client for the [A3 Age Assurance API](https://www.a3api.io).
+
+Typed, async-ready, with built-in retries — supports Python 3.9+.
+
+## Installation
+
+```bash
+pip install a3api
+```
+
+## Quick Start
+
+```python
+from a3api import A3Client, AssessAgeRequest, OsSignal
+
+client = A3Client(api_key="your-api-key")
+
+response = client.assess_age(AssessAgeRequest(
+    os_signal=OsSignal.AGE_18_PLUS,
+    user_country_code="US",
+))
+
+print(response.verdict)           # CONSISTENT
+print(response.confidence_score)  # 0.95
+print(response.verification_token)
+```
+
+### Async
+
+```python
+from a3api import AsyncA3Client, AssessAgeRequest, OsSignal
+
+async with AsyncA3Client(api_key="your-api-key") as client:
+    response = await client.assess_age(AssessAgeRequest(
+        os_signal=OsSignal.AGE_18_PLUS,
+        user_country_code="US",
+    ))
+```
+
+### With Behavioral Signals
+
+```python
+from a3api import (
+    A3Client, AssessAgeRequest, OsSignal,
+    BehavioralMetrics, DeviceContext,
+)
+
+client = A3Client(api_key="your-api-key")
+
+response = client.assess_age(AssessAgeRequest(
+    os_signal=OsSignal.AGE_13_15,
+    user_country_code="US",
+    behavioral_metrics=BehavioralMetrics(
+        avg_touch_precision=0.82,
+        scroll_velocity=340.0,
+        form_completion_time_ms=12000.0,
+    ),
+    device_context=DeviceContext(
+        os_version="iOS 17.2",
+        device_model="iPhone 15",
+        is_high_contrast_enabled=False,
+        screen_scale_factor=3.0,
+    ),
+))
+```
+
+## Error Handling
+
+```python
+from a3api import (
+    A3Client, A3AuthenticationError,
+    A3RateLimitError, A3ValidationError, A3ConnectionError,
+)
+
+try:
+    response = client.assess_age(request)
+except A3AuthenticationError:
+    # Invalid or missing API key (401)
+    pass
+except A3RateLimitError as e:
+    # Too many requests (429) — e.retry_after has the wait time
+    pass
+except A3ValidationError as e:
+    # Bad request (400) — e.validation_errors has details
+    pass
+except A3ConnectionError:
+    # Network or timeout error
+    pass
+```
+
+## Configuration
+
+```python
+client = A3Client(
+    api_key="your-api-key",
+    base_url="https://api.a3api.io",  # default
+    timeout=30.0,                      # seconds, default
+    max_retries=2,                     # default
+)
+```
+
+## License
+
+MIT

a3api-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "a3api"
+version = "0.1.0"
+description = "Official Python client for the A3 Age Assurance API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "A3 API Team" }]
+keywords = ["a3", "age-assurance", "age-verification", "ab-1043", "coppa"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.24,<1",
+  "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://www.a3api.io"
+Documentation = "https://www.a3api.io/docs"
+Repository = "https://github.com/a3api/a3api-python"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+  "pytest-asyncio>=0.21",
+  "pytest-httpx>=0.30",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/a3api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

a3api-0.1.0/src/a3api/__init__.py

@@ -0,0 +1,61 @@
+"""A3 Age Assurance API — official Python client."""
+
+from ._client import A3Client, AsyncA3Client
+from ._errors import (
+    A3ApiError,
+    A3AuthenticationError,
+    A3ConnectionError,
+    A3RateLimitError,
+    A3ValidationError,
+)
+from ._types import (
+    AccountLongevity,
+    AgeBracket,
+    AssessAgeRequest,
+    AssessAgeResponse,
+    BehavioralMetrics,
+    ConsentSource,
+    ContextualSignals,
+    DeviceContext,
+    FaceEstimationProvider,
+    FaceEstimationResult,
+    InputComplexity,
+    IpType,
+    OsSignal,
+    ParentalConsentStatus,
+    ReferrerCategory,
+    Verdict,
+)
+from ._version import __version__
+
+__all__ = [
+    # Clients
+    "A3Client",
+    "AsyncA3Client",
+    # Errors
+    "A3ApiError",
+    "A3AuthenticationError",
+    "A3ConnectionError",
+    "A3RateLimitError",
+    "A3ValidationError",
+    # Request types
+    "AssessAgeRequest",
+    "OsSignal",
+    "ParentalConsentStatus",
+    "ConsentSource",
+    "FaceEstimationProvider",
+    "IpType",
+    "ReferrerCategory",
+    "BehavioralMetrics",
+    "DeviceContext",
+    "ContextualSignals",
+    "AccountLongevity",
+    "InputComplexity",
+    "FaceEstimationResult",
+    # Response types
+    "AssessAgeResponse",
+    "Verdict",
+    "AgeBracket",
+    # Version
+    "__version__",
+]

a3api-0.1.0/src/a3api/_client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._errors import (
+    A3ApiError,
+    A3AuthenticationError,
+    A3ConnectionError,
+    A3RateLimitError,
+    A3ValidationError,
+)
+from ._retry import (
+    RetryConfig,
+    is_retryable_status,
+    parse_retry_after,
+    with_retry_async,
+    with_retry_sync,
+)
+from ._types import AssessAgeRequest, AssessAgeResponse
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.a3api.io"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+def _build_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Content-Type": "application/json",
+        "x-api-key": api_key,
+        "User-Agent": f"a3api-python/{__version__}",
+    }
+
+
+def _handle_error(response: httpx.Response) -> None:
+    body: dict[str, Any] | None = None
+    try:
+        body = response.json()
+    except Exception:
+        pass
+
+    status = response.status_code
+    if status == 400:
+        raise A3ValidationError(body)
+    if status == 401:
+        raise A3AuthenticationError(body)
+    if status == 429:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        raise A3RateLimitError(retry_after, body)
+    raise A3ApiError(
+        body.get("error", f"HTTP {status}") if body else f"HTTP {status}",
+        status,
+        body,
+    )
+
+
+def _should_retry(exc: Exception) -> tuple[bool, float | None]:
+    if isinstance(exc, A3RateLimitError):
+        return True, exc.retry_after
+    if isinstance(exc, A3ApiError) and is_retryable_status(exc.status_code):
+        return True, None
+    if isinstance(exc, A3ConnectionError):
+        return True, None
+    return False, None
+
+
+class A3Client:
+    """Synchronous A3 API client using httpx."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._retry_config = RetryConfig(max_retries=max_retries)
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> A3Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def assess_age(self, request: AssessAgeRequest) -> AssessAgeResponse:
+        """Assess age and return a parsed response model."""
+        raw = self.assess_age_raw(request)
+        return AssessAgeResponse.model_validate(raw)
+
+    def assess_age_raw(self, request: AssessAgeRequest) -> dict[str, Any]:
+        """Assess age and return the raw JSON dict."""
+        return with_retry_sync(
+            lambda: self._do_assess_age(request),
+            self._retry_config,
+            _should_retry,
+        )
+
+    def _do_assess_age(self, request: AssessAgeRequest) -> dict[str, Any]:
+        try:
+            response = self._client.post(
+                "/v1/assurance/assess-age",
+                json=request.model_dump(exclude_none=True),
+            )
+        except httpx.TimeoutException as exc:
+            raise A3ConnectionError(f"Request timed out: {exc}", exc) from exc
+        except httpx.NetworkError as exc:
+            raise A3ConnectionError(f"Network error: {exc}", exc) from exc
+        except httpx.ProtocolError as exc:
+            raise A3ConnectionError(f"Protocol error: {exc}", exc) from exc
+
+        if response.is_success:
+            return response.json()  # type: ignore[no-any-return]
+        _handle_error(response)
+        raise AssertionError("unreachable")  # pragma: no cover
+
+
+class AsyncA3Client:
+    """Asynchronous A3 API client using httpx."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._retry_config = RetryConfig(max_retries=max_retries)
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> AsyncA3Client:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def assess_age(self, request: AssessAgeRequest) -> AssessAgeResponse:
+        """Assess age and return a parsed response model."""
+        raw = await self.assess_age_raw(request)
+        return AssessAgeResponse.model_validate(raw)
+
+    async def assess_age_raw(self, request: AssessAgeRequest) -> dict[str, Any]:
+        """Assess age and return the raw JSON dict."""
+        return await with_retry_async(
+            lambda: self._do_assess_age(request),
+            self._retry_config,
+            _should_retry,
+        )
+
+    async def _do_assess_age(self, request: AssessAgeRequest) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                "/v1/assurance/assess-age",
+                json=request.model_dump(exclude_none=True),
+            )
+        except httpx.TimeoutException as exc:
+            raise A3ConnectionError(f"Request timed out: {exc}", exc) from exc
+        except httpx.NetworkError as exc:
+            raise A3ConnectionError(f"Network error: {exc}", exc) from exc
+        except httpx.ProtocolError as exc:
+            raise A3ConnectionError(f"Protocol error: {exc}", exc) from exc
+
+        if response.is_success:
+            return response.json()  # type: ignore[no-any-return]
+        _handle_error(response)
+        raise AssertionError("unreachable")  # pragma: no cover

a3api-0.1.0/src/a3api/_errors.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+
+class A3ApiError(Exception):
+    """Base error for all A3 API errors with an HTTP status code."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class A3AuthenticationError(A3ApiError):
+    """Raised on 401 Unauthorized responses."""
+
+    def __init__(self, body: Optional[dict[str, Any]] = None) -> None:
+        raw = body.get("message", "Unauthorized") if body else "Unauthorized"
+        msg = ", ".join(raw) if isinstance(raw, list) else str(raw)
+        super().__init__(msg, 401, body)
+
+
+class A3RateLimitError(A3ApiError):
+    """Raised on 429 Too Many Requests responses."""
+
+    def __init__(
+        self,
+        retry_after: Optional[float] = None,
+        body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__("Rate limit exceeded", 429, body)
+        self.retry_after = retry_after
+
+
+class A3ValidationError(A3ApiError):
+    """Raised on 400 Bad Request responses with validation details."""
+
+    def __init__(self, body: Optional[dict[str, Any]] = None) -> None:
+        raw: Union[str, list[str]] = (body or {}).get("message", [])
+        self.validation_errors: list[str] = (
+            raw if isinstance(raw, list) else [raw] if raw else []
+        )
+        msg = (
+            f"Validation failed: {', '.join(self.validation_errors)}"
+            if self.validation_errors
+            else "Validation failed"
+        )
+        super().__init__(msg, 400, body)
+
+
+class A3ConnectionError(Exception):
+    """Raised on network or timeout errors (no HTTP status code)."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause