vendorval-sdk 0.2.0__py3-none-any.whl

vendorval_sdk/__init__.py

@@ -0,0 +1,44 @@
+"""Official Python SDK for the VendorVal API."""
+
+from ._async_client import AsyncVendorval
+from ._client import Vendorval
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    CountryError,
+    NotFoundError,
+    PermissionError,
+    ProviderError,
+    RateLimitError,
+    ValidationError,
+    VendorvalError,
+)
+from ._idempotency import generate_idempotency_key
+from ._pagination import Page
+from ._version import API_VERSION, VERSION
+from ._webhooks import construct_event
+
+__all__ = [
+    "API_VERSION",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncVendorval",
+    "AuthenticationError",
+    "ConflictError",
+    "CountryError",
+    "NotFoundError",
+    "Page",
+    "PermissionError",
+    "ProviderError",
+    "RateLimitError",
+    "VERSION",
+    "ValidationError",
+    "Vendorval",
+    "VendorvalError",
+    "construct_event",
+    "generate_idempotency_key",
+]

vendorval_sdk/_async_client.py

@@ -0,0 +1,84 @@
+"""Asynchronous client."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._request import resolve_config
+from ._version import API_VERSION, VERSION
+from ._webhooks import construct_event
+from .resources._entities import AsyncEntitiesResource
+from .resources._meta import AsyncMetaResource
+from .resources._monitors import AsyncMonitorsResource
+from .resources._simple import AsyncJobsResource, AsyncProvidersResource, AsyncUsageResource
+from .resources._verifications import AsyncVerificationsResource
+
+
+class _Webhooks:
+    construct_event = staticmethod(construct_event)
+
+
+class AsyncVendorval:
+    """Asynchronous VendorVal client.
+
+    Use as an async context manager so the underlying httpx client is closed:
+
+        async with AsyncVendorval() as client:
+            await client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+    """
+
+    VERSION = VERSION
+    API_VERSION = API_VERSION
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        validate_api_key: bool = True,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._cfg = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            validate_api_key=validate_api_key,
+        )
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self._cfg.timeout)
+        self.entities = AsyncEntitiesResource(self._cfg, self._http)
+        self.verifications = AsyncVerificationsResource(self._cfg, self._http)
+        self.monitors = AsyncMonitorsResource(self._cfg, self._http)
+        self.providers = AsyncProvidersResource(self._cfg, self._http)
+        self.meta = AsyncMetaResource(self._cfg, self._http)
+        self.usage = AsyncUsageResource(self._cfg, self._http)
+        self.jobs = AsyncJobsResource(self._cfg, self._http)
+        self.webhooks = _Webhooks()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncVendorval:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    @property
+    def api_key(self) -> str:
+        return self._cfg.api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._cfg.base_url

vendorval_sdk/_client.py

@@ -0,0 +1,87 @@
+"""Synchronous client."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._request import resolve_config
+from ._version import API_VERSION, VERSION
+from ._webhooks import construct_event
+from .resources._entities import EntitiesResource
+from .resources._meta import MetaResource
+from .resources._monitors import MonitorsResource
+from .resources._simple import JobsResource, ProvidersResource, UsageResource
+from .resources._verifications import VerificationsResource
+
+
+class _Webhooks:
+    construct_event = staticmethod(construct_event)
+
+
+class Vendorval:
+    """Synchronous VendorVal client.
+
+    Construct directly or use as a context manager:
+
+        with Vendorval() as client:
+            client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+
+    The constructor reads `VENDORVAL_API_KEY` and `VENDORVAL_BASE_URL` from
+    the environment if not supplied.
+    """
+
+    VERSION = VERSION
+    API_VERSION = API_VERSION
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        validate_api_key: bool = True,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._cfg = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            validate_api_key=validate_api_key,
+        )
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self._cfg.timeout)
+        self.entities = EntitiesResource(self._cfg, self._http)
+        self.verifications = VerificationsResource(self._cfg, self._http)
+        self.monitors = MonitorsResource(self._cfg, self._http)
+        self.providers = ProvidersResource(self._cfg, self._http)
+        self.meta = MetaResource(self._cfg, self._http)
+        self.usage = UsageResource(self._cfg, self._http)
+        self.jobs = JobsResource(self._cfg, self._http)
+        self.webhooks = _Webhooks()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Vendorval:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    @property
+    def api_key(self) -> str:
+        return self._cfg.api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._cfg.base_url

