fraudnova 1.0.0__py3-none-any.whl

fraudnova/__init__.py

@@ -0,0 +1,44 @@
+"""Official Python SDK for the FraudNova fraud-detection API."""
+
+from ._version import __version__
+from .client import BATCH_MAX, DEFAULT_BASE_URL, Client
+from .exceptions import (
+    AccountSuspendedError,
+    ApiError,
+    AuthenticationError,
+    FraudNovaError,
+    InsufficientCreditsError,
+    InvalidArgumentError,
+    RateLimitError,
+    TransportError,
+    UnexpectedResponseError,
+    UpstreamError,
+    ValidationError,
+)
+from .results import BatchItem, BatchResult, DateInfo, EmailResult, IpResult, PhoneResult
+from .retry import RetryPolicy
+
+__all__ = [
+    "BATCH_MAX",
+    "DEFAULT_BASE_URL",
+    "AccountSuspendedError",
+    "ApiError",
+    "AuthenticationError",
+    "BatchItem",
+    "BatchResult",
+    "Client",
+    "DateInfo",
+    "EmailResult",
+    "FraudNovaError",
+    "InsufficientCreditsError",
+    "InvalidArgumentError",
+    "IpResult",
+    "PhoneResult",
+    "RateLimitError",
+    "RetryPolicy",
+    "TransportError",
+    "UnexpectedResponseError",
+    "UpstreamError",
+    "ValidationError",
+    "__version__",
+]

fraudnova/_transport.py

@@ -0,0 +1,112 @@
+"""Internal HTTP layer: builds requests, decodes the envelope, maps errors, retries 429s."""
+
+import platform
+from collections.abc import Mapping
+from typing import Any, Optional, Union
+
+import httpx
+
+from fraudnova._version import __version__
+from fraudnova.exceptions import (
+    ApiError,
+    InvalidArgumentError,
+    RateLimitError,
+    TransportError,
+    UnexpectedResponseError,
+    mask_api_key,
+)
+from fraudnova.retry import RetryPolicy, parse_retry_after
+
+
+class Transport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        retry: Optional[RetryPolicy],
+        http_client: Optional[httpx.Client],
+    ) -> None:
+        if api_key == "" or any(not 0x21 <= ord(ch) <= 0x7E for ch in api_key):
+            raise InvalidArgumentError(
+                "api_key must contain only printable ASCII characters, without whitespace."
+            )
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retry = retry
+        self._client = http_client
+        self.owns_client = http_client is None
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Union[str, int]]] = None,
+        authenticated: bool = True,
+    ) -> dict[str, Any]:
+        return self._send("GET", self.base_url + path, authenticated, params=params)
+
+    def post(self, path: str, json: Mapping[str, Any]) -> dict[str, Any]:
+        return self._send("POST", self.base_url + path, True, json=json)
+
+    def close(self) -> None:
+        if self.owns_client and self._client is not None:
+            self._client.close()
+
+    def _http(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(timeout=httpx.Timeout(self._timeout, connect=10.0))
+        return self._client
+
+    def _headers(self, authenticated: bool) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"fraudnova-python/{__version__} python/{platform.python_version()}",
+        }
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    def _send(
+        self,
+        method: str,
+        url: str,
+        authenticated: bool,
+        params: Optional[Mapping[str, Union[str, int]]] = None,
+        json: Optional[Mapping[str, Any]] = None,
+    ) -> dict[str, Any]:
+        attempt = 1
+        while True:
+            try:
+                response = self._http().request(
+                    method, url, params=params, json=json, headers=self._headers(authenticated)
+                )
+            except (httpx.HTTPError, httpx.InvalidURL, httpx.StreamError) as exc:
+                message = str(exc).replace(self._api_key, mask_api_key(self._api_key))
+                raise TransportError(f"FraudNova request failed: {message}") from exc
+
+            try:
+                return self._decode(response)
+            except RateLimitError as error:
+                delay = self._retry.delay_for(error, attempt) if self._retry else None
+                if self._retry is None or delay is None:
+                    raise
+                self._retry.sleep(delay)
+                attempt += 1
+
+    @staticmethod
+    def _decode(response: httpx.Response) -> dict[str, Any]:
+        status = response.status_code
+        if status < 200 or status >= 300:
+            raise ApiError.from_response(
+                status, response.text, parse_retry_after(response.headers.get("Retry-After"))
+            )
+        try:
+            decoded: Any = response.json()
+        except (ValueError, RecursionError):
+            decoded = None
+        if not isinstance(decoded, dict) or decoded.get("success") is not True:
+            raise UnexpectedResponseError(
+                status, "Unexpected response body", decoded if isinstance(decoded, dict) else None
+            )
+        return decoded

fraudnova/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

fraudnova/client.py

