vericorp 1.0.0__tar.gz

vericorp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

vericorp-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/

vericorp-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: vericorp
+Version: 1.0.0
+Summary: Python SDK for the VeriCorp API — European company verification
+Project-URL: Homepage, https://github.com/vericorptest-collab/vericorp-python
+Project-URL: Documentation, https://rapidapi.com/vericorp/api/vericorp-api
+Author: VeriCorp
+License-Expression: MIT
+Keywords: api,company,europe,tax-id,validation,vat,vies
+Classifier: Development Status :: 5 - Production/Stable
+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>=0.24
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# VeriCorp Python SDK
+
+Python SDK for the [VeriCorp API](https://rapidapi.com/vericorp/api/vericorp-api) — European company verification.
+
+## Install
+
+```bash
+pip install vericorp
+```
+
+## Quick Start
+
+```python
+from vericorp import VeriCorp
+
+client = VeriCorp("your-rapidapi-key")
+
+# Look up a company
+company = client.lookup("PT502011378")
+print(company.name)       # UNIVERSIDADE DO MINHO
+print(company.address)    # Address(street='LG DO PACO', city='BRAGA', ...)
+
+# Validate a VAT number
+result = client.validate("DE811871080")
+print(result.vat_valid)   # True
+
+# List supported countries
+countries = client.countries()
+print(countries.total)    # 29
+```
+
+## Async
+
+```python
+from vericorp import AsyncVeriCorp
+
+async with AsyncVeriCorp("your-rapidapi-key") as client:
+    company = await client.lookup("DK10150817")
+    print(company.name)
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `lookup(tax_id)` | Look up company by tax ID |
+| `lookup_gb(company_number)` | Look up UK company by number |
+| `validate(tax_id)` | Validate a VAT number |
+| `batch(tax_ids)` | Batch lookup (max 10) |
+| `countries()` | List supported countries |
+| `health()` | API health check |
+
+## Error Handling
+
+```python
+from vericorp.errors import InvalidTaxIdError, NotFoundError, RateLimitError
+
+try:
+    company = client.lookup("INVALID")
+except InvalidTaxIdError:
+    print("Bad tax ID format")
+except NotFoundError:
+    print("Company not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+```
+
+## License
+
+MIT

vericorp-1.0.0/README.md

@@ -0,0 +1,70 @@
+# VeriCorp Python SDK
+
+Python SDK for the [VeriCorp API](https://rapidapi.com/vericorp/api/vericorp-api) — European company verification.
+
+## Install
+
+```bash
+pip install vericorp
+```
+
+## Quick Start
+
+```python
+from vericorp import VeriCorp
+
+client = VeriCorp("your-rapidapi-key")
+
+# Look up a company
+company = client.lookup("PT502011378")
+print(company.name)       # UNIVERSIDADE DO MINHO
+print(company.address)    # Address(street='LG DO PACO', city='BRAGA', ...)
+
+# Validate a VAT number
+result = client.validate("DE811871080")
+print(result.vat_valid)   # True
+
+# List supported countries
+countries = client.countries()
+print(countries.total)    # 29
+```
+
+## Async
+
+```python
+from vericorp import AsyncVeriCorp
+
+async with AsyncVeriCorp("your-rapidapi-key") as client:
+    company = await client.lookup("DK10150817")
+    print(company.name)
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `lookup(tax_id)` | Look up company by tax ID |
+| `lookup_gb(company_number)` | Look up UK company by number |
+| `validate(tax_id)` | Validate a VAT number |
+| `batch(tax_ids)` | Batch lookup (max 10) |
+| `countries()` | List supported countries |
+| `health()` | API health check |
+
+## Error Handling
+
+```python
+from vericorp.errors import InvalidTaxIdError, NotFoundError, RateLimitError
+
+try:
+    company = client.lookup("INVALID")
+except InvalidTaxIdError:
+    print("Bad tax ID format")
+except NotFoundError:
+    print("Company not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+```
+
+## License
+
+MIT

vericorp-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vericorp"
+version = "1.0.0"
+description = "Python SDK for the VeriCorp API — European company verification"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "VeriCorp" }]
+keywords = ["vat", "validation", "company", "europe", "api", "tax-id", "vies"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "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",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vericorptest-collab/vericorp-python"
+Documentation = "https://rapidapi.com/vericorp/api/vericorp-api"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vericorp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vericorp-1.0.0/src/vericorp/__init__.py

@@ -0,0 +1,37 @@
+from .client import VeriCorp
+from .async_client import AsyncVeriCorp
+from .models import (
+    Company,
+    Address,
+    Contacts,
+    Director,
+    PSC,
+    ValidationResult,
+    CountriesResponse,
+    CountryInfo,
+    HealthResponse,
+    BatchResponse,
+)
+from .errors import VeriCorpError, RateLimitError, InvalidTaxIdError, NotFoundError, TimeoutError
+
+__all__ = [
+    "VeriCorp",
+    "AsyncVeriCorp",
+    "Company",
+    "Address",
+    "Contacts",
+    "Director",
+    "PSC",
+    "ValidationResult",
+    "CountriesResponse",
+    "CountryInfo",
+    "HealthResponse",
+    "BatchResponse",
+    "VeriCorpError",
+    "RateLimitError",
+    "InvalidTaxIdError",
+    "NotFoundError",
+    "TimeoutError",
+]
+
+__version__ = "1.0.0"

vericorp-1.0.0/src/vericorp/async_client.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+import asyncio
+import httpx
+from .models import Company, ValidationResult, CountriesResponse, HealthResponse, BatchResponse
+from .errors import VeriCorpError, RateLimitError, InvalidTaxIdError, NotFoundError, TimeoutError
+
+
+class AsyncVeriCorp:
+    """Async client for the VeriCorp API."""
+
+    BASE_URL = "https://vericorp-api.p.rapidapi.com"
+
+    def __init__(self, api_key: str, *, timeout: float = 10.0, max_retries: int = 2):
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            base_url=self.BASE_URL,
+            headers={
+                "X-RapidAPI-Key": api_key,
+                "X-RapidAPI-Host": "vericorp-api.p.rapidapi.com",
+            },
+            timeout=timeout,
+        )
+
+    async def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+
+                if response.status_code == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    if attempt < self._max_retries:
+                        wait = int(retry_after) if retry_after else (2 ** attempt)
+                        await asyncio.sleep(wait)
+                        continue
+                    raise RateLimitError(int(retry_after) if retry_after else None)
+
+                if response.status_code == 503 and attempt < self._max_retries:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+
+                return response
+            except httpx.TimeoutException:
+                last_error = TimeoutError()
+                if attempt < self._max_retries:
+                    continue
+                raise last_error
+            except (RateLimitError, TimeoutError):
+                raise
+            except httpx.HTTPError as e:
+                last_error = VeriCorpError(str(e))
+                if attempt < self._max_retries:
+                    continue
+                raise last_error
+
+        raise last_error or VeriCorpError("Request failed")
+
+    def _handle_error(self, response: httpx.Response, tax_id: str | None = None) -> None:
+        if response.status_code == 400:
+            raise InvalidTaxIdError(tax_id or "unknown")
+        if response.status_code == 404:
+            raise NotFoundError(tax_id or "unknown")
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(int(retry_after) if retry_after else None)
+        if response.status_code >= 400:
+            raise VeriCorpError(f"API error: {response.status_code}", response.status_code)
+
+    async def lookup(self, tax_id: str, *, force_refresh: bool = False) -> Company:
+        params = {"force_refresh": "true"} if force_refresh else {}
+        response = await self._request("GET", f"/v1/company/{tax_id}", params=params)
+        if not response.is_success:
+            self._handle_error(response, tax_id)
+        return Company.model_validate(response.json())
+
+    async def lookup_gb(self, company_number: str, *, force_refresh: bool = False) -> Company:
+        params = {"force_refresh": "true"} if force_refresh else {}
+        response = await self._request("GET", f"/v1/company/gb/{company_number}", params=params)
+        if not response.is_success:
+            self._handle_error(response, company_number)
+        return Company.model_validate(response.json())
+
+    async def validate(self, tax_id: str) -> ValidationResult:
+        response = await self._request("GET", f"/v1/validate/{tax_id}")
+        if not response.is_success:
+            self._handle_error(response, tax_id)
+        return ValidationResult.model_validate(response.json())
+
+    async def batch(self, tax_ids: list[str]) -> BatchResponse:
+        response = await self._request("POST", "/v1/batch", json={"tax_ids": tax_ids})
+        if not response.is_success:
+            self._handle_error(response)
+        return BatchResponse.model_validate(response.json())
+
+    async def countries(self) -> CountriesResponse:
+        response = await self._request("GET", "/v1/countries")
+        if not response.is_success:
+            self._handle_error(response)
+        return CountriesResponse.model_validate(response.json())
+
+    async def health(self) -> HealthResponse:
+        response = await self._request("GET", "/v1/health")
+        if not response.is_success:
+            self._handle_error(response)
+        return HealthResponse.model_validate(response.json())
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

vericorp-1.0.0/src/vericorp/client.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+import httpx
+from .models import Company, ValidationResult, CountriesResponse, HealthResponse, BatchResponse
+from .errors import VeriCorpError, RateLimitError, InvalidTaxIdError, NotFoundError, TimeoutError
+
+
+class VeriCorp:
+    """Synchronous client for the VeriCorp API."""
+
+    BASE_URL = "https://vericorp-api.p.rapidapi.com"
+
+    def __init__(self, api_key: str, *, timeout: float = 10.0, max_retries: int = 2):
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self.BASE_URL,
+            headers={
+                "X-RapidAPI-Key": api_key,
+                "X-RapidAPI-Host": "vericorp-api.p.rapidapi.com",
+            },
+            timeout=timeout,
+        )
+
+    def _request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+
+                if response.status_code == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    if attempt < self._max_retries:
+                        import time
+                        wait = int(retry_after) if retry_after else (2 ** attempt)
+                        time.sleep(wait)
+                        continue
+                    raise RateLimitError(int(retry_after) if retry_after else None)
+
+                if response.status_code == 503 and attempt < self._max_retries:
+                    import time
+                    time.sleep(2 ** attempt)
+                    continue
+
+                return response
+            except httpx.TimeoutException:
+                last_error = TimeoutError()
+                if attempt < self._max_retries:
+                    continue
+                raise last_error
+            except (RateLimitError, TimeoutError):
+                raise
+            except httpx.HTTPError as e:
+                last_error = VeriCorpError(str(e))
+                if attempt < self._max_retries:
+                    continue
+                raise last_error
+
+        raise last_error or VeriCorpError("Request failed")
+
+    def _handle_error(self, response: httpx.Response, tax_id: str | None = None) -> None:
+        if response.status_code == 400:
+            raise InvalidTaxIdError(tax_id or "unknown")
+        if response.status_code == 404:
+            raise NotFoundError(tax_id or "unknown")
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(int(retry_after) if retry_after else None)
+        if response.status_code >= 400:
+            raise VeriCorpError(f"API error: {response.status_code}", response.status_code)
+
+    def lookup(self, tax_id: str, *, force_refresh: bool = False) -> Company:
+        params = {"force_refresh": "true"} if force_refresh else {}
+        response = self._request("GET", f"/v1/company/{tax_id}", params=params)
+        if not response.is_success:
+            self._handle_error(response, tax_id)
+        return Company.model_validate(response.json())
+
+    def lookup_gb(self, company_number: str, *, force_refresh: bool = False) -> Company:
+        params = {"force_refresh": "true"} if force_refresh else {}
+        response = self._request("GET", f"/v1/company/gb/{company_number}", params=params)
+        if not response.is_success:
+            self._handle_error(response, company_number)
+        return Company.model_validate(response.json())
+
+    def validate(self, tax_id: str) -> ValidationResult:
+        response = self._request("GET", f"/v1/validate/{tax_id}")
+        if not response.is_success:
+            self._handle_error(response, tax_id)
+        return ValidationResult.model_validate(response.json())
+
+    def batch(self, tax_ids: list[str]) -> BatchResponse:
+        response = self._request("POST", "/v1/batch", json={"tax_ids": tax_ids})
+        if not response.is_success:
+            self._handle_error(response)
+        return BatchResponse.model_validate(response.json())
+
+    def countries(self) -> CountriesResponse:
+        response = self._request("GET", "/v1/countries")
+        if not response.is_success:
+            self._handle_error(response)
+        return CountriesResponse.model_validate(response.json())
+
+    def health(self) -> HealthResponse:
+        response = self._request("GET", "/v1/health")
+        if not response.is_success:
+            self._handle_error(response)
+        return HealthResponse.model_validate(response.json())
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

vericorp-1.0.0/src/vericorp/errors.py

@@ -0,0 +1,37 @@
+class VeriCorpError(Exception):
+    """Base error for VeriCorp API."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class RateLimitError(VeriCorpError):
+    """Raised when API rate limit is exceeded (429)."""
+
+    def __init__(self, retry_after: int | None = None):
+        super().__init__("Rate limit exceeded", 429)
+        self.retry_after = retry_after
+
+
+class InvalidTaxIdError(VeriCorpError):
+    """Raised when the tax ID format is invalid (400)."""
+
+    def __init__(self, tax_id: str):
+        super().__init__(f"Invalid tax ID: {tax_id}", 400)
+        self.tax_id = tax_id
+
+
+class NotFoundError(VeriCorpError):
+    """Raised when a company is not found (404)."""
+
+    def __init__(self, tax_id: str):
+        super().__init__(f"Company not found: {tax_id}", 404)
+        self.tax_id = tax_id
+
+
+class TimeoutError(VeriCorpError):
+    """Raised when a request times out."""
+
+    def __init__(self):
+        super().__init__("Request timed out")

vericorp-1.0.0/src/vericorp/models.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class Address(BaseModel):
+    street: Optional[str] = None
+    city: Optional[str] = None
+    postal_code: Optional[str] = None
+    region: Optional[str] = None
+    country: Optional[str] = None
+
+
+class Contacts(BaseModel):
+    phone: Optional[str] = None
+    fax: Optional[str] = None
+    email: Optional[str] = None
+    website: Optional[str] = None
+
+
+class Director(BaseModel):
+    name: Optional[str] = None
+    role: Optional[str] = None
+    appointed_on: Optional[str] = None
+    resigned_on: Optional[str] = None
+
+
+class PSC(BaseModel):
+    name: Optional[str] = None
+    natures_of_control: Optional[list[str]] = None
+    notified_on: Optional[str] = None
+
+
+class Company(BaseModel):
+    tax_id: str
+    country: str
+    name: str
+    address: Optional[Address] = None
+    legal_form: Optional[str] = None
+    status: Optional[str] = None
+    incorporation_date: Optional[str] = None
+    activity_code: Optional[str] = None
+    activity_description: Optional[str] = None
+    capital: Optional[float] = None
+    capital_currency: Optional[str] = None
+    contacts: Optional[Contacts] = None
+    directors: Optional[list[Director]] = None
+    psc: Optional[list[PSC]] = None
+    vat_valid: Optional[bool] = None
+    vat_consultation_number: Optional[str] = None
+    source: str
+    data_quality: str
+    cached: bool
+    stale: Optional[bool] = None
+    data_age_days: Optional[int] = None
+    fetched_at: str
+
+
+class ValidationResult(BaseModel):
+    tax_id: str
+    country: str
+    format_valid: bool
+    vat_valid: Optional[bool] = None
+    company_name: Optional[str] = None
+    consultation_number: Optional[str] = None
+
+
+class CountryInfo(BaseModel):
+    code: str
+    name: str
+    enriched: bool
+    source: Optional[str] = None
+    vat_validation: bool
+
+
+class CountriesResponse(BaseModel):
+    total: int
+    enriched: int
+    vat_validation: int
+    countries: list[CountryInfo]
+
+
+class SourceHealth(BaseModel):
+    status: str
+    latency_ms: Optional[int] = None
+    budget_remaining: Optional[int] = None
+
+
+class CacheHealth(BaseModel):
+    status: str
+
+
+class HealthResponse(BaseModel):
+    status: str
+    timestamp: str
+    sources: Optional[dict[str, SourceHealth]] = None
+    cache: Optional[CacheHealth] = None
+
+
+class BatchError(BaseModel):
+    tax_id: str
+    error: str
+    code: str
+
+
+class BatchResponse(BaseModel):
+    total: int
+    successful: int
+    results: list[Company | BatchError]

vericorp-1.0.0/tests/test_async_client.py

@@ -0,0 +1,67 @@
+import pytest
+import httpx
+from unittest.mock import patch, MagicMock, AsyncMock
+from vericorp import AsyncVeriCorp, Company, ValidationResult
+from vericorp.errors import InvalidTaxIdError, RateLimitError
+
+
+COMPANY_JSON = {
+    "tax_id": "PT502011378",
+    "country": "PT",
+    "name": "UNIVERSIDADE DO MINHO",
+    "address": {"street": "LG DO PACO", "city": "BRAGA", "postal_code": "4700-320", "country": "PT"},
+    "source": "nifpt",
+    "data_quality": "full",
+    "cached": True,
+    "fetched_at": "2026-01-01T00:00:00Z",
+}
+
+VALIDATION_JSON = {
+    "tax_id": "PT502011378",
+    "country": "PT",
+    "format_valid": True,
+    "vat_valid": True,
+    "company_name": "UNIVERSIDADE DO MINHO",
+}
+
+
+def mock_response(status_code: int = 200, json_data: dict | None = None, headers: dict | None = None) -> MagicMock:
+    response = MagicMock(spec=httpx.Response)
+    response.status_code = status_code
+    response.is_success = 200 <= status_code < 300
+    response.json.return_value = json_data or {}
+    response.headers = headers or {}
+    return response
+
+
+@pytest.mark.asyncio
+class TestAsyncVeriCorp:
+    async def test_lookup(self):
+        client = AsyncVeriCorp("test-key")
+        with patch.object(client._client, "request", new_callable=AsyncMock, return_value=mock_response(200, COMPANY_JSON)):
+            result = await client.lookup("PT502011378")
+            assert isinstance(result, Company)
+            assert result.name == "UNIVERSIDADE DO MINHO"
+
+    async def test_validate(self):
+        client = AsyncVeriCorp("test-key")
+        with patch.object(client._client, "request", new_callable=AsyncMock, return_value=mock_response(200, VALIDATION_JSON)):
+            result = await client.validate("PT502011378")
+            assert isinstance(result, ValidationResult)
+            assert result.vat_valid is True
+
+    async def test_invalid_tax_id(self):
+        client = AsyncVeriCorp("test-key")
+        with patch.object(client._client, "request", new_callable=AsyncMock, return_value=mock_response(400)):
+            with pytest.raises(InvalidTaxIdError):
+                await client.lookup("INVALID")
+
+    async def test_rate_limit(self):
+        client = AsyncVeriCorp("test-key", max_retries=0)
+        with patch.object(client._client, "request", new_callable=AsyncMock, return_value=mock_response(429, headers={"Retry-After": "10"})):
+            with pytest.raises(RateLimitError):
+                await client.lookup("PT502011378")
+
+    async def test_async_context_manager(self):
+        async with AsyncVeriCorp("test-key") as client:
+            assert client._client is not None

vericorp-1.0.0/tests/test_client.py

@@ -0,0 +1,125 @@
+import pytest
+import httpx
+from unittest.mock import patch, MagicMock
+from vericorp import VeriCorp, Company, ValidationResult, CountriesResponse, HealthResponse, BatchResponse
+from vericorp.errors import InvalidTaxIdError, NotFoundError, RateLimitError
+
+
+COMPANY_JSON = {
+    "tax_id": "PT502011378",
+    "country": "PT",
+    "name": "UNIVERSIDADE DO MINHO",
+    "address": {"street": "LG DO PACO", "city": "BRAGA", "postal_code": "4700-320", "country": "PT"},
+    "source": "nifpt",
+    "data_quality": "full",
+    "cached": True,
+    "fetched_at": "2026-01-01T00:00:00Z",
+}
+
+VALIDATION_JSON = {
+    "tax_id": "PT502011378",
+    "country": "PT",
+    "format_valid": True,
+    "vat_valid": True,
+    "company_name": "UNIVERSIDADE DO MINHO",
+}
+
+COUNTRIES_JSON = {
+    "total": 29,
+    "enriched": 8,
+    "vat_validation": 28,
+    "countries": [{"code": "PT", "name": "Portugal", "enriched": True, "source": "nifpt", "vat_validation": True}],
+}
+
+HEALTH_JSON = {
+    "status": "healthy",
+    "timestamp": "2026-01-01T00:00:00Z",
+}
+
+BATCH_JSON = {
+    "total": 1,
+    "successful": 1,
+    "results": [COMPANY_JSON],
+}
+
+
+def mock_response(status_code: int = 200, json_data: dict | None = None, headers: dict | None = None) -> httpx.Response:
+    response = MagicMock(spec=httpx.Response)
+    response.status_code = status_code
+    response.is_success = 200 <= status_code < 300
+    response.json.return_value = json_data or {}
+    response.headers = headers or {}
+    return response
+
+
+class TestVeriCorp:
+    def test_lookup(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(200, COMPANY_JSON)):
+            result = client.lookup("PT502011378")
+            assert isinstance(result, Company)
+            assert result.name == "UNIVERSIDADE DO MINHO"
+            assert result.country == "PT"
+
+    def test_lookup_gb(self):
+        client = VeriCorp("test-key")
+        gb_json = {**COMPANY_JSON, "tax_id": "GB00445790", "country": "GB", "source": "companies_house"}
+        with patch.object(client._client, "request", return_value=mock_response(200, gb_json)):
+            result = client.lookup_gb("00445790")
+            assert result.source == "companies_house"
+
+    def test_validate(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(200, VALIDATION_JSON)):
+            result = client.validate("PT502011378")
+            assert isinstance(result, ValidationResult)
+            assert result.format_valid is True
+            assert result.vat_valid is True
+
+    def test_batch(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(200, BATCH_JSON)):
+            result = client.batch(["PT502011378"])
+            assert isinstance(result, BatchResponse)
+            assert result.total == 1
+
+    def test_countries(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(200, COUNTRIES_JSON)):
+            result = client.countries()
+            assert isinstance(result, CountriesResponse)
+            assert result.total == 29
+
+    def test_health(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(200, HEALTH_JSON)):
+            result = client.health()
+            assert isinstance(result, HealthResponse)
+            assert result.status == "healthy"
+
+    def test_invalid_tax_id(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(400)):
+            with pytest.raises(InvalidTaxIdError):
+                client.lookup("INVALID")
+
+    def test_not_found(self):
+        client = VeriCorp("test-key")
+        with patch.object(client._client, "request", return_value=mock_response(404)):
+            with pytest.raises(NotFoundError):
+                client.lookup("PT000000000")
+
+    def test_rate_limit(self):
+        client = VeriCorp("test-key", max_retries=0)
+        with patch.object(client._client, "request", return_value=mock_response(429, headers={"Retry-After": "30"})):
+            with pytest.raises(RateLimitError) as exc_info:
+                client.lookup("PT502011378")
+            assert exc_info.value.retry_after == 30
+
+    def test_context_manager(self):
+        with VeriCorp("test-key") as client:
+            assert client._client is not None
+
+    def test_custom_timeout(self):
+        client = VeriCorp("test-key", timeout=5.0)
+        assert client._timeout == 5.0