checkharbor 0.1.0__py3-none-any.whl

checkharbor/__init__.py

@@ -0,0 +1,214 @@
+"""
+Checkharbor Python SDK — single-file, zero-dependency beyond `requests`.
+
+Usage:
+    from checkharbor import Checkharbor, CheckharborError
+
+    client = Checkharbor(api_key="chk_live_...")
+    result = client.validate_email("john@example.com")
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import time
+from typing import Any, Optional, Union
+
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["Checkharbor", "CheckharborError"]
+
+DEFAULT_BASE_URL = "https://api.checkharbor.com"
+
+
+class CheckharborError(Exception):
+    """Raised for any non-2xx response from the Checkharbor API."""
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+    def __repr__(self) -> str:
+        return f"CheckharborError(code={self.code!r}, status={self.status}, message={str(self)!r})"
+
+
+class _BatchNamespace:
+    def __init__(self, client: "Checkharbor") -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        type: str,
+        rows: Optional[list[str]] = None,
+        csv_string: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Create a batch job.
+
+        Args:
+            type: "email", "phone", or "ip"
+            rows: list of values (will be joined as CSV)
+            csv_string: raw CSV content (alternative to rows)
+            webhook_url: optional callback URL when job completes
+        """
+        if csv_string is None and not rows:
+            raise ValueError("batch.create() requires either rows or csv_string")
+
+        content = csv_string if csv_string is not None else "\n".join(rows)  # type: ignore[arg-type]
+
+        files = {"file": ("data.csv", io.BytesIO(content.encode()), "text/csv")}
+        data: dict[str, str] = {"type": type}
+        if webhook_url:
+            data["webhook_url"] = webhook_url
+
+        return self._client._request("POST", "/v1/batch", data=data, files=files)
+
+    def get(self, job_id: str) -> dict[str, Any]:
+        """Fetch the status of a batch job."""
+        return self._client._request("GET", f"/v1/batch/{job_id}")
+
+    def wait_until_done(
+        self,
+        job_id: str,
+        *,
+        poll_seconds: float = 2.0,
+        timeout_seconds: float = 300.0,
+    ) -> dict[str, Any]:
+        """
+        Block until the batch job is done or failed.
+
+        Raises:
+            CheckharborError: if job fails or timeout is exceeded.
+        """
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            job = self.get(job_id)
+            status = job.get("status")
+            if status == "done":
+                return job
+            if status == "failed":
+                raise CheckharborError("batch_failed", f"Batch job {job_id} failed", 200)
+            if time.monotonic() >= deadline:
+                raise CheckharborError(
+                    "timeout",
+                    f"Batch job {job_id} timed out after {timeout_seconds}s",
+                    0,
+                )
+            time.sleep(poll_seconds)
+
+    def download_result(self, job: dict[str, Any]) -> str:
+        """
+        Download result CSV from a completed batch job.
+        The result_url is a signed URL — no auth header needed.
+
+        Returns:
+            CSV content as a string.
+        """
+        if job.get("status") != "done":
+            raise CheckharborError("not_done", "Job is not done yet", 0)
+        result_url = job.get("result_url")
+        if not result_url:
+            raise CheckharborError("no_result_url", "Job has no result_url", 0)
+        resp = requests.get(result_url, timeout=30)
+        if not resp.ok:
+            raise CheckharborError("download_failed", f"Download failed: HTTP {resp.status_code}", resp.status_code)
+        return resp.text
+
+
+class Checkharbor:
+    """
+    Checkharbor API client.
+
+    Args:
+        api_key: Your Checkharbor API key (X-Api-Key header).
+        base_url: Override the default API base URL.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers["X-Api-Key"] = api_key
+        self.batch = _BatchNamespace(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, str]] = None,
+        files: Optional[Any] = None,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        resp = self._session.request(method, url, json=json, data=data, files=files, timeout=30)
+        if not resp.ok:
+            code = "api_error"
+            message = f"HTTP {resp.status_code}"
+            try:
+                body = resp.json()
+                code = body.get("error", {}).get("code", code)
+                message = body.get("error", {}).get("message", message)
+            except Exception:
+                pass
+            raise CheckharborError(code, message, resp.status_code)
+        return resp.json()  # type: ignore[return-value]
+
+    def ping(self) -> dict[str, Any]:
+        """Health check — returns ok + credits_remaining."""
+        return self._request("GET", "/v1/ping")
+
+    def validate_email(self, email: str) -> dict[str, Any]:
+        """Validate a single email address (1 credit)."""
+        return self._request("POST", "/v1/email/validate", json={"email": email})
+
+    def validate_phone(
+        self,
+        phone: str,
+        *,
+        country_hint: Optional[str] = None,
+        hlr: Optional[bool] = None,
+    ) -> dict[str, Any]:
+        """Validate a phone number (1 credit offline, 5 with HLR)."""
+        payload: dict[str, Any] = {"phone": phone}
+        if country_hint is not None:
+            payload["country_hint"] = country_hint
+        if hlr is not None:
+            payload["hlr"] = hlr
+        return self._request("POST", "/v1/phone/validate", json=payload)
+
+    def ip_intel(self, ip: str) -> dict[str, Any]:
+        """IP intelligence lookup (1 credit)."""
+        return self._request("POST", "/v1/ip/intel", json={"ip": ip})
+
+    def verify(
+        self,
+        *,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        ip: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Unified fraud scoring (3 credits).
+        At least one of email, phone, ip is required.
+        """
+        if not any([email, phone, ip]):
+            raise ValueError("verify() requires at least one of: email, phone, ip")
+        payload: dict[str, Any] = {}
+        if email:
+            payload["email"] = email
+        if phone:
+            payload["phone"] = phone
+        if ip:
+            payload["ip"] = ip
+        return self._request("POST", "/v1/verify", json=payload)