@@ -0,0 +1,203 @@
+"""The public FraudNova client."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal, Optional, Union
+
+import httpx
+
+from fraudnova._transport import Transport
+from fraudnova.exceptions import InvalidArgumentError, UnexpectedResponseError, mask_api_key
+from fraudnova.results import BatchItem, BatchResult, EmailResult, IpResult, PhoneResult, _int
+from fraudnova.retry import RetryPolicy
+
+DEFAULT_BASE_URL = "https://fraudnova.com/api/v1"
+BATCH_MAX = 100
+
+
+def _subject(value: str, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidArgumentError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _strictness(value: Optional[int]) -> Optional[int]:
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool) or value not in (0, 1, 2, 3):
+        raise InvalidArgumentError("strictness must be an integer from 0 to 3")
+    return value
+
+
+def _country(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    return value.strip().upper() or None
+
+
+def _data(envelope: Mapping[str, Any]) -> dict[str, Any]:
+    data = envelope.get("data")
+    if not isinstance(data, dict):
+        raise UnexpectedResponseError(200, "Missing data", dict(envelope))
+    return data
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        retry: Optional[RetryPolicy] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key.strip() if isinstance(api_key, str) else ""
+        if not key:
+            raise InvalidArgumentError("api_key must be a non-empty string")
+        if not base_url.lower().startswith(("http://", "https://")):
+            raise InvalidArgumentError("base_url must start with http:// or https://")
+        self._api_key = key
+        self._transport = Transport(key, base_url, timeout, retry, http_client)
+
+    def __repr__(self) -> str:
+        masked = mask_api_key(self._api_key)
+        return f"Client(api_key={masked!r}, base_url={self._transport.base_url!r})"
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    # Single checks
+
+    def check_ip(
+        self,
+        ip: str,
+        *,
+        strictness: Optional[int] = None,
+        mobile: Optional[bool] = None,
+        user_agent: Optional[str] = None,
+        user_language: Optional[str] = None,
+    ) -> IpResult:
+        params: dict[str, Union[str, int]] = {"ip": _subject(ip, "ip")}
+        level = _strictness(strictness)
+        if level is not None:
+            params["strictness"] = level
+        if mobile is not None:
+            params["mobile"] = "true" if mobile else "false"
+        if user_agent is not None:
+            params["user_agent"] = user_agent
+        if user_language is not None:
+            params["user_language"] = user_language
+        envelope = self._transport.get("/check", params)
+        return IpResult.from_dict(_data(envelope), _int(envelope.get("credits_remaining")))
+
+    def check_email(self, email: str) -> EmailResult:
+        envelope = self._transport.get("/check/email", {"email": _subject(email, "email")})
+        return EmailResult.from_dict(_data(envelope), _int(envelope.get("credits_remaining")))
+
+    def check_phone(self, phone: str, country: Optional[str] = None) -> PhoneResult:
+        params: dict[str, Union[str, int]] = {"phone": _subject(phone, "phone")}
+        code = _country(country)
+        if code:
+            params["country"] = code
+        envelope = self._transport.get("/check/phone", params)
+        return PhoneResult.from_dict(_data(envelope), _int(envelope.get("credits_remaining")))
+
+    # Batch checks
+
+    def check_ips(
+        self,
+        ips: Sequence[Optional[str]],
+        *,
+        strictness: Optional[int] = None,
+        mobile: Optional[bool] = None,
+        user_agent: Optional[str] = None,
+        user_language: Optional[str] = None,
+    ) -> BatchResult:
+        extra: dict[str, Any] = {}
+        level = _strictness(strictness)
+        if level is not None:
+            extra["strictness"] = level
+        if mobile is not None:
+            extra["mobile"] = mobile
+        if user_agent is not None:
+            extra["user_agent"] = user_agent
+        if user_language is not None:
+            extra["user_language"] = user_language
+        return self._batch("/check/batch", "ips", "ip", ips, extra)
+
+    def check_emails(self, emails: Sequence[Optional[str]]) -> BatchResult:
+        return self._batch("/check/email/batch", "emails", "email", emails, {})
+
+    def check_phones(
+        self, phones: Sequence[Optional[str]], country: Optional[str] = None
+    ) -> BatchResult:
+        extra: dict[str, Any] = {}
+        code = _country(country)
+        if code:
+            extra["country"] = code
+        return self._batch("/check/phone/batch", "phones", "phone", phones, extra)
+
+    def _batch(
+        self,
+        path: str,
+        field: str,
+        kind: Literal["ip", "email", "phone"],
+        subjects: Sequence[Optional[str]],
+        extra: Mapping[str, Any],
+    ) -> BatchResult:
+        if isinstance(subjects, (str, bytes)):
+            raise InvalidArgumentError(f"{field} must be a list of values, not a single string")
+        if len(subjects) == 0:
+            raise InvalidArgumentError(f"{field} must not be empty")
+        cleaned: list[Optional[str]] = []
+        for index, item in enumerate(subjects):
+            if item is not None and not isinstance(item, str):
+                raise InvalidArgumentError(f"{field}[{index}] must be a string or None")
+            cleaned.append(item.strip() if item is not None else None)
+        items: list[BatchItem] = []
+        credits = 0
+        for start in range(0, len(cleaned), BATCH_MAX):
+            body: dict[str, Any] = {field: cleaned[start : start + BATCH_MAX], **extra}
+            envelope = self._transport.post(path, body)
+            if not isinstance(envelope.get("results"), list):
+                raise UnexpectedResponseError(200, "Missing results", dict(envelope))
+            part = BatchResult.from_dict(envelope, kind)
+            items.extend(part.items)
+            credits = part.credits_remaining
+            rest = cleaned[start + BATCH_MAX :]
+            if rest and _int(envelope.get("credits_remaining")) == 0:
+                # The API answers 402 to a request sent with a zero balance, which would
+                # discard the results above; mark the unsent items the way the API does.
+                items.extend(
+                    BatchItem(
+                        subject=item or "",
+                        success=False,
+                        result=None,
+                        error="insufficient_credits",
+                    )
+                    for item in rest
+                )
+                break
+        return BatchResult(items=items, credits_remaining=credits)
+
+    # Account
+
+    def balance(self) -> int:
+        envelope = self._transport.get("/balance")
+        credits = _int(envelope.get("credits_remaining"))
+        if credits is None:
+            raise UnexpectedResponseError(200, "Missing credits_remaining", dict(envelope))
+        return credits
+
+    def my_ip(self) -> str:
+        envelope = self._transport.get("/my-ip", authenticated=False)
+        ip = envelope.get("ip")
+        if not isinstance(ip, str) or not ip:
+            raise UnexpectedResponseError(200, "Missing ip", dict(envelope))
+        return ip

fraudnova/exceptions.py

@@ -0,0 +1,158 @@
+"""Exception hierarchy for the FraudNova SDK."""
+
+import json
+from typing import Any, Optional
+
+
+def mask_api_key(api_key: str) -> str:
+    """Return a safe, shortened form of an API key for display."""
+    if len(api_key) > 12:
+        return "fn_…" + api_key[-4:]
+    return "fn_…"
+
+
+class FraudNovaError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class InvalidArgumentError(FraudNovaError, ValueError):
+    """A client-side input problem; no request was sent."""
+
+
+class TransportError(FraudNovaError):
+    """The HTTP request itself failed (timeout, DNS, TLS)."""
+
+
+class ApiError(FraudNovaError):
+    """The API answered with an error status."""
+
+    def __init__(
+        self,
+        status_code: int,
+        api_message: str,
+        body: Optional[dict[str, Any]] = None,
+        message: Optional[str] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.api_message = api_message
+        self.body: dict[str, Any] = body if body is not None else {}
+        super().__init__(
+            message
+            if message is not None
+            else f"FraudNova API error (HTTP {status_code}): {api_message}"
+        )
+        self._init_args: tuple[Any, ...] = (status_code, api_message, body, message)
+
+    def __reduce__(self) -> "tuple[Any, tuple[Any, ...], dict[str, Any]]":
+        # BaseException rebuilds from self.args (the message only), which does not match
+        # this constructor; rebuild from the arguments the instance was created with.
+        return (type(self), self._init_args, dict(self.__dict__))
+
+    @classmethod
+    def from_response(
+        cls, status_code: int, text: str, retry_after: Optional[int] = None
+    ) -> "ApiError":
+        try:
+            decoded: Any = json.loads(text)
+        except (ValueError, RecursionError):
+            decoded = None
+        is_json = isinstance(decoded, dict)
+        body: dict[str, Any] = decoded if isinstance(decoded, dict) else {}
+        envelope = is_json and ("success" in body or "message" in body)
+
+        api_message = ""
+        for key in ("message", "error"):
+            value = body.get(key)
+            if isinstance(value, str) and value != "":
+                api_message = value
+                break
+        if api_message == "":
+            stripped = text.strip()
+            api_message = stripped[:200] if stripped else f"HTTP {status_code}"
+
+        full: Optional[str] = (
+            None if is_json else f"FraudNova API error (HTTP {status_code}): non-JSON response"
+        )
+
+        if envelope and status_code == 401:
+            return AuthenticationError(status_code, api_message, body, full)
+        if envelope and status_code == 402:
+            return InsufficientCreditsError(status_code, api_message, body, full)
+        if envelope and status_code == 403:
+            return AccountSuspendedError(status_code, api_message, body, full)
+        if envelope and status_code == 422:
+            return ValidationError(status_code, api_message, body, full)
+        if status_code == 429:
+            return RateLimitError(status_code, api_message, body, retry_after, full)
+        if status_code in (502, 503, 504):
+            return UpstreamError(
+                status_code,
+                api_message,
+                body,
+                status_code == 503 and envelope,
+                full,
+            )
+        return ApiError(status_code, api_message, body, full)
+
+
+class AuthenticationError(ApiError):
+    """401: missing or invalid API key."""
+
+
+class InsufficientCreditsError(ApiError):
+    """402: the account has no credits left."""
+
+
+class AccountSuspendedError(ApiError):
+    """403: the account is suspended."""
+
+
+class ValidationError(ApiError):
+    """422: the request failed validation."""
+
+
+class RateLimitError(ApiError):
+    """429: rate or concurrency limit hit."""
+
+    def __init__(
+        self,
+        status_code: int,
+        api_message: str,
+        body: Optional[dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+        message: Optional[str] = None,
+    ) -> None:
+        super().__init__(status_code, api_message, body, message)
+        self.retry_after = retry_after
+        self._init_args = (status_code, api_message, body, retry_after, message)
+
+    @property
+    def is_concurrency_limit(self) -> bool:
+        return "Too many concurrent requests" in self.api_message
+
+
+class UpstreamError(ApiError):
+    """502/503/504: the lookup could not be completed."""
+
+    def __init__(
+        self,
+        status_code: int,
+        api_message: str,
+        body: Optional[dict[str, Any]] = None,
+        credit_refunded: bool = False,
+        message: Optional[str] = None,
+    ) -> None:
+        text = (
+            message
+            if message is not None
+            else f"FraudNova API error (HTTP {status_code}): {api_message}"
+        )
+        if credit_refunded:
+            text += " The credit for this check was refunded."
+        super().__init__(status_code, api_message, body, text)
+        self.credit_refunded = credit_refunded
+        self._init_args = (status_code, api_message, body, credit_refunded, message)
+
+
+class UnexpectedResponseError(ApiError):
+    """A 2xx response whose body is not the success envelope."""

fraudnova/results.py

@@ -0,0 +1,342 @@
+"""Typed, leniently parsed results for IP, email and phone checks."""
+
+import math
+import re
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Literal, Optional, Union
+
+from fraudnova.exceptions import InvalidArgumentError
+
+_WHOLE = re.compile(r"-?[0-9]+")
+_DECIMAL = re.compile(r"-?[0-9]+\.[0-9]+")
+
+
+def _bool(value: Any) -> Optional[bool]:
+    return value if isinstance(value, bool) else None
+
+
+def _str(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) else None
+
+
+def _int(value: Any) -> Optional[int]:
+    """Ints and whole-number strings as-is; floats and decimal strings round half away from zero."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    number: Optional[float] = None
+    if isinstance(value, str):
+        if _WHOLE.fullmatch(value):
+            if len(value) > 20:
+                return None
+            try:
+                return int(value)
+            except ValueError:  # beyond Python's int-string digit limit
+                return None
+        if _DECIMAL.fullmatch(value):
+            number = float(value)
+    elif isinstance(value, float):
+        number = value
+    if number is None or not math.isfinite(number):
+        return None
+    rounded = math.floor(abs(number) + 0.5)
+    return -rounded if number < 0 else rounded
+
+
+_coerce_int = _int
+
+
+@dataclass(frozen=True)
+class DateInfo:
+    human: Optional[str]
+    timestamp: Optional[int]
+    iso: Optional[str]
+
+    @classmethod
+    def from_value(cls, value: Any) -> Optional["DateInfo"]:
+        if isinstance(value, str):
+            return cls(human=value, timestamp=None, iso=None)
+        if isinstance(value, Mapping):
+            return cls(
+                human=_str(value.get("human")),
+                timestamp=_int(value.get("timestamp")),
+                iso=_str(value.get("iso")),
+            )
+        return None
+
+
+class _FlaggableResult:
+    DEFAULT_FLAG_ON: ClassVar[tuple[str, ...]] = ()
+    raw: dict[str, Any]
+
+    def flag_reasons(
+        self, risk_threshold: int = 75, flag_on: Optional[Sequence[str]] = None
+    ) -> list[str]:
+        if isinstance(flag_on, (str, bytes)):
+            raise InvalidArgumentError("flag_on must be a list of field names, not a single string")
+        reasons: list[str] = []
+        if (_int(self.raw.get("fraud_score")) or 0) >= risk_threshold:
+            reasons.append("fraud_score")
+        names = self.DEFAULT_FLAG_ON if flag_on is None else flag_on
+        reasons.extend(name for name in names if self.raw.get(name) is True)
+        return reasons
+
+    def flagged(self, risk_threshold: int = 75, flag_on: Optional[Sequence[str]] = None) -> bool:
+        return bool(self.flag_reasons(risk_threshold, flag_on))
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.raw)
+
+
+@dataclass(frozen=True)
+class IpResult(_FlaggableResult):
+    DEFAULT_FLAG_ON: ClassVar[tuple[str, ...]] = ("proxy", "vpn", "tor")
+
+    fraud_score: int
+    proxy: Optional[bool]
+    vpn: Optional[bool]
+    tor: Optional[bool]
+    active_vpn: Optional[bool]
+    active_tor: Optional[bool]
+    recent_abuse: Optional[bool]
+    bot_status: Optional[bool]
+    country_code: Optional[str]
+    region: Optional[str]
+    city: Optional[str]
+    isp: Optional[str]
+    organization: Optional[str]
+    asn: Optional[int]
+    operating_system: Optional[str]
+    browser: Optional[str]
+    device_brand: Optional[str]
+    device_model: Optional[str]
+    credits_remaining: Optional[int]
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(
+        cls, data: Mapping[str, Any], credits_remaining: Optional[int] = None
+    ) -> "IpResult":
+        raw = data if isinstance(data, dict) else dict(data)
+        return cls(
+            fraud_score=_int(raw.get("fraud_score")) or 0,
+            proxy=_bool(raw.get("proxy")),
+            vpn=_bool(raw.get("vpn")),
+            tor=_bool(raw.get("tor")),
+            active_vpn=_bool(raw.get("active_vpn")),
+            active_tor=_bool(raw.get("active_tor")),
+            recent_abuse=_bool(raw.get("recent_abuse")),
+            bot_status=_bool(raw.get("bot_status")),
+            country_code=_str(raw.get("country_code")),
+            region=_str(raw.get("region")),
+            city=_str(raw.get("city")),
+            isp=_str(raw.get("ISP")),
+            organization=_str(raw.get("organization")),
+            asn=_int(raw.get("ASN")),
+            operating_system=_str(raw.get("operating_system")),
+            browser=_str(raw.get("browser")),
+            device_brand=_str(raw.get("device_brand")),
+            device_model=_str(raw.get("device_model")),
+            credits_remaining=credits_remaining,
+            raw=raw,
+        )
+
+
+@dataclass(frozen=True)
+class EmailResult(_FlaggableResult):
+    DEFAULT_FLAG_ON: ClassVar[tuple[str, ...]] = ("disposable",)
+
+    fraud_score: int
+    valid: Optional[bool]
+    disposable: Optional[bool]
+    catch_all: Optional[bool]
+    generic: Optional[bool]
+    common: Optional[bool]
+    dns_valid: Optional[bool]
+    honeypot: Optional[bool]
+    frequent_complainer: Optional[bool]
+    suspect: Optional[bool]
+    recent_abuse: Optional[bool]
+    leaked: Optional[bool]
+    risky_tld: Optional[bool]
+    spf_record: Optional[bool]
+    dmarc_record: Optional[bool]
+    smtp_score: Optional[int]
+    overall_score: Optional[int]
+    deliverability: Optional[str]
+    spam_trap_score: Optional[str]
+    result_type: Optional[str]
+    sanitized_email: Optional[str]
+    first_seen: Optional[DateInfo]
+    domain_age: Optional[DateInfo]
+    credits_remaining: Optional[int]
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(
+        cls, data: Mapping[str, Any], credits_remaining: Optional[int] = None
+    ) -> "EmailResult":
+        raw = data if isinstance(data, dict) else dict(data)
+        return cls(
+            fraud_score=_int(raw.get("fraud_score")) or 0,
+            valid=_bool(raw.get("valid")),
+            disposable=_bool(raw.get("disposable")),
+            catch_all=_bool(raw.get("catch_all")),
+            generic=_bool(raw.get("generic")),
+            common=_bool(raw.get("common")),
+            dns_valid=_bool(raw.get("dns_valid")),
+            honeypot=_bool(raw.get("honeypot")),
+            frequent_complainer=_bool(raw.get("frequent_complainer")),
+            suspect=_bool(raw.get("suspect")),
+            recent_abuse=_bool(raw.get("recent_abuse")),
+            leaked=_bool(raw.get("leaked")),
+            risky_tld=_bool(raw.get("risky_tld")),
+            spf_record=_bool(raw.get("spf_record")),
+            dmarc_record=_bool(raw.get("dmarc_record")),
+            smtp_score=_int(raw.get("smtp_score")),
+            overall_score=_int(raw.get("overall_score")),
+            deliverability=_str(raw.get("deliverability")),
+            spam_trap_score=_str(raw.get("spam_trap_score")),
+            result_type=_str(raw.get("result_type")),
+            sanitized_email=_str(raw.get("sanitized_email")),
+            first_seen=DateInfo.from_value(raw.get("first_seen")),
+            domain_age=DateInfo.from_value(raw.get("domain_age")),
+            credits_remaining=credits_remaining,
+            raw=raw,
+        )
+
+
+@dataclass(frozen=True)
+class PhoneResult(_FlaggableResult):
+    DEFAULT_FLAG_ON: ClassVar[tuple[str, ...]] = ("VOIP", "risky")
+
+    fraud_score: int
+    valid: Optional[bool]
+    recent_abuse: Optional[bool]
+    voip: Optional[bool]
+    prepaid: Optional[bool]
+    risky: Optional[bool]
+    active: Optional[bool]
+    do_not_call: Optional[bool]
+    leaked: Optional[bool]
+    spammer: Optional[bool]
+    dialing_code: Optional[int]
+    carrier: Optional[str]
+    line_type: Optional[str]
+    country: Optional[str]
+    region: Optional[str]
+    city: Optional[str]
+    timezone: Optional[str]
+    zip_code: Optional[str]
+    active_status: Optional[str]
+    formatted: Optional[str]
+    local_format: Optional[str]
+    credits_remaining: Optional[int]
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(
+        cls, data: Mapping[str, Any], credits_remaining: Optional[int] = None
+    ) -> "PhoneResult":
+        raw = data if isinstance(data, dict) else dict(data)
+        return cls(
+            fraud_score=_int(raw.get("fraud_score")) or 0,
+            valid=_bool(raw.get("valid")),
+            recent_abuse=_bool(raw.get("recent_abuse")),
+            voip=_bool(raw.get("VOIP")),
+            prepaid=_bool(raw.get("prepaid")),
+            risky=_bool(raw.get("risky")),
+            active=_bool(raw.get("active")),
+            do_not_call=_bool(raw.get("do_not_call")),
+            leaked=_bool(raw.get("leaked")),
+            spammer=_bool(raw.get("spammer")),
+            dialing_code=_int(raw.get("dialing_code")),
+            carrier=_str(raw.get("carrier")),
+            line_type=_str(raw.get("line_type")),
+            country=_str(raw.get("country")),
+            region=_str(raw.get("region")),
+            city=_str(raw.get("city")),
+            timezone=_str(raw.get("timezone")),
+            zip_code=_str(raw.get("zip_code")),
+            active_status=_str(raw.get("active_status")),
+            formatted=_str(raw.get("formatted")),
+            local_format=_str(raw.get("local_format")),
+            credits_remaining=credits_remaining,
+            raw=raw,
+        )
+
+
+Result = Union[IpResult, EmailResult, PhoneResult]
+
+
+@dataclass(frozen=True)
+class BatchItem:
+    subject: str
+    success: bool
+    result: Optional[Result]
+    error: Optional[str]
+
+    def is_invalid(self) -> bool:
+        return self.error in ("invalid_ip", "invalid_email", "invalid_phone")
+
+    def is_insufficient_credits(self) -> bool:
+        return self.error == "insufficient_credits"
+
+    def is_upstream_failed(self) -> bool:
+        return self.error == "upstream_failed"
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    items: list[BatchItem]
+    credits_remaining: int
+
+    @classmethod
+    def from_dict(
+        cls, envelope: Mapping[str, Any], kind: Literal["ip", "email", "phone"]
+    ) -> "BatchResult":
+        raw_items = envelope.get("results")
+        items: list[BatchItem] = []
+        if isinstance(raw_items, list):
+            for item in raw_items:
+                if not isinstance(item, dict):
+                    continue
+                success = _bool(item.get("success")) or False
+                data = item.get("data")
+                result: Optional[Result] = None
+                if success and isinstance(data, dict):
+                    if kind == "ip":
+                        result = IpResult.from_dict(data)
+                    elif kind == "email":
+                        result = EmailResult.from_dict(data)
+                    else:
+                        result = PhoneResult.from_dict(data)
+                items.append(
+                    BatchItem(
+                        subject=_str(item.get(kind)) or "",
+                        success=success,
+                        result=result,
+                        error=_str(item.get("error")),
+                    )
+                )
+        return cls(items=items, credits_remaining=_int(envelope.get("credits_remaining")) or 0)
+
+    def successful(self) -> list[BatchItem]:
+        return [i for i in self.items if i.success]
+
+    def failed(self) -> list[BatchItem]:
+        return [i for i in self.items if not i.success]
+
+    def has_failures(self) -> bool:
+        return any(not i.success for i in self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __iter__(self) -> Iterator[BatchItem]:
+        return iter(self.items)
+
+    def __getitem__(self, index: int) -> BatchItem:
+        return self.items[index]

fraudnova/retry.py

@@ -0,0 +1,65 @@
+"""Opt-in retry policy for rate-limited (429) requests."""
+
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Callable, Optional
+
+from fraudnova.exceptions import InvalidArgumentError, RateLimitError
+
+
+def parse_retry_after(value: Optional[str], now: Optional[datetime] = None) -> Optional[int]:
+    """Parse a Retry-After header (delta-seconds or HTTP-date) into whole seconds."""
+    if value is None:
+        return None
+    text = value.strip()
+    if text == "":
+        return None
+    if text.isascii() and text.isdigit():
+        try:
+            return int(text)
+        except ValueError:
+            return None
+    try:
+        when = parsedate_to_datetime(text)
+    except (TypeError, ValueError, IndexError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    current = now if now is not None else datetime.now(timezone.utc)
+    return max(0, int((when - current).total_seconds()))
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    max_attempts: int = 3
+    concurrency_delays: Sequence[float] = (1, 2, 4)
+    rate_limit_delays: Sequence[float] = (5, 15, 40)
+    honour_retry_after: bool = True
+    max_retry_after: float = 60
+    sleeper: Callable[[float], None] = time.sleep
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise InvalidArgumentError("max_attempts must be at least 1.")
+        if self.max_retry_after < 0:
+            raise InvalidArgumentError("max_retry_after must not be negative.")
+
+    def delay_for(self, error: RateLimitError, attempt: int) -> Optional[float]:
+        """Seconds to wait before retrying after `attempt` (1-based) failed, or None to stop."""
+        if attempt >= self.max_attempts:
+            return None
+        if self.honour_retry_after and error.retry_after is not None:
+            if error.retry_after > self.max_retry_after:
+                return None
+            return float(error.retry_after)
+        schedule = self.concurrency_delays if error.is_concurrency_limit else self.rate_limit_delays
+        index = attempt - 1
+        if index >= len(schedule):
+            return None
+        return float(schedule[index])
+
+    def sleep(self, seconds: float) -> None:
+        self.sleeper(seconds)

fraudnova-1.0.0.dist-info/METADATA

@@ -0,0 +1,293 @@
+Metadata-Version: 2.5
+Name: fraudnova
+Version: 1.0.0
+Summary: Official Python client for the FraudNova fraud-detection API (IP, email and phone checks)
+Project-URL: Homepage, https://fraudnova.com
+Project-URL: Documentation, https://fraudnova.com/docs
+Project-URL: Repository, https://github.com/dahleedam/fraudnova-python
+Project-URL: Changelog, https://github.com/dahleedam/fraudnova-python/blob/main/CHANGELOG.md
+Author-email: FraudNova <support@fraudnova.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,email-validation,fraud,fraud-detection,ip,phone-validation,proxy,vpn
+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<1.0,>=0.26
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fraudnova
+
+[FraudNova](https://fraudnova.com) is a fraud-detection API. It returns a fraud score and risk flags for any IP address, email address or phone number, so your application can decide whether to accept, review or block a signup, lead or order. This is the official Python client.
+
+[![CI](https://github.com/dahleedam/fraudnova-python/actions/workflows/ci.yml/badge.svg)](https://github.com/dahleedam/fraudnova-python/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/fraudnova)](https://pypi.org/project/fraudnova/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fraudnova)](https://pypi.org/project/fraudnova/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+## Requirements
+
+- Python 3.9 or later
+- [httpx](https://www.python-httpx.org/) 0.26 or later, installed automatically
+
+## Installation
+
+```bash
+pip install fraudnova
+```
+
+You need an API key. [Register](https://fraudnova.com/register) to get free trial credits, then create a key at [fraudnova.com/dashboard/api-keys](https://fraudnova.com/dashboard/api-keys). The key starts with `fn_` and is shown once, so copy it right away.
+
+## Quickstart
+
+```python
+import fraudnova
+
+client = fraudnova.Client("fn_your_api_key")
+result = client.check_ip("8.8.8.8")
+if result.flagged():
+    ...  # review or block
+print(result.fraud_score)
+```
+
+## Checking IP addresses, emails and phone numbers
+
+```python
+import fraudnova
+
+client = fraudnova.Client("fn_your_api_key")
+
+ip = client.check_ip("8.8.8.8")
+email = client.check_email("someone@example.com")
+phone = client.check_phone("+1 817 679 1808")
+phone = client.check_phone("8176791808", country="US")  # optional two-letter country hint
+```
+
+`check_ip()` takes optional keyword arguments. Leave one out to use the API default.
+
+```python
+result = client.check_ip(
+    visitor_ip,
+    strictness=1,  # 0 = lenient, 3 = strict
+    mobile=False,  # the request comes from a mobile device
+    user_agent=request.headers.get("User-Agent"),  # enables the device and browser fields
+    user_language=request.headers.get("Accept-Language", "").split(",")[0].strip() or None,
+)
+```
+
+`user_language` takes a short language tag such as `en-US`, not the whole `Accept-Language` header, so the example sends only the first tag.
+
+An empty value, or a `strictness` that is not an integer from 0 to 3, raises `fraudnova.InvalidArgumentError` before any request is sent.
+
+## Batch checks
+
+`check_ips()`, `check_emails()` and `check_phones()` score a list of values. The list can be any length: the client splits it into requests of 100 (`fraudnova.BATCH_MAX`) and joins the answers in input order.
+
+```python
+batch = client.check_ips(ips)
+
+for item in batch.successful():
+    print(item.subject, item.result.fraud_score)
+
+for item in batch.failed():
+    print(item.subject, "failed:", item.error)
+
+print("Credits left:", batch.credits_remaining)
+```
+
+`check_ips()` takes the same keyword options as `check_ip()`, and `check_phones()` takes one `country` hint for the whole batch. `BatchResult` is iterable and supports `len()` and indexing; each `BatchItem` has `subject`, `success`, `result` (an `IpResult`, `EmailResult` or `PhoneResult`, or `None` on failure) and `error`. `has_failures()` tells you whether any item failed.
+
+Batches are split into requests of 100. When a request reports zero credits remaining, the client stops and marks the remaining items `insufficient_credits` instead of sending a request that would fail. Any other error on a later request (a 429 with no retry policy or with the retries used up, a 503, or a `TransportError`) propagates as an exception, and the results of the earlier requests are discarded even though they were billed. If you need control over each request, slice the list to 100 yourself:
+
+```python
+for start in range(0, len(ips), fraudnova.BATCH_MAX):
+    batch = client.check_ips(ips[start : start + fraudnova.BATCH_MAX])
+    ...  # handle this request's result before sending the next
+```
+
+Items must be strings or `None`; any other type raises `InvalidArgumentError` before the request is sent. One bad value never fails the batch, so an empty string or `None` comes back as a failed item. A failed item carries one of these error codes:
+
+| `error` | Helper | Meaning |
+| --- | --- | --- |
+| `invalid_ip`, `invalid_email`, `invalid_phone` | `is_invalid()` | The value is not a valid IP address, email address or phone number. |
+| `insufficient_credits` | `is_insufficient_credits()` | Your balance ran out partway through the batch. |
+| `upstream_failed` | `is_upstream_failed()` | The lookup failed. The item was not charged. |
+
+## Results
+
+`check_ip()`, `check_email()` and `check_phone()` return an `IpResult`, `EmailResult` or `PhoneResult`. Each has the API's fields as snake_case attributes, for example `fraud_score`, `recent_abuse` and `country_code`. `fraud_score` is always an integer (0 when the API does not return one); every other field is optional (`None`), because the API does not return every field for every check.
+
+```python
+ip = client.check_ip("8.8.8.8")
+ip.proxy  # Optional[bool]
+ip.vpn  # Optional[bool]
+ip.country_code  # Optional[str], for example "US"
+ip.isp  # Optional[str] (API field ISP)
+ip.asn  # Optional[int] (API field ASN)
+
+email = client.check_email("someone@example.com")
+email.disposable  # Optional[bool]
+email.deliverability  # Optional[str]
+email.first_seen  # Optional[DateInfo], also domain_age
+
+phone = client.check_phone("+18176791808")
+phone.voip  # Optional[bool] (API field VOIP)
+phone.line_type  # Optional[str]
+phone.carrier  # Optional[str]
+```
+
+The email dates `first_seen` and `domain_age` are `DateInfo` objects with `human`, `timestamp` and `iso`.
+
+`to_dict()` returns the full API response for that check, with the original field names, including any field the client does not map to an attribute:
+
+```python
+fields = client.check_ip("8.8.8.8").to_dict()
+# {"fraud_score": 20, "proxy": False, "ISP": "Google", ...}
+```
+
+`credits_remaining` holds your balance after the check. It is `None` on results inside a batch; read `BatchResult.credits_remaining` there instead.
+
+## The `flagged()` helper
+
+`flagged()` returns `True` when the `fraud_score` is at or above a risk threshold (default 75), or when any of a set of fields is `True`. `flag_reasons()` lists which of those fired, for example `["fraud_score", "proxy"]`. Both take the same two optional arguments, `risk_threshold` and `flag_on`.
+
+| Check | Fields checked by default |
+| --- | --- |
+| IP address | `proxy`, `vpn`, `tor` |
+| Email address | `disposable` |
+| Phone number | `VOIP`, `risky` |
+
+Pass your own threshold and fields with the raw API field names (`VOIP`, not `voip`):
+
+```python
+result = client.check_phone("+18176791808")
+
+if result.flagged(risk_threshold=85, flag_on=["VOIP", "risky", "recent_abuse"]):
+    reasons = result.flag_reasons(85, ["VOIP", "risky", "recent_abuse"])
+    ...
+```
+
+The defaults are available as `IpResult.DEFAULT_FLAG_ON`, `EmailResult.DEFAULT_FLAG_ON` and `PhoneResult.DEFAULT_FLAG_ON`.
+
+## Balance and your IP
+
+```python
+credits = client.balance()  # int, costs no credits
+ip = client.my_ip()  # str, the public IP your server calls from; no API key needed
+```
+
+## Errors
+
+Every exception the client raises is a `fraudnova.FraudNovaError`, so one `except` handles them all:
+
+```python
+from fraudnova import FraudNovaError, InsufficientCreditsError
+
+try:
+    result = client.check_ip(visitor_ip)
+except InsufficientCreditsError:
+    ...  # buy a credit pack in the FraudNova dashboard
+except FraudNovaError as error:
+    ...  # log it and let the request through, or hold it for review
+```
+
+| Exception | Status | When |
+| --- | --- | --- |
+| `AuthenticationError` | 401 | The API key is missing, invalid or revoked. |
+| `InsufficientCreditsError` | 402 | Your balance is too low for the check. |
+| `AccountSuspendedError` | 403 | The account is suspended. |
+| `ValidationError` | 422 | The API rejected the request parameters. |
+| `RateLimitError` | 429 | Too many requests, or too many checks in flight at once. `retry_after` and `is_concurrency_limit` tell you which. |
+| `UpstreamError` | 502, 503, 504 | The lookup failed. On a 503 the credit is refunded automatically and `credit_refunded` is `True`. |
+| `UnexpectedResponseError` | 2xx | The response could not be read as a FraudNova response. |
+| `ApiError` | any other error status | Base class of every exception with a status. `status_code`, `api_message` and `body` are on all of them. A 401, 402, 403 or 422 whose body is not a FraudNova JSON response (for example a proxy error page) is a plain `ApiError`. |
+| `TransportError` | none | The HTTP client failed, for example a timeout or DNS error. The original exception is `__cause__`. |
+| `InvalidArgumentError` | none | A value was empty or out of range; no request was sent. It is also a `ValueError`. |
+
+## Retries
+
+The client does not retry by default. To retry HTTP 429 responses, pass a `RetryPolicy`:
+
+```python
+from fraudnova import Client, RetryPolicy
+
+client = Client("fn_your_api_key", retry=RetryPolicy(max_attempts=3))
+```
+
+`max_attempts` counts the first attempt, so `3` means up to two retries. Only 429 is retried; every other error is raised right away. The wait is the `Retry-After` header when the response has one, otherwise a short schedule for the concurrency limit and a longer one for the rate limit. When the attempts run out, the `RateLimitError` is raised. A `Retry-After` longer than `max_retry_after` (60 seconds by default) is not waited for; the `RateLimitError` is raised right away. Batch requests are safe to retry, because a 429 is returned before any item is checked.
+
+Retries can make one call slow. With `RetryPolicy(max_attempts=3)` and the default `max_retry_after=60`, one call can sleep for up to about two minutes, plus three timeouts. Inside a web request, use a small `max_retry_after` (for example `2`) and a short `timeout`, and keep the full policy for background jobs.
+
+## Bring your own HTTP client
+
+Inject your own `httpx.Client`. Timeouts, proxies and TLS settings belong to the HTTP client, so set them there:
+
+```python
+import httpx
+from fraudnova import Client
+
+http = httpx.Client(timeout=5.0, proxy="http://proxy.internal:3128")
+client = Client("fn_your_api_key", http_client=http)
+```
+
+Without an injected client, the SDK creates its own `httpx.Client` with a 30 second timeout (change it with `Client(..., timeout=10.0)`).
+
+Use the client as a context manager, or call `close()`, to release connections when you are done. `close()` only closes an `httpx.Client` the SDK created; one you inject stays yours to close.
+
+```python
+with Client("fn_your_api_key") as client:
+    client.check_email("someone@example.com")
+```
+
+## Testing
+
+Inject an `httpx.Client` backed by `httpx.MockTransport`, so your tests send no real request:
+
+```python
+import httpx
+from fraudnova import Client
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(
+        200,
+        json={
+            "success": True,
+            "data": {"fraud_score": 12, "proxy": False},
+            "credits_remaining": 99,
+        },
+    )
+
+
+http = httpx.Client(transport=httpx.MockTransport(handler))
+client = Client("fn_test", http_client=http)
+
+assert client.check_ip("8.8.8.8").fraud_score == 12
+```
+
+## Credits and limits
+
+One check costs one credit, whichever type it is. Failed checks are refunded. You get free trial credits when you verify your email address, and you buy more as credit packs, with no subscription. A batch costs one credit per successful item.
+
+The API limits requests per minute for each key and checks in flight for each account. The current limits are in the [API documentation](https://fraudnova.com/docs).
+
+## Resources
+
+* [FraudNova API documentation](https://fraudnova.com/docs)
+* [Examples repository](https://github.com/dahleedam/fraudnova-examples)
+* [Status](https://fraudnova.com/status)
+* [Changelog](https://fraudnova.com/changelog)
+* Support: [support@fraudnova.com](mailto:support@fraudnova.com)
+
+## Licence
+
+Released under the MIT license. See [LICENSE](LICENSE).

fraudnova-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fraudnova/__init__.py,sha256=9B1-ldMYIXs5GASxQw89X2lGNatTaERiRHTSXc6J9YQ,1043
+fraudnova/_transport.py,sha256=SKvRjeJhZ9Fo7jCHI0fGHMl9shjfcTLplqw6-aS86Fc,3950
+fraudnova/_version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+fraudnova/client.py,sha256=MCLQgiBEmuWf4-zl7l9zIdUTh46pOzfi2N8ycRpDjiE,7697
+fraudnova/exceptions.py,sha256=9xCcDxhkvS288tN1pVxUHKhz_wVUD3rg-oadTIqJZ_Y,5276
+fraudnova/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fraudnova/results.py,sha256=LN1J5NBJlxtO0rVzHHTAg7PRfNbsxVPnbkonZfidhC0,11780
+fraudnova/retry.py,sha256=MXKpX9Zf70A6iZbD69PPoHXDQuQEcBwp6brvQF_gbYI,2387
+fraudnova-1.0.0.dist-info/METADATA,sha256=91525Ewa1hLjGEETfrhyX3yqDOhs9K1kT_jCNssiHk8,13308
+fraudnova-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fraudnova-1.0.0.dist-info/licenses/LICENSE,sha256=iBwexUBqLwwXvEiXfBlWhMzIQjbTcQqjPQGFf6uRkZI,1066
+fraudnova-1.0.0.dist-info/RECORD,,

fraudnova-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fraudnova-1.0.0.dist-info/licenses/LICENSE

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