vendorval-sdk 0.2.0__tar.gz

vendorval_sdk-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+node_modules/
+dist/
+build/
+*.tsbuildinfo
+.turbo/
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+coverage.xml
+.coverage
+
+# editor
+.vscode/
+.idea/
+.DS_Store
+
+# env
+.env
+.env.local
+
+# Local scratch — the canonical live smoke harnesses live under
+# examples/{node,python}/live-smoke/. Keep test-python/ out of commits in
+# case it stays around in working trees.
+test-python/

vendorval_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# vendorval-sdk (Python)
+
+## 0.2.0 — 2026-05-05
+
+**Breaking:** Renamed PyPI distribution from `vendorval` to `vendorval-sdk` and import path from `vendorval` to `vendorval_sdk` to avoid collisions with the `vendorval` Frappe app and other downstream packages that want to claim the `vendorval` namespace. Update consumers:
+
+```diff
+- pip install vendorval
++ pip install vendorval-sdk
+```
+
+```diff
+- from vendorval import Vendorval
++ from vendorval_sdk import Vendorval
+```
+
+The public class names (`Vendorval`, `AsyncVendorval`, error types, `construct_event`, …) and their behaviour are unchanged.
+
+**New — country-aware SDK surface (Phase J):**
+
+- `IdentifierType` extended with `vat_id`; `CheckType` extended with `vat_validation`, `lei_validation`, `sanctions_screening`.
+- New `CountryCode`, `EntityRegion`, `CountryTier` types and a typed `SupportedCountrySummary` / `SupportedCountriesResponse` pair mirroring `/v1/meta/countries`.
+- New `MetaResource` exposing `client.meta.list_supported_countries()` and `client.meta.get_supported_country(code)` (sync + async).
+- `entities.lookup` / `verifications.create` accept an optional `country` parameter that is forwarded to the API.
+- New `CountryError` (subclass of `ValidationError`) wired into the response-to-error mapping for the five 422 codes: `country_required`, `country_not_supported`, `identifier_not_supported_for_country`, `check_not_supported_for_country`, `country_mismatch`. Plain 422 responses now map to `ValidationError` so non-country semantic violations inherit the same catch-all behaviour.
+
+## 0.1.0 — Unreleased
+
+Initial public release.
+
+- `Vendorval` (sync) and `AsyncVendorval` (async) clients with `api_key` / `base_url` / `timeout` / `max_retries` options.
+- Resources: `entities`, `verifications` (incl. `create_and_wait`), `monitors`, `providers`, `usage`, `jobs`.
+- Auto-retry on `429` and `5xx` honoring `retry-after` and `x-ratelimit-reset`.
+- Auto-generated idempotency keys for retried POSTs to verification endpoints.
+- Typed errors: `AuthenticationError`, `PermissionError`, `ValidationError`, `RateLimitError`, `NotFoundError`, `ConflictError`, `ProviderError`, `APIError`.
+- `request_id` exposed on every response and error.
+- Forward-compatible `webhooks.construct_event` (placeholder until outbound delivery ships).

vendorval_sdk-0.2.0/LICENSE

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

