apiddress 0.1.0__tar.gz

apiddress-0.1.0/.gitignore

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

apiddress-0.1.0/LICENSE

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

apiddress-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: apiddress
+Version: 0.1.0
+Summary: Official Python SDK for the APIddress email validation API
+Project-URL: Homepage, https://api.apiddress.com
+Author: APIddress
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apiddress,email,email-verification,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# apiddress
+
+Official Python SDK for the [APIddress](https://api.apiddress.com) email validation API.
+
+- Zero runtime dependencies (stdlib `urllib` only)
+- Python 3.9+, fully type-hinted, frozen dataclass responses
+- Automatic retry with backoff on `429` and `5xx` (batch creation is never retried)
+
+## Install
+
+```bash
+pip install apiddress
+```
+
+## Quickstart
+
+```python
+from apiddress import Client
+
+client = Client("YOUR_API_KEY")
+
+result = client.validate_email("ada@stripe.com")
+print(result.status)  # "valid"
+print(result.score)   # 0.98
+```
+
+## Configuration
+
+```python
+client = Client(
+    "YOUR_API_KEY",
+    base_url="https://api.apiddress.com",  # default
+    timeout=10.0,                          # per-request timeout (seconds), default 10
+    max_retries=2,                         # retries on 429/5xx, default 2
+)
+```
+
+## Usage
+
+### Validate one email
+
+```python
+result = client.validate_email(
+    "john@company.com",
+    check_smtp=False,        # default
+    allow_role_based=True,   # server default
+)
+# result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
+# result.suggestion: "john@gmail.com" for typo-like addresses, else None
+# result.checks: ValidationChecks(syntax, domain_exists, mx, smtp, disposable, ...)
+```
+
+A malformed value (e.g. `"not-an-email"`) is a verdict, not an error: you get
+`status == "invalid"` with `reason == "invalid_syntax"`.
+
+### Validate up to 100 emails synchronously
+
+```python
+response = client.validate_emails(["a@example.com", "b@example.com"])
+print(response.count, [r.status for r in response.results])
+```
+
+### Batch jobs (up to 5000 emails)
+
+```python
+batch = client.create_batch(
+    emails,
+    callback_url="https://yourapp.com/webhooks/apiddress",  # optional
+)
+
+done = client.wait_for_batch(
+    batch.batch_id,
+    poll_interval=1.0,  # default
+    timeout=60.0,       # default
+)
+print(done.status, len(done.results))
+
+# Or poll yourself:
+status = client.get_batch(batch.batch_id)
+```
+
+`wait_for_batch` returns the terminal state (`"completed"` or `"failed"`) —
+check `status` before using `results`.
+
+### Account
+
+```python
+profile = client.me()         # plan, limits, usage
+usage = client.usage()        # current month
+may = client.usage("2026-05") # specific month
+health = client.health()      # no auth required
+```
+
+## Error handling
+
+Every failed request raises an `APIddressError`:
+
+```python
+from apiddress import APIddressError, Client
+
+try:
+    client.validate_email("john@company.com")
+except APIddressError as err:
+    print(err.status, err.code, err.message, err.details)
+    # 429 quota_exceeded "Monthly request limit exceeded." {"requests_used": ..., "requests_limit": ...}
+```
+
+| `status` | `code` |
+| -------- | ------------------ |
+| 400 | `invalid_request` |
+| 401 | `unauthorized` |
+| 404 | `not_found` |
+| 429 | `quota_exceeded` |
+| 500 | `internal_error` |
+| 0 | `timeout` (request or `wait_for_batch` timeout) |
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e . pytest
+
+# Integration tests need a live backend:
+APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev \
+  .venv/bin/pytest
+```
+
+## License
+
+MIT

apiddress-0.1.0/README.md

@@ -0,0 +1,130 @@
+# apiddress
+
+Official Python SDK for the [APIddress](https://api.apiddress.com) email validation API.
+
+- Zero runtime dependencies (stdlib `urllib` only)
+- Python 3.9+, fully type-hinted, frozen dataclass responses
+- Automatic retry with backoff on `429` and `5xx` (batch creation is never retried)
+
+## Install
+
+```bash
+pip install apiddress
+```
+
+## Quickstart
+
+```python
+from apiddress import Client
+
+client = Client("YOUR_API_KEY")
+
+result = client.validate_email("ada@stripe.com")
+print(result.status)  # "valid"
+print(result.score)   # 0.98
+```
+
+## Configuration
+
+```python
+client = Client(
+    "YOUR_API_KEY",
+    base_url="https://api.apiddress.com",  # default
+    timeout=10.0,                          # per-request timeout (seconds), default 10
+    max_retries=2,                         # retries on 429/5xx, default 2
+)
+```
+
+## Usage
+
+### Validate one email
+
+```python
+result = client.validate_email(
+    "john@company.com",
+    check_smtp=False,        # default
+    allow_role_based=True,   # server default
+)
+# result.status: "valid" | "invalid" | "risky" | "disposable" | "unknown"
+# result.suggestion: "john@gmail.com" for typo-like addresses, else None
+# result.checks: ValidationChecks(syntax, domain_exists, mx, smtp, disposable, ...)
+```
+
+A malformed value (e.g. `"not-an-email"`) is a verdict, not an error: you get
+`status == "invalid"` with `reason == "invalid_syntax"`.
+
+### Validate up to 100 emails synchronously
+
+```python
+response = client.validate_emails(["a@example.com", "b@example.com"])
+print(response.count, [r.status for r in response.results])
+```
+
+### Batch jobs (up to 5000 emails)
+
+```python
+batch = client.create_batch(
+    emails,
+    callback_url="https://yourapp.com/webhooks/apiddress",  # optional
+)
+
+done = client.wait_for_batch(
+    batch.batch_id,
+    poll_interval=1.0,  # default
+    timeout=60.0,       # default
+)
+print(done.status, len(done.results))
+
+# Or poll yourself:
+status = client.get_batch(batch.batch_id)
+```
+
+`wait_for_batch` returns the terminal state (`"completed"` or `"failed"`) —
+check `status` before using `results`.
+
+### Account
+
+```python
+profile = client.me()         # plan, limits, usage
+usage = client.usage()        # current month
+may = client.usage("2026-05") # specific month
+health = client.health()      # no auth required
+```
+
+## Error handling
+
+Every failed request raises an `APIddressError`:
+
+```python
+from apiddress import APIddressError, Client
+
+try:
+    client.validate_email("john@company.com")
+except APIddressError as err:
+    print(err.status, err.code, err.message, err.details)
+    # 429 quota_exceeded "Monthly request limit exceeded." {"requests_used": ..., "requests_limit": ...}
+```
+
+| `status` | `code` |
+| -------- | ------------------ |
+| 400 | `invalid_request` |
+| 401 | `unauthorized` |
+| 404 | `not_found` |
+| 429 | `quota_exceeded` |
+| 500 | `internal_error` |
+| 0 | `timeout` (request or `wait_for_batch` timeout) |
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e . pytest
+
+# Integration tests need a live backend:
+APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev \
+  .venv/bin/pytest
+```
+
+## License
+
+MIT

apiddress-0.1.0/apiddress/__init__.py

@@ -0,0 +1,30 @@
+"""Official Python SDK for the APIddress email validation API."""
+
+from .client import Client
+from .errors import APIddressError
+from .models import (
+    ApiKeyProfileResponse,
+    BatchAcceptedResponse,
+    BatchStatusResponse,
+    BulkValidateResponse,
+    HealthResponse,
+    UsageResponse,
+    ValidateEmailResponse,
+    ValidationChecks,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "APIddressError",
+    "ApiKeyProfileResponse",
+    "BatchAcceptedResponse",
+    "BatchStatusResponse",
+    "BulkValidateResponse",
+    "HealthResponse",
+    "UsageResponse",
+    "ValidateEmailResponse",
+    "ValidationChecks",
+    "__version__",
+]

apiddress-0.1.0/apiddress/client.py

@@ -0,0 +1,228 @@
+"""Official APIddress client (stdlib-only, Python 3.9+)."""
+
+import json
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .errors import APIddressError
+from .models import (
+    ApiKeyProfileResponse,
+    BatchAcceptedResponse,
+    BatchStatusResponse,
+    BulkValidateResponse,
+    HealthResponse,
+    UsageResponse,
+    ValidateEmailResponse,
+)
+
+__all__ = ["Client"]
+
+DEFAULT_BASE_URL = "https://api.apiddress.com"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 2
+
+_TERMINAL_BATCH_STATUSES = ("completed", "failed")
+
+
+class Client:
+    """APIddress email validation client.
+
+    >>> from apiddress import Client
+    >>> client = Client("YOUR_API_KEY")
+    >>> result = client.validate_email("ada@stripe.com")
+    >>> result.status
+    'valid'
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        :param api_key: Your APIddress API key (sent as ``x-api-key``).
+        :param base_url: API origin. Defaults to production.
+        :param timeout: Per-request timeout in seconds. Default 10.
+        :param max_retries: Retries on 429/5xx. Default 2.
+            Batch creation is never retried.
+        """
+        if not api_key or not isinstance(api_key, str):
+            raise TypeError("apiddress.Client: an API key string is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    # -- Validation ----------------------------------------------------------
+
+    def validate_email(
+        self,
+        email: str,
+        check_smtp: bool = False,
+        allow_role_based: Optional[bool] = None,
+    ) -> ValidateEmailResponse:
+        """Validate a single email address. Costs 1 request."""
+        body: Dict[str, Any] = {"email": email, "check_smtp": check_smtp}
+        if allow_role_based is not None:
+            body["allow_role_based"] = allow_role_based
+        data = self._request("POST", "/api/v1/validate-email", body=body)
+        return ValidateEmailResponse.from_dict(data)
+
+    def validate_emails(
+        self,
+        emails: List[str],
+        check_smtp: bool = False,
+    ) -> BulkValidateResponse:
+        """Validate 1-100 email addresses synchronously. Costs one request per email."""
+        data = self._request(
+            "POST",
+            "/api/v1/validate-emails",
+            body={"emails": emails, "check_smtp": check_smtp},
+        )
+        return BulkValidateResponse.from_dict(data)
+
+    def create_batch(
+        self,
+        emails: List[str],
+        callback_url: Optional[str] = None,
+        check_smtp: bool = False,
+    ) -> BatchAcceptedResponse:
+        """Create an asynchronous batch job for 1-5000 email addresses.
+
+        Never retried automatically (to avoid duplicate jobs).
+        """
+        body: Dict[str, Any] = {"emails": emails, "check_smtp": check_smtp}
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        data = self._request("POST", "/api/v1/batches", body=body, retryable=False)
+        return BatchAcceptedResponse.from_dict(data)
+
+    def get_batch(self, batch_id: str) -> BatchStatusResponse:
+        """Get the current state (and results, when completed) of a batch job."""
+        data = self._request(
+            "GET", "/api/v1/batches/" + urllib.parse.quote(batch_id, safe="")
+        )
+        return BatchStatusResponse.from_dict(data)
+
+    def wait_for_batch(
+        self,
+        batch_id: str,
+        poll_interval: float = 1.0,
+        timeout: float = 60.0,
+    ) -> BatchStatusResponse:
+        """Poll a batch job until it reaches a terminal state.
+
+        Returns the final state (``status`` is ``"completed"`` or ``"failed"``).
+        Raises :class:`APIddressError` with ``code="timeout"`` if the job is
+        still running after ``timeout`` seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            batch = self.get_batch(batch_id)
+            if batch.status in _TERMINAL_BATCH_STATUSES:
+                return batch
+            if time.monotonic() + poll_interval > deadline:
+                raise APIddressError(
+                    0,
+                    "timeout",
+                    f"Batch {batch_id} did not complete within {timeout}s "
+                    f"(last status: {batch.status})",
+                )
+            time.sleep(poll_interval)
+
+    # -- Account -------------------------------------------------------------
+
+    def me(self) -> ApiKeyProfileResponse:
+        """Get the profile (plan, limits, usage) of the authenticated API key."""
+        return ApiKeyProfileResponse.from_dict(self._request("GET", "/api/v1/me"))
+
+    def usage(self, month: Optional[str] = None) -> UsageResponse:
+        """Get usage for a month ("YYYY-MM"). Defaults to the current month."""
+        query = {"month": month} if month is not None else None
+        return UsageResponse.from_dict(
+            self._request("GET", "/api/v1/usage", query=query)
+        )
+
+    def health(self) -> HealthResponse:
+        """Service health check. Does not require authentication."""
+        return HealthResponse.from_dict(
+            self._request("GET", "/api/v1/health", auth=False)
+        )
+
+    # -- Transport -----------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, str]] = None,
+        auth: bool = True,
+        retryable: bool = True,
+    ) -> Dict[str, Any]:
+        url = self._base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        headers = {"accept": "application/json"}
+        if auth:
+            headers["x-api-key"] = self._api_key
+
+        data: Optional[bytes] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["content-type"] = "application/json"
+
+        max_attempts = self._max_retries + 1 if retryable else 1
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                    return json.loads(response.read().decode("utf-8"))
+            except urllib.error.HTTPError as http_error:
+                error = _parse_error_envelope(http_error)
+                should_retry = attempt + 1 < max_attempts and (
+                    http_error.code == 429 or http_error.code >= 500
+                )
+                if not should_retry:
+                    raise error from None
+            except urllib.error.URLError as url_error:
+                if isinstance(url_error.reason, (socket.timeout, TimeoutError)):
+                    raise APIddressError(
+                        0, "timeout", f"Request to {path} timed out after {self._timeout}s"
+                    ) from None
+                raise
+            except (socket.timeout, TimeoutError):
+                raise APIddressError(
+                    0, "timeout", f"Request to {path} timed out after {self._timeout}s"
+                ) from None
+            time.sleep(_backoff_seconds(attempt))
+            attempt += 1
+
+
+def _backoff_seconds(attempt: int) -> float:
+    """Exponential backoff with a little jitter: ~0.25s, ~0.5s, ~1s, capped at 4s."""
+    return min(0.25 * (2 ** attempt), 4.0) + random.random() * 0.1
+
+
+def _parse_error_envelope(http_error: urllib.error.HTTPError) -> APIddressError:
+    code = "unknown_error"
+    message = f"HTTP {http_error.code}"
+    details: Optional[Dict[str, Any]] = None
+    try:
+        payload = json.loads(http_error.read().decode("utf-8"))
+        envelope = payload.get("error") or {}
+        code = envelope.get("code", code)
+        message = envelope.get("message", message)
+        details = envelope.get("details")
+    except (ValueError, UnicodeDecodeError):
+        pass  # Non-JSON error body; keep defaults.
+    return APIddressError(http_error.code, code, message, details)

apiddress-0.1.0/apiddress/errors.py

@@ -0,0 +1,40 @@
+"""Error type for the APIddress SDK."""
+
+from typing import Any, Dict, Optional
+
+__all__ = ["APIddressError"]
+
+
+class APIddressError(Exception):
+    """Raised for any failed APIddress request.
+
+    For HTTP errors, ``status`` is the response status code and ``code`` /
+    ``message`` / ``details`` come from the API error envelope
+    ``{"error": {"code", "message", "details"}}``.
+
+    For client-side failures (request timeout, batch polling timeout),
+    ``status`` is 0 and ``code`` is ``"timeout"``.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        #: HTTP status code, or 0 for client-side failures.
+        self.status = status
+        #: Machine-readable error code, e.g. "unauthorized", "quota_exceeded".
+        self.code = code
+        #: Human-readable message.
+        self.message = message
+        #: Extra context from the API, or None.
+        self.details = details
+
+    def __repr__(self) -> str:
+        return (
+            f"APIddressError(status={self.status!r}, code={self.code!r}, "
+            f"message={self.message!r}, details={self.details!r})"
+        )

apiddress-0.1.0/apiddress/models.py

@@ -0,0 +1,218 @@
+"""Response models for the APIddress API.
+
+Hand-mapped 1:1 from the OpenAPI 3.1 contract (``backend/openapi.yaml``).
+Attribute names match the wire format exactly.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+__all__ = [
+    "ValidationChecks",
+    "ValidateEmailResponse",
+    "BulkValidateResponse",
+    "BatchAcceptedResponse",
+    "BatchStatusResponse",
+    "ApiKeyProfileResponse",
+    "UsageResponse",
+    "HealthResponse",
+]
+
+
+@dataclass(frozen=True)
+class ValidationChecks:
+    """Individual checks performed on an email address."""
+
+    syntax: bool
+    domain_exists: bool
+    mx: bool
+    #: None when the SMTP probe was skipped or inconclusive.
+    smtp: Optional[bool]
+    disposable: bool
+    role_based: bool
+    free_provider: bool
+    #: None when not determined.
+    catch_all: Optional[bool]
+    typo: bool
+    #: "low" | "medium" | "high" | None
+    spam_trap_risk: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ValidationChecks":
+        return cls(
+            syntax=data["syntax"],
+            domain_exists=data["domain_exists"],
+            mx=data["mx"],
+            smtp=data["smtp"],
+            disposable=data["disposable"],
+            role_based=data["role_based"],
+            free_provider=data["free_provider"],
+            catch_all=data["catch_all"],
+            typo=data["typo"],
+            spam_trap_risk=data["spam_trap_risk"],
+        )
+
+
+@dataclass(frozen=True)
+class ValidateEmailResponse:
+    """Result of validating a single email address."""
+
+    email: str
+    normalized_email: str
+    #: "valid" | "invalid" | "risky" | "disposable" | "unknown"
+    status: str
+    valid: bool
+    #: Confidence score between 0 and 1.
+    score: float
+    #: Machine-readable reason, e.g. "accepted_email", "invalid_syntax".
+    reason: str
+    #: Suggested correction for typo-like addresses, or None.
+    suggestion: Optional[str]
+    checks: ValidationChecks
+    provider: Optional[str]
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ValidateEmailResponse":
+        return cls(
+            email=data["email"],
+            normalized_email=data["normalized_email"],
+            status=data["status"],
+            valid=data["valid"],
+            score=data["score"],
+            reason=data["reason"],
+            suggestion=data["suggestion"],
+            checks=ValidationChecks.from_dict(data["checks"]),
+            provider=data["provider"],
+            created_at=data["created_at"],
+        )
+
+
+@dataclass(frozen=True)
+class BulkValidateResponse:
+    """Result of a synchronous bulk validation."""
+
+    count: int
+    results: List[ValidateEmailResponse]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BulkValidateResponse":
+        return cls(
+            count=data["count"],
+            results=[ValidateEmailResponse.from_dict(item) for item in data["results"]],
+        )
+
+
+@dataclass(frozen=True)
+class BatchAcceptedResponse:
+    """Returned when an asynchronous batch job is accepted (HTTP 202)."""
+
+    batch_id: str
+    #: Always "pending" on acceptance.
+    status: str
+    submitted_count: int
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchAcceptedResponse":
+        return cls(
+            batch_id=data["batch_id"],
+            status=data["status"],
+            submitted_count=data["submitted_count"],
+            created_at=data["created_at"],
+        )
+
+
+@dataclass(frozen=True)
+class BatchStatusResponse:
+    """Current state of an asynchronous batch job."""
+
+    batch_id: str
+    #: "pending" | "processing" | "completed" | "failed"
+    status: str
+    submitted_count: int
+    processed_count: int
+    created_at: str
+    completed_at: Optional[str]
+    #: Per-email results once the batch is completed, otherwise None.
+    results: Optional[List[ValidateEmailResponse]]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchStatusResponse":
+        raw_results = data["results"]
+        return cls(
+            batch_id=data["batch_id"],
+            status=data["status"],
+            submitted_count=data["submitted_count"],
+            processed_count=data["processed_count"],
+            created_at=data["created_at"],
+            completed_at=data["completed_at"],
+            results=(
+                None
+                if raw_results is None
+                else [ValidateEmailResponse.from_dict(item) for item in raw_results]
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class ApiKeyProfileResponse:
+    """Profile of the authenticated API key."""
+
+    id: str
+    email: str
+    #: "free" | "paid" | "enterprise"
+    plan: str
+    is_active: bool
+    requests_limit: int
+    requests_used: int
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ApiKeyProfileResponse":
+        return cls(
+            id=data["id"],
+            email=data["email"],
+            plan=data["plan"],
+            is_active=data["is_active"],
+            requests_limit=data["requests_limit"],
+            requests_used=data["requests_used"],
+            created_at=data["created_at"],
+        )
+
+
+@dataclass(frozen=True)
+class UsageResponse:
+    """Monthly usage for the authenticated API key."""
+
+    #: Month in YYYY-MM format.
+    month: str
+    requests_used: int
+    requests_limit: int
+    remaining: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "UsageResponse":
+        return cls(
+            month=data["month"],
+            requests_used=data["requests_used"],
+            requests_limit=data["requests_limit"],
+            remaining=data["remaining"],
+        )
+
+
+@dataclass(frozen=True)
+class HealthResponse:
+    """Service health payload."""
+
+    status: str
+    timestamp: str
+    version: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "HealthResponse":
+        return cls(
+            status=data["status"],
+            timestamp=data["timestamp"],
+            version=data["version"],
+        )

apiddress-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apiddress"
+version = "0.1.0"
+description = "Official Python SDK for the APIddress email validation API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "APIddress" }]
+keywords = ["email", "validation", "email-verification", "apiddress"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Email",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://api.apiddress.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["apiddress"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

apiddress-0.1.0/tests/test_integration.py

@@ -0,0 +1,130 @@
+"""Integration tests against a live APIddress backend.
+
+    APIDDRESS_BASE_URL=http://localhost:3000 APIDDRESS_API_KEY=test_key_local_dev pytest
+
+Quota cost of this suite: 9 validations
+(4 single + 3 bulk + 2 batch; me/usage/health/errors are free).
+"""
+
+import os
+import re
+
+import pytest
+
+from apiddress import APIddressError, Client
+
+BASE_URL = os.environ.get("APIDDRESS_BASE_URL", "http://localhost:3000")
+API_KEY = os.environ.get("APIDDRESS_API_KEY", "test_key_local_dev")
+
+
+@pytest.fixture(scope="module")
+def client() -> Client:
+    return Client(API_KEY, base_url=BASE_URL)
+
+
+class TestHealth:
+    def test_health_without_auth(self, client: Client) -> None:
+        health = client.health()
+        assert health.status == "ok"
+        assert isinstance(health.version, str)
+        assert isinstance(health.timestamp, str)
+
+
+class TestValidateEmail:
+    def test_valid_corporate_address(self, client: Client) -> None:
+        result = client.validate_email("ada@stripe.com")
+        assert result.status == "valid"
+        assert result.valid is True
+        assert result.email == "ada@stripe.com"
+        assert result.normalized_email == "ada@stripe.com"
+        assert result.score > 0.5
+        assert result.checks.syntax is True
+        assert result.checks.mx is True
+        assert result.checks.disposable is False
+        # check_smtp defaults to False, so the probe must be skipped.
+        assert result.checks.smtp is None
+
+    def test_disposable_address(self, client: Client) -> None:
+        result = client.validate_email("temp@mailinator.com")
+        assert result.status == "disposable"
+        assert result.valid is False
+        assert result.checks.disposable is True
+
+    def test_typo_suggestion(self, client: Client) -> None:
+        result = client.validate_email("jane@gmial.com")
+        assert result.checks.typo is True
+        assert result.suggestion == "jane@gmail.com"
+
+    def test_malformed_is_a_verdict_not_an_error(self, client: Client) -> None:
+        result = client.validate_email("not-an-email")
+        assert result.status == "invalid"
+        assert result.valid is False
+        assert result.reason == "invalid_syntax"
+        assert result.checks.syntax is False
+
+
+class TestValidateEmails:
+    def test_bulk_of_three(self, client: Client) -> None:
+        response = client.validate_emails(
+            ["ada@stripe.com", "temp@mailinator.com", "nope"]
+        )
+        assert response.count == 3
+        assert len(response.results) == 3
+        assert [r.status for r in response.results] == [
+            "valid",
+            "disposable",
+            "invalid",
+        ]
+
+
+class TestBatches:
+    def test_batch_lifecycle(self, client: Client) -> None:
+        accepted = client.create_batch(["ada@stripe.com", "temp@mailinator.com"])
+        assert accepted.status == "pending"
+        assert accepted.submitted_count == 2
+        assert len(accepted.batch_id) >= 8
+
+        done = client.wait_for_batch(accepted.batch_id, poll_interval=0.5, timeout=20.0)
+        assert done.status == "completed"
+        assert done.batch_id == accepted.batch_id
+        assert done.processed_count == 2
+        assert done.completed_at is not None
+        assert done.results is not None and len(done.results) == 2
+        assert done.results[0].status == "valid"
+
+    def test_unknown_batch_is_404(self, client: Client) -> None:
+        with pytest.raises(APIddressError) as excinfo:
+            client.get_batch("does-not-exist-123")
+        assert excinfo.value.status == 404
+        assert excinfo.value.code == "not_found"
+
+
+class TestAccount:
+    def test_me(self, client: Client) -> None:
+        profile = client.me()
+        assert profile.is_active is True
+        assert profile.plan in ("free", "paid", "enterprise")
+        assert profile.requests_limit > 0
+        assert profile.requests_used >= 0
+
+    def test_usage_current_month(self, client: Client) -> None:
+        usage = client.usage()
+        assert re.fullmatch(r"\d{4}-(0[1-9]|1[0-2])", usage.month)
+        assert usage.remaining == usage.requests_limit - usage.requests_used
+
+
+class TestErrors:
+    def test_bad_api_key_is_401(self) -> None:
+        bad = Client("definitely_not_a_key", base_url=BASE_URL)
+        with pytest.raises(APIddressError) as excinfo:
+            bad.me()
+        assert excinfo.value.status == 401
+        assert excinfo.value.code == "unauthorized"
+        assert len(excinfo.value.message) > 0
+
+    def test_400_error_envelope_mapping(self, client: Client) -> None:
+        with pytest.raises(APIddressError) as excinfo:
+            client.validate_emails([])
+        assert excinfo.value.status == 400
+        assert excinfo.value.code == "invalid_request"
+        assert isinstance(excinfo.value.message, str)