veqen 0.1.0__tar.gz

veqen-0.1.0/LICENSE

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

veqen-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: veqen
+Version: 0.1.0
+Summary: Official Python client for the Veqen signup-check API: disposable emails, datacenter IPs, VoIP numbers and more.
+License-Expression: MIT
+Project-URL: Homepage, https://veqen-app.com
+Project-URL: Documentation, https://veqen-app.com/docs
+Project-URL: Source, https://github.com/Keyveve/veqen-sdks/tree/main/python
+Project-URL: Issues, https://github.com/Keyveve/veqen-sdks/issues
+Keywords: email validation,disposable email,fraud,signup,ip lookup,phone validation,vpn detection
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: certifi>=2026.10.19
+Dynamic: license-file
+
+# veqen (Python)
+
+Official Python client for [Veqen](https://veqen-app.com): catch disposable emails, typos, datacenter and Tor IPs, and VoIP numbers with one API call.
+
+```bash
+pip install https://veqen-app.com/static/sdk/veqen-0.1.0-py3-none-any.whl
+```
+
+```python
+from veqen import Veqen, VeqenError
+
+client = Veqen()  # reads VEQEN_API_KEY from the environment
+
+result = client.signup(email="jane@mailinator.com", ip="185.220.101.1")
+print(result["risk"]["verdict"])        # "refuse"
+for reason in result["risk"]["reasons"]:
+    print(reason["code"], reason["message"])
+```
+
+| Method | Endpoint | Credits |
+|---|---|---|
+| `email(address, verify_mailbox=False)` | `/v1/email/check` | 1 (+5) |
+| `emails(list)` | `/v1/email/batch` (chunks of 100) | 1 each |
+| `ip(address)` | `/v1/ip/check` | 1 |
+| `phone(number, country=None)` | `/v1/phone/check` | 1 |
+| `domain(name)` | `/v1/domain/check` | 1 |
+| `signup(email=, ip=, phone=, phone_country=)` | `/v1/signup/check` | 3 |
+| `account()`, `usage(days=30)` | `/v1/account`, `/v1/usage` | 0 |
+
+Errors raise `VeqenError` with `.status`, `.type` (e.g. `insufficient_credits`) and `.message`. Requests are retried on 429 and 5xx. Docs: https://veqen-app.com/docs

veqen-0.1.0/README.md

@@ -0,0 +1,30 @@
+# veqen (Python)
+
+Official Python client for [Veqen](https://veqen-app.com): catch disposable emails, typos, datacenter and Tor IPs, and VoIP numbers with one API call.
+
+```bash
+pip install https://veqen-app.com/static/sdk/veqen-0.1.0-py3-none-any.whl
+```
+
+```python
+from veqen import Veqen, VeqenError
+
+client = Veqen()  # reads VEQEN_API_KEY from the environment
+
+result = client.signup(email="jane@mailinator.com", ip="185.220.101.1")
+print(result["risk"]["verdict"])        # "refuse"
+for reason in result["risk"]["reasons"]:
+    print(reason["code"], reason["message"])
+```
+
+| Method | Endpoint | Credits |
+|---|---|---|
+| `email(address, verify_mailbox=False)` | `/v1/email/check` | 1 (+5) |
+| `emails(list)` | `/v1/email/batch` (chunks of 100) | 1 each |
+| `ip(address)` | `/v1/ip/check` | 1 |
+| `phone(number, country=None)` | `/v1/phone/check` | 1 |
+| `domain(name)` | `/v1/domain/check` | 1 |
+| `signup(email=, ip=, phone=, phone_country=)` | `/v1/signup/check` | 3 |
+| `account()`, `usage(days=30)` | `/v1/account`, `/v1/usage` | 0 |
+
+Errors raise `VeqenError` with `.status`, `.type` (e.g. `insufficient_credits`) and `.message`. Requests are retried on 429 and 5xx. Docs: https://veqen-app.com/docs

veqen-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "veqen"
+version = "0.1.0"
+description = "Official Python client for the Veqen signup-check API: disposable emails, datacenter IPs, VoIP numbers and more."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.25", "certifi>=2026.10.19"]
+keywords = ["email validation", "disposable email", "fraud", "signup", "ip lookup", "phone validation", "vpn detection"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://veqen-app.com"
+Documentation = "https://veqen-app.com/docs"
+Source = "https://github.com/Keyveve/veqen-sdks/tree/main/python"
+Issues = "https://github.com/Keyveve/veqen-sdks/issues"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["veqen"]

veqen-0.1.0/setup.cfg

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

veqen-0.1.0/tests/test_client.py

@@ -0,0 +1,90 @@
+import json
+
+import httpx
+import pytest
+
+from veqen import Veqen, VeqenError
+
+
+def make(handler, **kwargs):
+    return Veqen("vq_live_test", base_url="https://api.test", transport=httpx.MockTransport(handler), **kwargs)
+
+
+def test_signup_sends_auth_and_drops_empty_fields():
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers["Authorization"]
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json={"risk": {"verdict": "refuse"}})
+
+    result = make(handler).signup(email="a@b.com", ip="1.2.3.4")
+    assert result["risk"]["verdict"] == "refuse"
+    assert seen == {"auth": "Bearer vq_live_test", "path": "/v1/signup/check", "body": {"email": "a@b.com", "ip": "1.2.3.4", "verify_mailbox": False}}
+
+
+def test_errors_raise_with_type():
+    def handler(request):
+        return httpx.Response(402, json={"error": {"type": "insufficient_credits", "message": "Buy credits"}}, headers={"X-Request-Id": "r1"})
+
+    with pytest.raises(VeqenError) as info:
+        make(handler).email("a@b.com")
+    assert info.value.status == 402 and info.value.type == "insufficient_credits" and info.value.request_id == "r1"
+
+
+def test_retries_on_429(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        if len(calls) < 2:
+            return httpx.Response(429, json={"error": {"type": "rate_limited", "message": "slow"}}, headers={"Retry-After": "1"})
+        return httpx.Response(200, json={"ok": True})
+
+    assert make(handler).ip("1.2.3.4") == {"ok": True}
+    assert len(calls) == 2
+
+
+def test_batch_chunks_by_100():
+    sizes = []
+
+    def handler(request):
+        emails = json.loads(request.content)["emails"]
+        sizes.append(len(emails))
+        return httpx.Response(200, json={"results": [{"email": e} for e in emails], "count": len(emails)})
+
+    results = make(handler).emails([f"u{i}@a.com" for i in range(250)])
+    assert sizes == [100, 100, 50] and len(results) == 250
+
+
+def test_idempotency_header():
+    def handler(request):
+        assert request.headers["Idempotency-Key"] == "k1"
+        return httpx.Response(200, json={})
+
+    make(handler).phone("+447400123456", idempotency_key="k1")
+
+
+def test_requires_key(monkeypatch):
+    monkeypatch.delenv("VEQEN_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        Veqen()
+
+
+def test_retry_preserves_automatic_idempotency_key(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    keys = []
+
+    def handler(request):
+        keys.append(request.headers["Idempotency-Key"])
+        if len(keys) == 1:
+            raise httpx.ReadTimeout("Response lost after server charged", request=request)
+        return httpx.Response(200, json={})
+
+    client = make(handler)
+    client.ip("1.2.3.4")
+    client.ip("1.2.3.4")
+    assert keys[0] == keys[1]
+    assert keys[1] != keys[2]

veqen-0.1.0/veqen/__init__.py

@@ -0,0 +1,143 @@
+"""Official Python client for the Veqen signup-check API.
+
+    from veqen import Veqen
+
+    client = Veqen()  # reads VEQEN_API_KEY
+    result = client.signup(email="jane@mailinator.com", ip="185.220.101.1")
+    print(result["risk"]["verdict"])
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+__all__ = ["Veqen", "VeqenError"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://veqen-app.com"
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+class VeqenError(Exception):
+    """Raised for any non-2xx response. ``type`` matches the API's error.type."""
+
+    def __init__(self, status: int, type_: str, message: str, request_id: str | None = None):
+        super().__init__(f"{status} {type_}: {message}")
+        self.status = status
+        self.type = type_
+        self.message = message
+        self.request_id = request_id
+
+
+class Veqen:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("VEQEN_API_KEY")
+        if not key:
+            raise ValueError("Pass api_key or set VEQEN_API_KEY.")
+        self.max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=(base_url or os.environ.get("VEQEN_BASE_URL") or DEFAULT_BASE_URL).rstrip("/"),
+            headers={"Authorization": f"Bearer {key}", "User-Agent": f"veqen-python/{__version__}"},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # --- checks ----------------------------------------------------------------------------------
+
+    def email(self, email: str, *, verify_mailbox: bool = False, idempotency_key: str | None = None) -> dict:
+        return self._post("/v1/email/check", {"email": email, "verify_mailbox": verify_mailbox}, idempotency_key)
+
+    def emails(self, emails: list[str], *, verify_mailbox: bool = False) -> list[dict]:
+        results: list[dict] = []
+        for start in range(0, len(emails), 100):
+            chunk = emails[start : start + 100]
+            results.extend(self._post("/v1/email/batch", {"emails": chunk, "verify_mailbox": verify_mailbox})["results"])
+        return results
+
+    def ip(self, ip: str, *, idempotency_key: str | None = None) -> dict:
+        return self._post("/v1/ip/check", {"ip": ip}, idempotency_key)
+
+    def phone(self, phone: str, country: str | None = None, *, idempotency_key: str | None = None) -> dict:
+        return self._post("/v1/phone/check", {"phone": phone, "country": country}, idempotency_key)
+
+    def domain(self, domain: str, *, idempotency_key: str | None = None) -> dict:
+        return self._post("/v1/domain/check", {"domain": domain}, idempotency_key)
+
+    def signup(
+        self,
+        *,
+        email: str | None = None,
+        ip: str | None = None,
+        phone: str | None = None,
+        phone_country: str | None = None,
+        verify_mailbox: bool = False,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        body = {"email": email, "ip": ip, "phone": phone, "phone_country": phone_country, "verify_mailbox": verify_mailbox}
+        return self._post("/v1/signup/check", {k: v for k, v in body.items() if v not in (None, "")}, idempotency_key)
+
+    # --- account ---------------------------------------------------------------------------------
+
+    def account(self) -> dict:
+        return self._request("GET", "/v1/account")
+
+    def usage(self, days: int = 30) -> dict:
+        return self._request("GET", "/v1/usage", params={"days": days})
+
+    # --- plumbing --------------------------------------------------------------------------------
+
+    def _post(self, path: str, body: dict, idempotency_key: str | None = None) -> Any:
+        # Reuse one key across transport/5xx retries, but generate a fresh key per logical call.
+        headers = {"Idempotency-Key": idempotency_key or str(uuid.uuid4())}
+        return self._request("POST", path, json=body, headers=headers)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if attempt >= self.max_retries:
+                    raise
+                attempt += 1
+                time.sleep(min(2**attempt * 0.25, 4))
+                continue
+            if response.status_code in RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                retry_after = response.headers.get("Retry-After")
+                time.sleep(float(retry_after) if retry_after and retry_after.isdigit() else min(2**attempt * 0.25, 4))
+                continue
+            if response.status_code >= 400:
+                try:
+                    error = response.json().get("error", {})
+                except ValueError:
+                    error = {}
+                raise VeqenError(
+                    response.status_code,
+                    error.get("type", "http_error"),
+                    error.get("message", response.text[:200]),
+                    response.headers.get("X-Request-Id"),
+                )
+            return response.json()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Veqen:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

veqen-0.1.0/veqen.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: veqen
+Version: 0.1.0
+Summary: Official Python client for the Veqen signup-check API: disposable emails, datacenter IPs, VoIP numbers and more.
+License-Expression: MIT
+Project-URL: Homepage, https://veqen-app.com
+Project-URL: Documentation, https://veqen-app.com/docs
+Project-URL: Source, https://github.com/Keyveve/veqen-sdks/tree/main/python
+Project-URL: Issues, https://github.com/Keyveve/veqen-sdks/issues
+Keywords: email validation,disposable email,fraud,signup,ip lookup,phone validation,vpn detection
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: certifi>=2026.10.19
+Dynamic: license-file
+
+# veqen (Python)
+
+Official Python client for [Veqen](https://veqen-app.com): catch disposable emails, typos, datacenter and Tor IPs, and VoIP numbers with one API call.
+
+```bash
+pip install https://veqen-app.com/static/sdk/veqen-0.1.0-py3-none-any.whl
+```
+
+```python
+from veqen import Veqen, VeqenError
+
+client = Veqen()  # reads VEQEN_API_KEY from the environment
+
+result = client.signup(email="jane@mailinator.com", ip="185.220.101.1")
+print(result["risk"]["verdict"])        # "refuse"
+for reason in result["risk"]["reasons"]:
+    print(reason["code"], reason["message"])
+```
+
+| Method | Endpoint | Credits |
+|---|---|---|
+| `email(address, verify_mailbox=False)` | `/v1/email/check` | 1 (+5) |
+| `emails(list)` | `/v1/email/batch` (chunks of 100) | 1 each |
+| `ip(address)` | `/v1/ip/check` | 1 |
+| `phone(number, country=None)` | `/v1/phone/check` | 1 |
+| `domain(name)` | `/v1/domain/check` | 1 |
+| `signup(email=, ip=, phone=, phone_country=)` | `/v1/signup/check` | 3 |
+| `account()`, `usage(days=30)` | `/v1/account`, `/v1/usage` | 0 |
+
+Errors raise `VeqenError` with `.status`, `.type` (e.g. `insufficient_credits`) and `.message`. Requests are retried on 429 and 5xx. Docs: https://veqen-app.com/docs

veqen-0.1.0/veqen.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_client.py
+veqen/__init__.py
+veqen.egg-info/PKG-INFO
+veqen.egg-info/SOURCES.txt
+veqen.egg-info/dependency_links.txt
+veqen.egg-info/requires.txt
+veqen.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+httpx>=0.25
+certifi>=2026.10.19

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

@@ -0,0 +1 @@
+veqen