checkharbor 0.1.0__tar.gz

checkharbor-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,60 @@
+# 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/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/checkharbor.egg-info/PKG-INFO

@@ -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/checkharbor.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+checkharbor/__init__.py
+checkharbor.egg-info/PKG-INFO
+checkharbor.egg-info/SOURCES.txt
+checkharbor.egg-info/dependency_links.txt
+checkharbor.egg-info/requires.txt
+checkharbor.egg-info/top_level.txt
+tests/test_checkharbor.py

checkharbor-0.1.0/checkharbor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

checkharbor-0.1.0/checkharbor.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

checkharbor-0.1.0/checkharbor.egg-info/top_level.txt

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

checkharbor-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "checkharbor"
+version = "0.1.0"
+description = "Official Checkharbor Python SDK — email/phone/IP validation"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["checkharbor", "email-validation", "phone-validation", "ip-intelligence"]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://checkharbor.com"
+Documentation = "https://docs.checkharbor.com"
+Repository = "https://github.com/checkharbor/checkharbor-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["checkharbor*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

checkharbor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

checkharbor-0.1.0/tests/test_checkharbor.py

@@ -0,0 +1,266 @@
+"""Minimal pytest tests for the Checkharbor Python SDK using unittest.mock."""
+
+from __future__ import annotations
+
+import io
+import time
+from unittest.mock import MagicMock, patch, call
+import pytest
+
+from checkharbor import Checkharbor, CheckharborError
+
+
+# ── fixtures ──────────────────────────────────────────────────────────────────
+
+EMAIL_OK = {
+    "input": "test@example.com",
+    "valid_syntax": True,
+    "score": 90,
+    "credits_used": 1,
+}
+
+PHONE_OK = {
+    "input": "+905321234567",
+    "valid": True,
+    "e164": "+905321234567",
+    "country": "TR",
+    "line_type": "mobile",
+    "credits_used": 1,
+}
+
+IP_OK = {
+    "input": "84.17.45.10",
+    "vpn": False,
+    "proxy": False,
+    "tor": False,
+    "datacenter": False,
+    "abuse_score": 5,
+    "credits_used": 1,
+}
+
+VERIFY_OK = {
+    "fraud_score": 20,
+    "risk": "low",
+    "credits_used": 3,
+}
+
+BATCH_QUEUED = {
+    "id": "job_123",
+    "status": "queued",
+    "type": "email",
+    "total_rows": 3,
+    "processed_rows": 0,
+    "result_url": None,
+}
+
+BATCH_DONE = {
+    **BATCH_QUEUED,
+    "status": "done",
+    "processed_rows": 3,
+    "result_url": "https://cdn.checkharbor.com/results/job_123.csv?sig=abc",
+}
+
+
+def make_response(body: dict, status: int = 200) -> MagicMock:
+    resp = MagicMock()
+    resp.ok = 200 <= status < 300
+    resp.status_code = status
+    resp.json.return_value = body
+    resp.text = "csv,data\na,b"
+    return resp
+
+
+@pytest.fixture
+def client() -> Checkharbor:
+    return Checkharbor(api_key="test-key", base_url="http://localhost:4000")
+
+
+# ── constructor ───────────────────────────────────────────────────────────────
+
+def test_constructor_requires_api_key():
+    with pytest.raises(ValueError, match="api_key is required"):
+        Checkharbor(api_key="")
+
+
+def test_constructor_strips_trailing_slash():
+    c = Checkharbor(api_key="k", base_url="http://localhost:4000/")
+    assert c._base_url == "http://localhost:4000"
+
+
+# ── ping ──────────────────────────────────────────────────────────────────────
+
+def test_ping(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response({"ok": True, "credits_remaining": 500})) as mock:
+        result = client.ping()
+    assert result["ok"] is True
+    assert result["credits_remaining"] == 500
+    mock.assert_called_once_with("GET", "http://localhost:4000/v1/ping", json=None, data=None, files=None, timeout=30)
+
+
+# ── validate_email ────────────────────────────────────────────────────────────
+
+def test_validate_email(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(EMAIL_OK)) as mock:
+        result = client.validate_email("test@example.com")
+    assert result["valid_syntax"] is True
+    assert result["score"] == 90
+    mock.assert_called_once_with(
+        "POST", "http://localhost:4000/v1/email/validate",
+        json={"email": "test@example.com"}, data=None, files=None, timeout=30
+    )
+
+
+# ── validate_phone ────────────────────────────────────────────────────────────
+
+def test_validate_phone_with_options(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(PHONE_OK)) as mock:
+        result = client.validate_phone("+905321234567", country_hint="TR", hlr=False)
+    assert result["valid"] is True
+    mock.assert_called_once_with(
+        "POST", "http://localhost:4000/v1/phone/validate",
+        json={"phone": "+905321234567", "country_hint": "TR", "hlr": False},
+        data=None, files=None, timeout=30
+    )
+
+
+def test_validate_phone_minimal(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(PHONE_OK)) as mock:
+        client.validate_phone("+905321234567")
+    called_json = mock.call_args.kwargs["json"]
+    assert called_json == {"phone": "+905321234567"}
+
+
+# ── ip_intel ──────────────────────────────────────────────────────────────────
+
+def test_ip_intel(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(IP_OK)):
+        result = client.ip_intel("84.17.45.10")
+    assert result["input"] == "84.17.45.10"
+    assert result["credits_used"] == 1
+
+
+# ── verify ────────────────────────────────────────────────────────────────────
+
+def test_verify(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(VERIFY_OK)) as mock:
+        result = client.verify(email="test@example.com", ip="1.2.3.4")
+    assert result["fraud_score"] == 20
+    assert result["risk"] == "low"
+
+
+def test_verify_requires_at_least_one_field(client: Checkharbor):
+    with pytest.raises(ValueError, match="at least one of"):
+        client.verify()
+
+
+# ── batch ─────────────────────────────────────────────────────────────────────
+
+def test_batch_create_with_rows(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(BATCH_QUEUED, 202)) as mock:
+        job = client.batch.create(
+            type="email",
+            rows=["a@example.com", "b@example.com", "c@example.com"],
+        )
+    assert job["id"] == "job_123"
+    assert job["status"] == "queued"
+    # Confirm multipart call (data + files, no json)
+    call_kwargs = mock.call_args.kwargs
+    assert call_kwargs["json"] is None
+    assert call_kwargs["data"] == {"type": "email"}
+    assert "file" in call_kwargs["files"]
+
+
+def test_batch_create_with_csv_string(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(BATCH_QUEUED, 202)) as mock:
+        client.batch.create(type="email", csv_string="a@b.com\nc@d.com")
+    call_kwargs = mock.call_args.kwargs
+    assert call_kwargs["data"] == {"type": "email"}
+
+
+def test_batch_create_raises_without_data(client: Checkharbor):
+    with pytest.raises(ValueError, match="rows or csv_string"):
+        client.batch.create(type="email")
+
+
+def test_batch_get(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(BATCH_DONE)) as mock:
+        job = client.batch.get("job_123")
+    assert job["status"] == "done"
+    mock.assert_called_once_with(
+        "GET", "http://localhost:4000/v1/batch/job_123",
+        json=None, data=None, files=None, timeout=30
+    )
+
+
+def test_batch_wait_until_done_polls(client: Checkharbor):
+    responses = [
+        make_response(BATCH_QUEUED),
+        make_response({**BATCH_QUEUED, "status": "processing"}),
+        make_response(BATCH_DONE),
+    ]
+    with patch.object(client._session, "request", side_effect=responses):
+        with patch("time.sleep"):  # don't actually sleep
+            job = client.batch.wait_until_done("job_123", poll_seconds=0.001)
+    assert job["status"] == "done"
+
+
+def test_batch_wait_until_done_fails(client: Checkharbor):
+    failed = {**BATCH_QUEUED, "status": "failed"}
+    with patch.object(client._session, "request", return_value=make_response(failed)):
+        with pytest.raises(CheckharborError) as exc_info:
+            client.batch.wait_until_done("job_123", poll_seconds=0.001)
+    assert exc_info.value.code == "batch_failed"
+
+
+def test_batch_wait_until_done_timeout(client: Checkharbor):
+    with patch.object(client._session, "request", return_value=make_response(BATCH_QUEUED)):
+        with patch("time.sleep"):
+            with patch("time.monotonic", side_effect=[0.0, 0.0, 1000.0]):
+                with pytest.raises(CheckharborError) as exc_info:
+                    client.batch.wait_until_done("job_123", poll_seconds=0.001, timeout_seconds=1.0)
+    assert exc_info.value.code == "timeout"
+
+
+def test_batch_download_result(client: Checkharbor):
+    csv_content = "email,valid\na@b.com,true"
+    download_resp = MagicMock()
+    download_resp.ok = True
+    download_resp.status_code = 200
+    download_resp.text = csv_content
+
+    with patch("requests.get", return_value=download_resp) as mock_get:
+        result = client.batch.download_result(BATCH_DONE)
+    assert result == csv_content
+    mock_get.assert_called_once_with(BATCH_DONE["result_url"], timeout=30)
+
+
+def test_batch_download_result_raises_if_not_done(client: Checkharbor):
+    with pytest.raises(CheckharborError) as exc_info:
+        client.batch.download_result(BATCH_QUEUED)
+    assert exc_info.value.code == "not_done"
+
+
+# ── error handling ────────────────────────────────────────────────────────────
+
+def test_raises_checkharbor_error_on_402(client: Checkharbor):
+    err_resp = make_response(
+        {"error": {"code": "insufficient_credits", "message": "Not enough credits"}},
+        status=402,
+    )
+    with patch.object(client._session, "request", return_value=err_resp):
+        with pytest.raises(CheckharborError) as exc_info:
+            client.validate_email("x@y.com")
+    assert exc_info.value.code == "insufficient_credits"
+    assert exc_info.value.status == 402
+
+
+def test_raises_checkharbor_error_on_429(client: Checkharbor):
+    err_resp = make_response(
+        {"error": {"code": "rate_limited", "message": "Too many requests"}},
+        status=429,
+    )
+    with patch.object(client._session, "request", return_value=err_resp):
+        with pytest.raises(CheckharborError) as exc_info:
+            client.ip_intel("1.2.3.4")
+    assert exc_info.value.code == "rate_limited"
+    assert exc_info.value.status == 429