vendorval_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: vendorval-sdk
+Version: 0.2.0
+Summary: Official Python SDK for the VendorVal API
+Project-URL: Homepage, https://docs.vendorval.com
+Project-URL: Documentation, https://docs.vendorval.com
+Project-URL: Source, https://github.com/Modali-Consulting/vendorval-sdk
+Project-URL: Issues, https://github.com/Modali-Consulting/vendorval-sdk/issues
+Author: Modali Consulting
+License: MIT
+License-File: LICENSE
+Keywords: api,compliance,sam.gov,sdk,tin,vendor,vendorval,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# vendorval-sdk
+
+Official Python SDK for the [VendorVal API](https://docs.vendorval.com).
+
+```bash
+pip install vendorval-sdk
+```
+
+## Quick start
+
+```python
+from vendorval_sdk import Vendorval
+
+client = Vendorval()  # reads VENDORVAL_API_KEY from env
+
+# 1) Look up an entity by identifier
+lookup = client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+if lookup.match == "not_found":
+    raise SystemExit("entity not in registry")
+
+# 2) Run a verification and wait for the terminal result
+bundle = client.verifications.create_and_wait(
+    identifiers=[{"type": "uei", "value": "ABCD12345678"}],
+    legal_name="Acme Federal Services LLC",
+    checks=["sam_registration"],
+    mode="cached",
+)
+print(bundle.verification.overall_result)
+```
+
+### Async
+
+```python
+import asyncio
+from vendorval_sdk import AsyncVendorval
+
+async def main() -> None:
+    async with AsyncVendorval() as client:
+        result = await client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+        print(result.match)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+client = Vendorval(
+    api_key="vv_live_…",
+    base_url="https://api.vendorval.com",
+    timeout=30.0,                 # seconds, default 60
+    max_retries=2,                # default 2
+)
+```
+
+API keys are prefixed `vv_test_` (sandbox) or `vv_live_` (production). The SDK validates the prefix client-side.
+
+## Errors
+
+```python
+from vendorval_sdk import RateLimitError, ConflictError, ValidationError
+
+try:
+    client.verifications.create(...)
+except RateLimitError as err:
+    print("rate limited, retry after", err.retry_after, "seconds")
+except ConflictError as err:
+    print("ambiguous match", err.candidates)
+```
+
+All errors carry `request_id`, `status`, `code`, `type`, `message`.
+
+## Webhooks
+
+```python
+from vendorval_sdk import construct_event
+
+event = construct_event(raw_body, signature_header, secret)
+```
+
+> Outbound webhook delivery is not enabled in the API yet; this helper exists so handler code is ready when delivery lands.
+
+## License
+
+[MIT](./LICENSE)

vendorval_sdk-0.2.0/README.md

@@ -0,0 +1,85 @@
+# vendorval-sdk
+
+Official Python SDK for the [VendorVal API](https://docs.vendorval.com).
+
+```bash
+pip install vendorval-sdk
+```
+
+## Quick start
+
+```python
+from vendorval_sdk import Vendorval
+
+client = Vendorval()  # reads VENDORVAL_API_KEY from env
+
+# 1) Look up an entity by identifier
+lookup = client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+if lookup.match == "not_found":
+    raise SystemExit("entity not in registry")
+
+# 2) Run a verification and wait for the terminal result
+bundle = client.verifications.create_and_wait(
+    identifiers=[{"type": "uei", "value": "ABCD12345678"}],
+    legal_name="Acme Federal Services LLC",
+    checks=["sam_registration"],
+    mode="cached",
+)
+print(bundle.verification.overall_result)
+```
+
+### Async
+
+```python
+import asyncio
+from vendorval_sdk import AsyncVendorval
+
+async def main() -> None:
+    async with AsyncVendorval() as client:
+        result = await client.entities.lookup(identifiers={"uei": "ABCD12345678"})
+        print(result.match)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+client = Vendorval(
+    api_key="vv_live_…",
+    base_url="https://api.vendorval.com",
+    timeout=30.0,                 # seconds, default 60
+    max_retries=2,                # default 2
+)
+```
+
+API keys are prefixed `vv_test_` (sandbox) or `vv_live_` (production). The SDK validates the prefix client-side.
+
+## Errors
+
+```python
+from vendorval_sdk import RateLimitError, ConflictError, ValidationError
+
+try:
+    client.verifications.create(...)
+except RateLimitError as err:
+    print("rate limited, retry after", err.retry_after, "seconds")
+except ConflictError as err:
+    print("ambiguous match", err.candidates)
+```
+
+All errors carry `request_id`, `status`, `code`, `type`, `message`.
+
+## Webhooks
+
+```python
+from vendorval_sdk import construct_event
+
+event = construct_event(raw_body, signature_header, secret)
+```
+
+> Outbound webhook delivery is not enabled in the API yet; this helper exists so handler code is ready when delivery lands.
+
+## License
+
+[MIT](./LICENSE)

vendorval_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vendorval-sdk"
+version = "0.2.0"
+description = "Official Python SDK for the VendorVal API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Modali Consulting" }]
+keywords = ["vendorval", "vendor", "verification", "sam.gov", "tin", "compliance", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25",
+    "typing-extensions>=4.7; python_version<'3.11'",
+]
+
+[project.urls]
+Homepage = "https://docs.vendorval.com"
+Documentation = "https://docs.vendorval.com"
+Source = "https://github.com/Modali-Consulting/vendorval-sdk"
+Issues = "https://github.com/Modali-Consulting/vendorval-sdk/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vendorval_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+mypy_path = "src"
+packages = ["vendorval_sdk"]

vendorval_sdk-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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