checkharbor-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: checkharbor
+Version: 0.1.0
+Summary: Official Checkharbor Python SDK — email/phone/IP validation
+License: MIT
+Project-URL: Homepage, https://checkharbor.com
+Project-URL: Documentation, https://docs.checkharbor.com
+Project-URL: Repository, https://github.com/checkharbor/checkharbor-python
+Keywords: checkharbor,email-validation,phone-validation,ip-intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# checkharbor
+
+Official Checkharbor Python SDK.
+
+## Install
+
+```bash
+pip install checkharbor
+```
+
+## Quick start
+
+```python
+from checkharbor import Checkharbor
+
+client = Checkharbor(api_key="chk_live_...")
+
+# Validate email
+email = client.validate_email("john@example.com")
+print(email["score"], email["deliverability"])
+
+# Validate phone
+phone = client.validate_phone("+905321234567", country_hint="TR")
+
+# IP intelligence
+ip = client.ip_intel("84.17.45.10")
+
+# Unified fraud check
+fraud = client.verify(email="john@example.com", ip="84.17.45.10")
+print(fraud["fraud_score"], fraud["risk"])
+
+# Batch
+job = client.batch.create(
+    type="email",
+    rows=["a@example.com", "b@example.com"],
+    webhook_url="https://myapp.com/webhook",
+)
+done = client.batch.wait_until_done(job["id"])
+csv = client.batch.download_result(done)
+```
+
+## Error handling
+
+```python
+from checkharbor import CheckharborError
+
+try:
+    result = client.validate_email("bad@test.com")
+except CheckharborError as e:
+    print(e.code, e.status, str(e))
+    # e.g. "insufficient_credits" 402 "Not enough credits"
+```
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

checkharbor-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+checkharbor/__init__.py,sha256=065UeTy8x4k_0gAqMEfVTUi1QKSro6Qv_-5rPdi5Io4,7017
+checkharbor-0.1.0.dist-info/METADATA,sha256=jxKXPTC9OJZN5X6Ueupfe2w9zQwfPn9v5lAOzSMjp04,1682
+checkharbor-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+checkharbor-0.1.0.dist-info/top_level.txt,sha256=ow8bI7EGXjUPmDOmOaSE2zy0FIDOaCxK2A-I_gBoBHs,12
+checkharbor-0.1.0.dist-info/RECORD,,

checkharbor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

checkharbor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+checkharbor