vendorval_sdk/_errors.py

@@ -0,0 +1,205 @@
+"""Error classes mirroring the VendorVal API error envelope."""
+
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+
+class VendorvalError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        type: str = "api_error",
+        code: str = "api_error",
+        request_id: str | None = None,
+        param: str | None = None,
+        details: Any = None,
+        headers: httpx.Headers | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+        self.code = code
+        self.request_id = request_id
+        self.param = param
+        self.details = details
+        self.headers = headers
+
+
+class APIError(VendorvalError):
+    pass
+
+
+class AuthenticationError(VendorvalError):
+    pass
+
+
+class PermissionError(VendorvalError):  # noqa: A001 - shadowing builtin is intentional
+    pass
+
+
+class ValidationError(VendorvalError):
+    pass
+
+
+class CountryError(ValidationError):
+    """422 raised when a request can't be routed to a country/provider.
+
+    Subclass of :class:`ValidationError` so existing 4xx catch-all handlers
+    continue to match. Use ``err.code`` to switch on the specific failure:
+
+      - ``country_required`` — no explicit country and nothing inferable
+      - ``country_not_supported`` — resolved country isn't in SUPPORTED_COUNTRIES
+      - ``identifier_not_supported_for_country`` — e.g. ``tin`` with ``country='DE'``
+      - ``check_not_supported_for_country`` — e.g. ``sam_registration`` for an EU country
+      - ``country_mismatch`` — explicit country contradicts identifier inference
+
+    The ``details`` attribute carries a :data:`CountryErrorDetails`-shaped dict
+    with ``country_resolved``, ``identifiers_seen``, ``recommended_action``,
+    ``supported_countries``, and (for ``country_mismatch``) ``candidates``.
+    """
+
+
+_COUNTRY_ERROR_CODES = frozenset(
+    {
+        "country_required",
+        "country_not_supported",
+        "identifier_not_supported_for_country",
+        "check_not_supported_for_country",
+        "country_mismatch",
+    }
+)
+
+
+class NotFoundError(VendorvalError):
+    pass
+
+
+class ConflictError(VendorvalError):
+    def __init__(self, *args: Any, candidates: list[Any] | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.candidates = candidates
+
+
+class RateLimitError(VendorvalError):
+    def __init__(self, *args: Any, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class ProviderError(VendorvalError):
+    pass
+
+
+class APIConnectionError(VendorvalError):
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(
+            message,
+            status=0,
+            type="connection_error",
+            code="connection_error",
+            request_id=request_id,
+        )
+
+
+class APITimeoutError(APIConnectionError):
+    def __init__(self, timeout: float, *, request_id: str | None = None) -> None:
+        super().__init__(f"Request timed out after {timeout}s", request_id=request_id)
+
+
+_STATUS_TO_CLS: dict[int, type[VendorvalError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionError,
+    404: NotFoundError,
+    # 422 is an invalid-request status the API uses for semantic-validation
+    # failures (Phase J country routing emits 422 + CountryError, but other
+    # semantic violations also land here). Mapping to ValidationError keeps
+    # catch-all 4xx handlers working consistently.
+    422: ValidationError,
+    429: RateLimitError,
+    502: ProviderError,
+}
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    try:
+        dt = parsedate_to_datetime(value)
+        from datetime import datetime, timezone
+
+        return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
+    except (TypeError, ValueError):
+        return None
+
+
+def error_from_response(
+    *,
+    status: int,
+    payload: Any,
+    headers: httpx.Headers,
+    request_id: str | None,
+) -> VendorvalError:
+    envelope = None
+    if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+        envelope = payload["error"]
+
+    msg = (envelope or {}).get("message") or f"VendorVal API error (status {status})"
+    type_ = (envelope or {}).get("type") or "api_error"
+    code = (envelope or {}).get("code") or f"http_{status}"
+    param = (envelope or {}).get("param")
+    details = (envelope or {}).get("details")
+
+    common: dict[str, Any] = dict(
+        message=msg,
+        status=status,
+        type=type_,
+        code=code,
+        request_id=request_id,
+        param=param,
+        details=details,
+        headers=headers,
+    )
+
+    if status == 409:
+        candidates = None
+        if envelope:
+            if isinstance(envelope.get("candidates"), list):
+                candidates = envelope["candidates"]
+            elif isinstance(envelope.get("details"), dict):
+                inner = envelope["details"].get("candidates")
+                if isinstance(inner, list):
+                    candidates = inner
+        return ConflictError(**common, candidates=candidates)
+
+    if status == 429:
+        return RateLimitError(
+            **common,
+            retry_after=parse_retry_after(headers.get("retry-after")),
+        )
+
+    # Phase J: 422 envelopes with a country-routing code surface as CountryError
+    # (a ValidationError subclass) so consumers can switch on `err.code` and
+    # inspect the structured `err.details` payload. The `isinstance(code, str)`
+    # guard handles malformed payloads where `code` is a non-string (e.g. a list
+    # or dict) — set membership on a frozenset[str] would otherwise TypeError
+    # on unhashable values, breaking error normalization for the rest of the
+    # response.
+    if status == 422 and isinstance(code, str) and code in _COUNTRY_ERROR_CODES:
+        return CountryError(**common)
+
+    cls = _STATUS_TO_CLS.get(status, APIError)
+    return cls(**common)

vendorval_sdk/_idempotency.py

@@ -0,0 +1,10 @@
+"""Idempotency key helpers."""
+
+from __future__ import annotations
+
+import uuid
+
+
+def generate_idempotency_key() -> str:
+    """Return a UUID4 string suitable for `options.idempotency_key`."""
+    return str(uuid.uuid4())

vendorval_sdk/_models.py

@@ -0,0 +1,59 @@
+"""Lightweight response wrappers that expose `request_id`.
+
+Kept as `__getattr__`-backed dict facades so we don't tie the SDK to a strict
+schema while the API is still stabilizing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Response:
+    """Dict-backed object that exposes the API response plus `_request_id`."""
+
+    __slots__ = ("_data", "_request_id", "_status")
+
+    def __init__(self, data: Any, request_id: str | None, status: int) -> None:
+        self._data = data if isinstance(data, dict) else {}
+        self._request_id = request_id
+        self._status = status
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._data[name]
+        except KeyError as err:
+            raise AttributeError(name) from err
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    @property
+    def request_id(self) -> str | None:
+        return self._request_id
+
+    @property
+    def status(self) -> int:
+        return self._status
+
+    def __repr__(self) -> str:
+        return f"<Response request_id={self._request_id!r} status={self._status}>"
+
+
+class VerificationBundleResponse(Response):
+    @property
+    def entity(self) -> Response:
+        return Response(self._data.get("entity"), self._request_id, self._status)
+
+    @property
+    def verification(self) -> Response:
+        return Response(self._data.get("verification"), self._request_id, self._status)

vendorval_sdk/_pagination.py

@@ -0,0 +1,34 @@
+"""Pagination helpers.
+
+Today list endpoints return arrays. Wrapping in `Page` keeps the
+`for item in page` and `async for item in page` shapes stable for when
+the API ships cursor pagination.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Page(Generic[T]):
+    def __init__(self, items: list[T]) -> None:
+        self._items = list(items)
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self._items)
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        for item in self._items:
+            yield item
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __getitem__(self, index: int) -> T:
+        return self._items[index]
+
+    def all(self) -> list[T]:
+        return list(self._items)