vercre-sdk 1.0.0__tar.gz

vercre_sdk-1.0.0/.gitignore

@@ -0,0 +1,43 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.pem
+*.key
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+node_modules/
+artifacts/
+cache/
+nohup.out
+
+# sops / age secrets
+keys.txt
+secrets.json
+
+# Generated key files (contain private keys — never commit)
+issuer.json
+subject.json
+
+# Issued credential files (contain signed JWTs — never commit)
+credential.json
+kyc.json
+aml.json
+
+# Frontend
+# frontend/
+.vercel
+
+# Database hardening
+certs/
+backups/

vercre_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: vercre-sdk
+Version: 1.0.0
+Summary: Python SDK for the VERCRE Verifiable Credentials API
+Project-URL: Homepage, https://vercre.vectorguardlabs.com
+Project-URL: Documentation, https://vercre.vectorguardlabs.com/docs/sdk
+Project-URL: Repository, https://github.com/pavondunbar/Verified-Credentials-SDK
+Project-URL: Issues, https://github.com/pavondunbar/Verified-Credentials-SDK/issues
+Author: Pavon Dunbar
+License-Expression: MIT
+Keywords: api-client,did,sdk,vercre,verifiable-credentials,w3c
+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<1.0,>=0.25.0
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: async
+Requires-Dist: anyio>=4.0; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vercre-sdk
+
+Python SDK for the [VERCRE](https://vercre.vectorguardlabs.com) Verifiable Credentials API.
+
+## Installation
+
+```bash
+pip install vercre-sdk
+```
+
+## Quick Start
+
+```python
+from vercre_sdk import VercreClient
+
+client = VercreClient(
+    api_key="vercre_admin_your_key_here",
+    base_url="https://api.vercre.io",
+)
+
+# Issue a credential
+credential = client.issue_credential(
+    issuer_did="did:key:z6Mk...",
+    subject_did="did:key:z6Mp...",
+    credential_type="KYCBasic",
+    claims={"name": "Alice Johnson", "country": "US"},
+)
+print(f"Issued: {credential.credential_id}")
+
+# Verify a credential
+result = client.verify_credential(credential=credential.credential)
+print(f"Valid: {result.valid}, Decision: {result.compliance_decision}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from vercre_sdk import AsyncVercreClient
+
+async def main():
+    async with AsyncVercreClient(api_key="vercre_admin_xxx") as client:
+        result = await client.verify_credential(credential=my_credential)
+        print(result.compliance_decision)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from vercre_sdk import VercreClient, RateLimitError, AuthenticationError
+
+client = VercreClient(api_key="...")
+
+try:
+    result = client.verify_credential(credential=cred)
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Available Methods
+
+### Credentials
+- `issue_credential()` - Issue a new verifiable credential
+- `verify_credential()` - Verify a credential with compliance scoring
+- `revoke_credential()` - Revoke a credential
+- `get_credential_status()` - Check on-chain attestation status
+- `get_credential()` - Look up credential by ID
+- `list_credentials()` - List credentials by subject DID
+
+### Verification
+- `verify_presentation()` - Verify a W3C Verifiable Presentation
+
+### Issuers
+- `get_issuer()` - Get issuer details
+- `list_issuers()` - List registered issuers
+- `check_issuer_can_issue()` - Check credential type authorization
+
+### Disputes
+- `file_dispute()` - File a dispute against a credential
+- `get_dispute()` - Get dispute details
+- `list_disputes()` - List disputes
+
+### Reputation
+- `get_reputation()` - Get issuer reputation score
+- `submit_feedback()` - Submit verifier feedback
+
+### Webhooks
+- `register_webhook()` - Register a webhook endpoint
+- `list_webhooks()` - List registered webhooks
+- `delete_webhook()` - Remove a webhook
+
+### Billing
+- `get_subscription()` - Get current plan
+- `get_usage()` - Get usage and remaining quota
+- `subscribe()` - Change billing plan
+- `get_billing_portal_url()` - Self-service billing management
+
+### Keys
+- `rotate_key()` - Rotate signing key for a DID
+- `list_key_versions()` - List key version history
+
+## License
+
+MIT

vercre_sdk-1.0.0/README.md

@@ -0,0 +1,108 @@
+# vercre-sdk
+
+Python SDK for the [VERCRE](https://vercre.vectorguardlabs.com) Verifiable Credentials API.
+
+## Installation
+
+```bash
+pip install vercre-sdk
+```
+
+## Quick Start
+
+```python
+from vercre_sdk import VercreClient
+
+client = VercreClient(
+    api_key="vercre_admin_your_key_here",
+    base_url="https://api.vercre.io",
+)
+
+# Issue a credential
+credential = client.issue_credential(
+    issuer_did="did:key:z6Mk...",
+    subject_did="did:key:z6Mp...",
+    credential_type="KYCBasic",
+    claims={"name": "Alice Johnson", "country": "US"},
+)
+print(f"Issued: {credential.credential_id}")
+
+# Verify a credential
+result = client.verify_credential(credential=credential.credential)
+print(f"Valid: {result.valid}, Decision: {result.compliance_decision}")
+```
+
+## Async Usage
+
+```python
+import asyncio
+from vercre_sdk import AsyncVercreClient
+
+async def main():
+    async with AsyncVercreClient(api_key="vercre_admin_xxx") as client:
+        result = await client.verify_credential(credential=my_credential)
+        print(result.compliance_decision)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from vercre_sdk import VercreClient, RateLimitError, AuthenticationError
+
+client = VercreClient(api_key="...")
+
+try:
+    result = client.verify_credential(credential=cred)
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except AuthenticationError:
+    print("Invalid API key")
+```
+
+## Available Methods
+
+### Credentials
+- `issue_credential()` - Issue a new verifiable credential
+- `verify_credential()` - Verify a credential with compliance scoring
+- `revoke_credential()` - Revoke a credential
+- `get_credential_status()` - Check on-chain attestation status
+- `get_credential()` - Look up credential by ID
+- `list_credentials()` - List credentials by subject DID
+
+### Verification
+- `verify_presentation()` - Verify a W3C Verifiable Presentation
+
+### Issuers
+- `get_issuer()` - Get issuer details
+- `list_issuers()` - List registered issuers
+- `check_issuer_can_issue()` - Check credential type authorization
+
+### Disputes
+- `file_dispute()` - File a dispute against a credential
+- `get_dispute()` - Get dispute details
+- `list_disputes()` - List disputes
+
+### Reputation
+- `get_reputation()` - Get issuer reputation score
+- `submit_feedback()` - Submit verifier feedback
+
+### Webhooks
+- `register_webhook()` - Register a webhook endpoint
+- `list_webhooks()` - List registered webhooks
+- `delete_webhook()` - Remove a webhook
+
+### Billing
+- `get_subscription()` - Get current plan
+- `get_usage()` - Get usage and remaining quota
+- `subscribe()` - Change billing plan
+- `get_billing_portal_url()` - Self-service billing management
+
+### Keys
+- `rotate_key()` - Rotate signing key for a DID
+- `list_key_versions()` - List key version history
+
+## License
+
+MIT

vercre_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "vercre-sdk"
+version = "1.0.0"
+description = "Python SDK for the VERCRE Verifiable Credentials API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Pavon Dunbar" },
+]
+keywords = [
+    "verifiable-credentials",
+    "w3c",
+    "did",
+    "sdk",
+    "api-client",
+    "vercre",
+]
+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 :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0,<1.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+async = ["anyio>=4.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://vercre.vectorguardlabs.com"
+Documentation = "https://vercre.vectorguardlabs.com/docs/sdk"
+Repository = "https://github.com/pavondunbar/Verified-Credentials-SDK"
+Issues = "https://github.com/pavondunbar/Verified-Credentials-SDK/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vercre_sdk"]

vercre_sdk-1.0.0/src/vercre_sdk/__init__.py

@@ -0,0 +1,36 @@
+"""VERCRE SDK — Python client for the VERCRE Verifiable Credentials API."""
+
+from vercre_sdk.async_client import AsyncVercreClient
+from vercre_sdk.client import VercreClient
+from vercre_sdk.exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    VercreError,
+)
+from vercre_sdk.models import (
+    Credential,
+    Issuer,
+    Subscription,
+    UsageInfo,
+    VerificationResult,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "VercreClient",
+    "AsyncVercreClient",
+    "VercreError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "Credential",
+    "VerificationResult",
+    "Issuer",
+    "Subscription",
+    "UsageInfo",
+]

vercre_sdk-1.0.0/src/vercre_sdk/_transport.py

@@ -0,0 +1,82 @@
+"""HTTP transport layer with error handling and retry logic."""
+
+import httpx
+
+from vercre_sdk.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    VercreError,
+)
+
+_DEFAULT_TIMEOUT = 30.0
+_MAX_RETRIES = 3
+_RETRY_BACKOFF = 1.0
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise appropriate SDK exception for error HTTP responses."""
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+        detail = body.get("detail", response.text)
+    except Exception:
+        detail = response.text
+
+    status = response.status_code
+    msg = f"VERCRE API error ({status}): {detail}"
+
+    if status == 401:
+        raise AuthenticationError(msg, status_code=status, detail=detail)
+    if status == 403:
+        raise ForbiddenError(msg, status_code=status, detail=detail)
+    if status == 404:
+        raise NotFoundError(msg, status_code=status, detail=detail)
+    if status == 409:
+        raise ConflictError(msg, status_code=status, detail=detail)
+    if status in (400, 422):
+        raise ValidationError(msg, status_code=status, detail=detail)
+    if status == 429:
+        retry_after = response.headers.get("Retry-After")
+        raise RateLimitError(
+            msg,
+            status_code=status,
+            detail=detail,
+            retry_after=int(retry_after) if retry_after else None,
+        )
+    if status >= 500:
+        raise ServerError(msg, status_code=status, detail=detail)
+    raise VercreError(msg, status_code=status, detail=detail)
+
+
+
+def build_headers(api_key: str) -> dict[str, str]:
+    """Build default request headers."""
+    return {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "User-Agent": "vercre-sdk-python/1.0.0",
+    }
+
+
+def should_retry(status_code: int, attempt: int) -> bool:
+    """Determine if a request should be retried."""
+    if attempt >= _MAX_RETRIES:
+        return False
+    return status_code in (429, 502, 503, 504)
+
+
+def retry_delay(attempt: int, retry_after: str | None = None) -> float:
+    """Calculate delay before next retry (exponential backoff)."""
+    if retry_after:
+        try:
+            return float(retry_after)
+        except ValueError:
+            pass
+    return _RETRY_BACKOFF * (2 ** attempt)

vercre_sdk-1.0.0/src/vercre_sdk/async_client.py

@@ -0,0 +1,274 @@
+"""Asynchronous VERCRE API client."""
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from vercre_sdk._transport import (
+    _DEFAULT_TIMEOUT,
+    _raise_for_status,
+    build_headers,
+    retry_delay,
+    should_retry,
+)
+from vercre_sdk.models import (
+    Credential,
+    CredentialStatus,
+    DisputeResult,
+    Issuer,
+    Subscription,
+    UsageInfo,
+    VerificationResult,
+    WebhookResult,
+)
+
+
+class AsyncVercreClient:
+    """Async client for the VERCRE Verifiable Credentials API.
+
+    Usage:
+        async with AsyncVercreClient(api_key="vercre_admin_xxx") as client:
+            cred = await client.issue_credential(
+                issuer_did="did:key:z6Mk...",
+                subject_did="did:key:z6Mp...",
+                credential_type="KYCBasic",
+                claims={"name": "Alice"},
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.vercre.io",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=build_headers(api_key),
+            timeout=timeout,
+        )
+
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
+        """Make an HTTP request with retry logic."""
+        url = f"/api/v1{path}"
+        response = None
+        for attempt in range(4):
+            response = await self._client.request(method, url, **kwargs)
+            if should_retry(response.status_code, attempt):
+                delay = retry_delay(attempt, response.headers.get("Retry-After"))
+                await asyncio.sleep(delay)
+                continue
+            _raise_for_status(response)
+            if response.status_code == 204:
+                return {}
+            return response.json()
+        _raise_for_status(response)
+        return response.json()
+
+    # --- Health ---
+
+    async def health(self) -> dict:
+        """Check API health."""
+        return await self._request("GET", "/health")
+
+    # --- Credentials ---
+
+    async def issue_credential(
+        self,
+        issuer_did: str,
+        subject_did: str,
+        credential_type: str,
+        claims: dict,
+        expiration: str | None = None,
+    ) -> Credential:
+        """Issue a new verifiable credential."""
+        payload: dict[str, Any] = {
+            "issuerDid": issuer_did,
+            "subjectDid": subject_did,
+            "credentialType": credential_type,
+            "claims": claims,
+        }
+        if expiration:
+            payload["expiration"] = expiration
+        data = await self._request("POST", "/issue", json=payload)
+        return Credential.model_validate(data)
+
+
+    async def verify_credential(
+        self,
+        credential: dict | None = None,
+        credential_id: str | None = None,
+        policy: dict | None = None,
+    ) -> VerificationResult:
+        """Verify a credential and get a compliance decision."""
+        payload: dict[str, Any] = {}
+        if credential:
+            payload["credential"] = credential
+        if credential_id:
+            payload["credentialId"] = credential_id
+        if policy:
+            payload["policy"] = policy
+        data = await self._request("POST", "/verify", json=payload)
+        return VerificationResult.model_validate(data)
+
+    async def revoke_credential(self, credential: dict, issuer_did: str) -> dict:
+        """Revoke a previously issued credential."""
+        return await self._request(
+            "POST", "/credentials/revoke",
+            json={"credential": credential, "issuerDid": issuer_did},
+        )
+
+    async def get_credential_status(self, credential_hash: str) -> CredentialStatus:
+        """Get on-chain attestation status."""
+        data = await self._request("GET", f"/credentials/{credential_hash}/status")
+        return CredentialStatus.model_validate(data)
+
+    async def get_credential(self, credential_id: str) -> dict:
+        """Look up a credential by ID."""
+        return await self._request("GET", f"/credentials/{credential_id}/detail")
+
+    async def list_credentials(self, subject_did: str) -> dict:
+        """List all credentials for a subject DID."""
+        return await self._request("GET", f"/subjects/{subject_did}/credentials")
+
+    # --- Verification ---
+
+    async def verify_presentation(
+        self, presentation: dict, check_chain: bool = True
+    ) -> dict:
+        """Verify a W3C Verifiable Presentation."""
+        return await self._request(
+            "POST", "/verify-presentation",
+            json={"presentation": presentation, "checkChain": check_chain},
+        )
+
+
+    # --- Issuers ---
+
+    async def get_issuer(self, did: str) -> Issuer:
+        """Get issuer details."""
+        data = await self._request("GET", f"/issuers/{did}")
+        return Issuer.model_validate(data)
+
+    async def list_issuers(self, tier: str | None = None) -> list[dict]:
+        """List registered issuers."""
+        params = {"tier": tier} if tier else {}
+        data = await self._request("GET", "/issuers", params=params)
+        return data if isinstance(data, list) else data.get("issuers", [])
+
+    async def check_issuer_can_issue(self, did: str, credential_type: str) -> dict:
+        """Check if an issuer can issue a credential type."""
+        return await self._request(
+            "GET", f"/issuers/{did}/can-issue", params={"type": credential_type}
+        )
+
+    # --- Disputes ---
+
+    async def file_dispute(
+        self,
+        credential_id: str,
+        reporter_did: str,
+        issuer_did: str,
+        reason: str,
+    ) -> DisputeResult:
+        """File a dispute against a credential."""
+        data = await self._request(
+            "POST", "/disputes",
+            json={
+                "credentialId": credential_id,
+                "reporterDid": reporter_did,
+                "issuerDid": issuer_did,
+                "reason": reason,
+            },
+        )
+        return DisputeResult.model_validate(data)
+
+    async def get_dispute(self, dispute_id: str) -> dict:
+        """Get dispute details."""
+        return await self._request("GET", f"/disputes/{dispute_id}")
+
+    async def list_disputes(self, issuer_did: str | None = None) -> list[dict]:
+        """List disputes."""
+        params = {"issuer": issuer_did} if issuer_did else {}
+        data = await self._request("GET", "/disputes", params=params)
+        return data if isinstance(data, list) else data.get("disputes", [])
+
+    # --- Reputation ---
+
+    async def get_reputation(self, did: str) -> dict:
+        """Get an issuer's reputation score."""
+        return await self._request("GET", f"/reputation/{did}")
+
+    async def submit_feedback(self, did: str, positive: bool, detail: str = "") -> dict:
+        """Submit verifier feedback on an issuer."""
+        return await self._request(
+            "POST", f"/reputation/{did}/feedback",
+            json={"positive": positive, "detail": detail},
+        )
+
+
+    # --- Webhooks ---
+
+    async def register_webhook(self, url: str, events: list[str]) -> WebhookResult:
+        """Register a webhook endpoint."""
+        data = await self._request(
+            "POST", "/webhooks", json={"url": url, "events": events}
+        )
+        return WebhookResult.model_validate(data)
+
+    async def list_webhooks(self) -> list[dict]:
+        """List registered webhooks."""
+        data = await self._request("GET", "/webhooks")
+        return data if isinstance(data, list) else data.get("webhooks", [])
+
+    async def delete_webhook(self, webhook_id: str) -> dict:
+        """Delete a webhook subscription."""
+        return await self._request("DELETE", f"/webhooks/{webhook_id}")
+
+    # --- Billing ---
+
+    async def get_subscription(self) -> Subscription:
+        """Get current billing subscription."""
+        data = await self._request("GET", "/billing/subscription")
+        return Subscription.model_validate(data)
+
+    async def get_usage(self) -> UsageInfo:
+        """Get current period usage and quotas."""
+        data = await self._request("GET", "/billing/usage")
+        return UsageInfo.model_validate(data)
+
+    async def subscribe(self, plan: str) -> dict:
+        """Create or change a billing subscription."""
+        return await self._request("POST", "/billing/subscribe", json={"plan": plan})
+
+    async def get_billing_portal_url(self, return_url: str = "") -> str:
+        """Get a Stripe billing portal URL."""
+        payload = {"returnUrl": return_url} if return_url else {}
+        data = await self._request("POST", "/billing/portal", json=payload)
+        return data.get("url", "")
+
+    # --- Keys ---
+
+    async def rotate_key(self, did: str) -> dict:
+        """Rotate the signing key for a DID."""
+        return await self._request("POST", f"/keys/{did}/rotate")
+
+    async def list_key_versions(self, did: str) -> list[dict]:
+        """List all key versions for a DID."""
+        data = await self._request("GET", f"/keys/{did}/versions")
+        return data if isinstance(data, list) else []

vercre_sdk-1.0.0/src/vercre_sdk/client.py

@@ -0,0 +1,275 @@
+"""Synchronous VERCRE API client."""
+
+import time
+from typing import Any
+
+import httpx
+
+from vercre_sdk._transport import (
+    _DEFAULT_TIMEOUT,
+    _raise_for_status,
+    build_headers,
+    retry_delay,
+    should_retry,
+)
+from vercre_sdk.models import (
+    Credential,
+    CredentialStatus,
+    DisputeResult,
+    Issuer,
+    Subscription,
+    UsageInfo,
+    VerificationResult,
+    WebhookResult,
+)
+
+
+class VercreClient:
+    """Synchronous client for the VERCRE Verifiable Credentials API.
+
+    Usage:
+        client = VercreClient(api_key="vercre_admin_xxx", base_url="https://api.vercre.io")
+        cred = client.issue_credential(
+            issuer_did="did:key:z6Mk...",
+            subject_did="did:key:z6Mp...",
+            credential_type="KYCBasic",
+            claims={"name": "Alice", "country": "US"},
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.vercre.io",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=build_headers(api_key),
+            timeout=timeout,
+        )
+
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs) -> dict[str, Any]:
+        """Make an HTTP request with retry logic."""
+        url = f"/api/v1{path}"
+        for attempt in range(4):
+            response = self._client.request(method, url, **kwargs)
+            if should_retry(response.status_code, attempt):
+                delay = retry_delay(attempt, response.headers.get("Retry-After"))
+                time.sleep(delay)
+                continue
+            _raise_for_status(response)
+            if response.status_code == 204:
+                return {}
+            return response.json()
+        _raise_for_status(response)
+        return response.json()
+
+    # --- Health ---
+
+    def health(self) -> dict:
+        """Check API health."""
+        return self._request("GET", "/health")
+
+    # --- Credentials ---
+
+    def issue_credential(
+        self,
+        issuer_did: str,
+        subject_did: str,
+        credential_type: str,
+        claims: dict,
+        expiration: str | None = None,
+    ) -> Credential:
+        """Issue a new verifiable credential."""
+        payload: dict[str, Any] = {
+            "issuerDid": issuer_did,
+            "subjectDid": subject_did,
+            "credentialType": credential_type,
+            "claims": claims,
+        }
+        if expiration:
+            payload["expiration"] = expiration
+        data = self._request("POST", "/issue", json=payload)
+        return Credential.model_validate(data)
+
+
+    def verify_credential(
+        self,
+        credential: dict | None = None,
+        credential_id: str | None = None,
+        policy: dict | None = None,
+    ) -> VerificationResult:
+        """Verify a credential and get a compliance decision."""
+        payload: dict[str, Any] = {}
+        if credential:
+            payload["credential"] = credential
+        if credential_id:
+            payload["credentialId"] = credential_id
+        if policy:
+            payload["policy"] = policy
+        data = self._request("POST", "/verify", json=payload)
+        return VerificationResult.model_validate(data)
+
+    def revoke_credential(self, credential: dict, issuer_did: str) -> dict:
+        """Revoke a previously issued credential."""
+        return self._request(
+            "POST", "/credentials/revoke",
+            json={"credential": credential, "issuerDid": issuer_did},
+        )
+
+    def get_credential_status(self, credential_hash: str) -> CredentialStatus:
+        """Get on-chain attestation status for a credential."""
+        data = self._request("GET", f"/credentials/{credential_hash}/status")
+        return CredentialStatus.model_validate(data)
+
+    def get_credential(self, credential_id: str) -> dict:
+        """Look up a credential by ID."""
+        return self._request("GET", f"/credentials/{credential_id}/detail")
+
+    def list_credentials(self, subject_did: str) -> dict:
+        """List all credentials for a subject DID."""
+        return self._request("GET", f"/subjects/{subject_did}/credentials")
+
+    # --- Verification ---
+
+    def verify_presentation(
+        self, presentation: dict, check_chain: bool = True
+    ) -> dict:
+        """Verify a W3C Verifiable Presentation."""
+        return self._request(
+            "POST", "/verify-presentation",
+            json={"presentation": presentation, "checkChain": check_chain},
+        )
+
+
+    # --- Issuers ---
+
+    def get_issuer(self, did: str) -> Issuer:
+        """Get issuer details."""
+        data = self._request("GET", f"/issuers/{did}")
+        return Issuer.model_validate(data)
+
+    def list_issuers(self, tier: str | None = None) -> list[dict]:
+        """List registered issuers."""
+        params = {"tier": tier} if tier else {}
+        data = self._request("GET", "/issuers", params=params)
+        return data if isinstance(data, list) else data.get("issuers", [])
+
+    def check_issuer_can_issue(self, did: str, credential_type: str) -> dict:
+        """Check if an issuer is authorized to issue a credential type."""
+        return self._request(
+            "GET", f"/issuers/{did}/can-issue",
+            params={"type": credential_type},
+        )
+
+    # --- Disputes ---
+
+    def file_dispute(
+        self,
+        credential_id: str,
+        reporter_did: str,
+        issuer_did: str,
+        reason: str,
+    ) -> DisputeResult:
+        """File a dispute against a credential."""
+        data = self._request(
+            "POST", "/disputes",
+            json={
+                "credentialId": credential_id,
+                "reporterDid": reporter_did,
+                "issuerDid": issuer_did,
+                "reason": reason,
+            },
+        )
+        return DisputeResult.model_validate(data)
+
+    def get_dispute(self, dispute_id: str) -> dict:
+        """Get dispute details."""
+        return self._request("GET", f"/disputes/{dispute_id}")
+
+    def list_disputes(self, issuer_did: str | None = None) -> list[dict]:
+        """List disputes, optionally filtered by issuer."""
+        params = {"issuer": issuer_did} if issuer_did else {}
+        data = self._request("GET", "/disputes", params=params)
+        return data if isinstance(data, list) else data.get("disputes", [])
+
+
+    # --- Reputation ---
+
+    def get_reputation(self, did: str) -> dict:
+        """Get an issuer's reputation score."""
+        return self._request("GET", f"/reputation/{did}")
+
+    def submit_feedback(self, did: str, positive: bool, detail: str = "") -> dict:
+        """Submit verifier feedback on an issuer."""
+        return self._request(
+            "POST", f"/reputation/{did}/feedback",
+            json={"positive": positive, "detail": detail},
+        )
+
+    # --- Webhooks ---
+
+    def register_webhook(self, url: str, events: list[str]) -> WebhookResult:
+        """Register a webhook endpoint."""
+        data = self._request(
+            "POST", "/webhooks",
+            json={"url": url, "events": events},
+        )
+        return WebhookResult.model_validate(data)
+
+    def list_webhooks(self) -> list[dict]:
+        """List registered webhooks."""
+        data = self._request("GET", "/webhooks")
+        return data if isinstance(data, list) else data.get("webhooks", [])
+
+    def delete_webhook(self, webhook_id: str) -> dict:
+        """Delete a webhook subscription."""
+        return self._request("DELETE", f"/webhooks/{webhook_id}")
+
+    # --- Billing ---
+
+    def get_subscription(self) -> Subscription:
+        """Get current billing subscription."""
+        data = self._request("GET", "/billing/subscription")
+        return Subscription.model_validate(data)
+
+    def get_usage(self) -> UsageInfo:
+        """Get current period usage and quotas."""
+        data = self._request("GET", "/billing/usage")
+        return UsageInfo.model_validate(data)
+
+    def subscribe(self, plan: str) -> dict:
+        """Create or change a billing subscription."""
+        return self._request("POST", "/billing/subscribe", json={"plan": plan})
+
+    def get_billing_portal_url(self, return_url: str = "") -> str:
+        """Get a Stripe billing portal URL for self-service management."""
+        payload = {"returnUrl": return_url} if return_url else {}
+        data = self._request("POST", "/billing/portal", json=payload)
+        return data.get("url", "")
+
+    # --- Keys ---
+
+    def rotate_key(self, did: str) -> dict:
+        """Rotate the signing key for a DID."""
+        return self._request("POST", f"/keys/{did}/rotate")
+
+    def list_key_versions(self, did: str) -> list[dict]:
+        """List all key versions for a DID."""
+        data = self._request("GET", f"/keys/{did}/versions")
+        return data if isinstance(data, list) else []

vercre_sdk-1.0.0/src/vercre_sdk/exceptions.py

@@ -0,0 +1,46 @@
+"""SDK exceptions for VERCRE API errors."""
+
+
+class VercreError(Exception):
+    """Base exception for all VERCRE SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, detail: str | None = None):
+        self.status_code = status_code
+        self.detail = detail or message
+        super().__init__(message)
+
+
+class AuthenticationError(VercreError):
+    """Raised when API key is missing or invalid (401)."""
+
+
+class ForbiddenError(VercreError):
+    """Raised when the API key lacks permission for the operation (403)."""
+
+
+class NotFoundError(VercreError):
+    """Raised when a requested resource does not exist (404)."""
+
+
+class ValidationError(VercreError):
+    """Raised when request data fails validation (400/422)."""
+
+
+class RateLimitError(VercreError):
+    """Raised when rate limit is exceeded (429).
+
+    Attributes:
+        retry_after: Seconds to wait before retrying.
+    """
+
+    def __init__(self, message: str, retry_after: int | None = None, **kwargs):
+        self.retry_after = retry_after
+        super().__init__(message, **kwargs)
+
+
+class ServerError(VercreError):
+    """Raised when the VERCRE API returns a 5xx error."""
+
+
+class ConflictError(VercreError):
+    """Raised when the request conflicts with existing state (409)."""

vercre_sdk-1.0.0/src/vercre_sdk/models.py

@@ -0,0 +1,121 @@
+"""Response models for the VERCRE SDK."""
+
+from pydantic import BaseModel, Field
+
+
+class Credential(BaseModel):
+    """An issued verifiable credential."""
+
+    credential: dict = Field(description="Full signed VC object.")
+    credential_hash: str = Field(alias="credentialHash", description="SHA-256 hash.")
+    credential_id: str = Field(alias="credentialId", description="Unique ID.")
+    transaction_id: str = Field(alias="transactionId", description="On-chain tx ID.")
+
+
+class IssuerInfo(BaseModel):
+    """Issuer details from verification."""
+
+    did: str
+    tier: str
+    reputation: int
+    status: str
+
+
+class CredentialInfo(BaseModel):
+    """Credential metadata from verification."""
+
+    type: str
+    expired: bool
+    revoked: bool
+
+
+class VerificationResult(BaseModel):
+    """Result of a credential verification."""
+
+    valid: bool
+    issuer: IssuerInfo | None = None
+    credential: CredentialInfo | None = None
+    confidence_score: float | None = Field(None, alias="confidenceScore")
+    compliance_decision: str = Field(alias="complianceDecision")
+    reasons: list[str] = Field(default_factory=list)
+
+
+
+class Issuer(BaseModel):
+    """Registered issuer information."""
+
+    did: str
+    tier: str
+    reputation: int
+    status: str
+    stake: float
+    name: str | None = None
+
+
+class Subscription(BaseModel):
+    """Billing subscription state."""
+
+    plan: str
+    active: bool = True
+    stripe_customer_id: str | None = Field(None, alias="stripeCustomerId")
+    stripe_subscription_id: str | None = Field(None, alias="stripeSubscriptionId")
+
+
+class UsageInfo(BaseModel):
+    """Current period usage information."""
+
+    plan: str
+    # Issuer fields
+    issuances: int | None = None
+    included_issuances: int | None = Field(None, alias="includedIssuances")
+    remaining_issuances: int | None = Field(None, alias="remainingIssuances")
+    anchors: int | None = None
+    included_anchors: int | None = Field(None, alias="includedAnchors")
+    remaining_anchors: int | None = Field(None, alias="remainingAnchors")
+    # Verifier fields
+    verifications: int | None = None
+    included: int | None = None
+    remaining: int | None = None
+    rate_limit_rpm: int | None = Field(None, alias="rateLimitRpm")
+
+
+class OnboardResult(BaseModel):
+    """Result of onboarding (signup)."""
+
+    did: str
+    name: str
+    api_key: str = Field(alias="apiKey")
+    api_key_id: str = Field(alias="apiKeyId")
+    plan: str | None = None
+    tier: str | None = None
+    status: str | None = None
+
+
+class CredentialStatus(BaseModel):
+    """On-chain credential status."""
+
+    status: str
+    revoked: bool
+    expired: bool
+
+
+class DisputeResult(BaseModel):
+    """Filed dispute result."""
+
+    id: str
+    credential_id: str = Field(alias="credentialId")
+    reporter_did: str = Field(alias="reporterDid")
+    issuer_did: str = Field(alias="issuerDid")
+    reason: str
+    status: str
+    created_at: str = Field(alias="createdAt")
+
+
+class WebhookResult(BaseModel):
+    """Registered webhook."""
+
+    id: str
+    url: str
+    events: list[str]
+    created_at: str = Field(alias="createdAt")
+    active: bool