layercall 1.0.0__tar.gz

layercall-1.0.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: layercall
+Version: 1.0.0
+Summary: Official LayerCall client — score an IP, email, phone, domain or a whole signup for fraud in one call. Zero dependencies.
+Author: LayerCall
+License: MIT
+Project-URL: Homepage, https://www.layercall.com
+Project-URL: Documentation, https://www.layercall.com/docs
+Project-URL: Source, https://github.com/hirajha/layercall-sdk
+Keywords: fraud,fraud-detection,vpn-detection,proxy-detection,tor,email-validation,disposable-email,phone-validation,ip-lookup,bot-detection,signup-fraud,risk-score
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# layercall
+
+Official Python client for [LayerCall](https://www.layercall.com) — score an
+IP, email, phone number, domain, or a whole signup for fraud in a single call.
+
+**Zero dependencies.** Standard library only. A trust check sits on your signup
+path, which is the worst place to add a dependency tree that has to resolve
+against whatever your app already pins.
+
+```bash
+pip install layercall
+```
+
+## Quick start
+
+```python
+import os
+from layercall import LayerCall
+
+lc = LayerCall(os.environ["LAYERCALL_API_KEY"])
+
+result = lc.score_user(ip=request.remote_addr, email=form["email"])
+
+if result["verdict"] == "review":
+    send_otp(form["email"])      # a real user clears it themselves
+elif result["verdict"] == "block":
+    queue_for_review(result)
+```
+
+[Get a free API key](https://www.layercall.com/get-key) — 1,000 lookups a
+month, no card.
+
+## Acting on a verdict
+
+| Verdict | Do this | Not this |
+| --- | --- | --- |
+| `allow` | Let them through | — |
+| `review` | **Step up** — OTP, SMS, 3-D Secure | Don't reject. This band includes ordinary VPN users. |
+| `block` | Reject, or send to a human queue | Don't reject silently |
+
+Prefer a challenge over a rejection. A real user clears it in seconds; an
+attacker cannot. A false positive then costs friction instead of a customer.
+
+**Already send an OTP to everyone?** Passwordless products can't use an email
+code as a step-up — it's already mandatory. Score after sign-in and use a
+different lever: a limited account state, a delayed payout, or a review queue.
+
+## Methods
+
+```python
+lc.score_ip("185.220.101.1")
+lc.verify_email("someone@mailinator.com")
+lc.lookup_phone("+14155552671")
+lc.lookup_phone("4155552671", country="US")
+lc.score_domain("example.com")
+lc.score_user(ip=ip, email=email, phone=phone, device_id=device_id)
+lc.batch("email", ["a@x.com", "b@y.com"])       # up to 500
+```
+
+Every method takes `strictness` (`0` lenient → `3` paranoid). It moves the
+verdict thresholds only; the risk score never changes, so you can re-tune
+without re-scoring anything.
+
+## None means unknown, never "no"
+
+```python
+signals = lc.score_domain("example.de")["signals"]
+signals["newly_registered"]   # None — .de publishes no RDAP, so age is unknown
+```
+
+`None` means we could not determine it. It is **not** a negative finding.
+Treating it as "established" is exactly the mistake the field exists to
+prevent.
+
+Same for `mailbox_exists`: Gmail and Yahoo accept mail for addresses that do
+not exist, so we return `None` rather than a guess.
+
+## Errors
+
+```python
+from layercall import LayerCallError
+
+try:
+    lc.score_ip(ip)
+except LayerCallError as err:
+    if err.is_quota:   # 402 — out of quota or spend cap reached
+        ...
+    if err.is_auth:    # 401/403 — bad or revoked key
+        ...
+    print(err.request_id)   # quote this in a support ticket
+except Exception:
+    pass   # fail open: let the signup through
+```
+
+429s and 5xx retry automatically (2 attempts, short backoff). Other 4xx fail
+fast — they will not succeed on a retry.
+
+## Server-side only
+
+An API key in anything a user can read is public and bills to your account.
+
+## License
+
+MIT

layercall-1.0.0/README.md

@@ -0,0 +1,104 @@
+# layercall
+
+Official Python client for [LayerCall](https://www.layercall.com) — score an
+IP, email, phone number, domain, or a whole signup for fraud in a single call.
+
+**Zero dependencies.** Standard library only. A trust check sits on your signup
+path, which is the worst place to add a dependency tree that has to resolve
+against whatever your app already pins.
+
+```bash
+pip install layercall
+```
+
+## Quick start
+
+```python
+import os
+from layercall import LayerCall
+
+lc = LayerCall(os.environ["LAYERCALL_API_KEY"])
+
+result = lc.score_user(ip=request.remote_addr, email=form["email"])
+
+if result["verdict"] == "review":
+    send_otp(form["email"])      # a real user clears it themselves
+elif result["verdict"] == "block":
+    queue_for_review(result)
+```
+
+[Get a free API key](https://www.layercall.com/get-key) — 1,000 lookups a
+month, no card.
+
+## Acting on a verdict
+
+| Verdict | Do this | Not this |
+| --- | --- | --- |
+| `allow` | Let them through | — |
+| `review` | **Step up** — OTP, SMS, 3-D Secure | Don't reject. This band includes ordinary VPN users. |
+| `block` | Reject, or send to a human queue | Don't reject silently |
+
+Prefer a challenge over a rejection. A real user clears it in seconds; an
+attacker cannot. A false positive then costs friction instead of a customer.
+
+**Already send an OTP to everyone?** Passwordless products can't use an email
+code as a step-up — it's already mandatory. Score after sign-in and use a
+different lever: a limited account state, a delayed payout, or a review queue.
+
+## Methods
+
+```python
+lc.score_ip("185.220.101.1")
+lc.verify_email("someone@mailinator.com")
+lc.lookup_phone("+14155552671")
+lc.lookup_phone("4155552671", country="US")
+lc.score_domain("example.com")
+lc.score_user(ip=ip, email=email, phone=phone, device_id=device_id)
+lc.batch("email", ["a@x.com", "b@y.com"])       # up to 500
+```
+
+Every method takes `strictness` (`0` lenient → `3` paranoid). It moves the
+verdict thresholds only; the risk score never changes, so you can re-tune
+without re-scoring anything.
+
+## None means unknown, never "no"
+
+```python
+signals = lc.score_domain("example.de")["signals"]
+signals["newly_registered"]   # None — .de publishes no RDAP, so age is unknown
+```
+
+`None` means we could not determine it. It is **not** a negative finding.
+Treating it as "established" is exactly the mistake the field exists to
+prevent.
+
+Same for `mailbox_exists`: Gmail and Yahoo accept mail for addresses that do
+not exist, so we return `None` rather than a guess.
+
+## Errors
+
+```python
+from layercall import LayerCallError
+
+try:
+    lc.score_ip(ip)
+except LayerCallError as err:
+    if err.is_quota:   # 402 — out of quota or spend cap reached
+        ...
+    if err.is_auth:    # 401/403 — bad or revoked key
+        ...
+    print(err.request_id)   # quote this in a support ticket
+except Exception:
+    pass   # fail open: let the signup through
+```
+
+429s and 5xx retry automatically (2 attempts, short backoff). Other 4xx fail
+fast — they will not succeed on a retry.
+
+## Server-side only
+
+An API key in anything a user can read is public and bills to your account.
+
+## License
+
+MIT

layercall-1.0.0/layercall/__init__.py

@@ -0,0 +1,231 @@
+"""Official LayerCall client.
+
+Score an IP, email, phone number, domain, or a whole signup for fraud in a
+single call.
+
+Zero dependencies, standard library only. A trust check sits on the signup
+path, which is the worst place in an application to introduce a dependency
+tree that has to be resolved against whatever the host app already pins.
+
+Test keys return synthetic data
+-------------------------------
+A key beginning ``tl_test_`` returns fabricated scores and signals, derived
+from the value you sent rather than from anything known about it. Response
+shapes, error codes and your own allow/block rules behave exactly as in
+production, so integration tests against a test key are valid — the numbers
+are not. Those responses carry ``test_mode: True`` and a ``test_mode_note``.
+
+    result = client.score_ip("8.8.8.8")
+    if result.get("test_mode"):
+        ...  # pointed at a test key, do not assert on risk_score
+
+Use a ``tl_live_`` key to score real values.
+See https://www.layercall.com/docs/test-mode
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Literal, Mapping, Sequence
+
+__version__ = "1.0.0"
+__all__ = ["LayerCall", "LayerCallError"]
+
+Verdict = Literal["allow", "review", "block"]
+Strictness = Literal[0, 1, 2, 3]
+
+_DEFAULT_BASE = "https://www.layercall.com"
+
+
+class LayerCallError(Exception):
+    """A non-2xx response. Branch on ``status`` or ``code``."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+    @property
+    def is_quota(self) -> bool:
+        """Quota exhausted or spend cap reached — upgrade or raise the cap."""
+        return self.status == 402
+
+    @property
+    def is_auth(self) -> bool:
+        """Bad or revoked key."""
+        return self.status in (401, 403)
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"LayerCallError(status={self.status}, code={self.code!r}, message={self!s})"
+
+
+class LayerCall:
+    """Client for the LayerCall API.
+
+    Server-side only. An API key in anything a user can read is public, and it
+    bills to your account.
+
+        lc = LayerCall(os.environ["LAYERCALL_API_KEY"])
+        result = lc.score_user(ip=request.remote_addr, email=form["email"])
+        if result["verdict"] == "review":
+            send_otp(form["email"])       # a real user clears it themselves
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE,
+        timeout: float = 5.0,
+        retries: int = 2,
+    ) -> None:
+        if not api_key:
+            raise ValueError("LayerCall: api_key is required.")
+        self._key = api_key
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+
+    # -- transport --------------------------------------------------------
+
+    def _request(
+        self,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = self._base + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        data = json.dumps(body).encode() if body is not None else None
+        last_exc: Exception | None = None
+
+        for attempt in range(self._retries + 1):
+            req = urllib.request.Request(
+                url,
+                data=data,
+                method="POST" if data is not None else "GET",
+                headers={
+                    "X-Api-Key": self._key,
+                    "Content-Type": "application/json",
+                    "User-Agent": f"layercall-python/{__version__}",
+                },
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                    return json.loads(resp.read().decode() or "{}")
+            except urllib.error.HTTPError as exc:
+                try:
+                    payload = json.loads(exc.read().decode() or "{}")
+                except Exception:
+                    payload = {}
+                err = LayerCallError(
+                    payload.get("error") or f"HTTP {exc.code}",
+                    exc.code,
+                    payload.get("code"),
+                    payload.get("request_id"),
+                )
+                # A 4xx other than 429 fails identically on retry. Surfacing it
+                # now beats spending a signup path's latency budget proving it.
+                if not (exc.code == 429 or exc.code >= 500) or attempt == self._retries:
+                    raise err from None
+                last_exc = err
+            except Exception as exc:  # timeouts, DNS, connection resets
+                last_exc = exc
+                if attempt == self._retries:
+                    break
+            # Short exponential backoff — this sits in front of a user.
+            time.sleep(0.15 * (2**attempt))
+
+        raise last_exc if last_exc else RuntimeError("LayerCall: request failed")
+
+    # -- endpoints --------------------------------------------------------
+
+    def score_ip(self, ip: str, *, strictness: Strictness | None = None) -> dict[str, Any]:
+        """VPN, proxy, Tor, datacenter, geolocation and ASN for an IP."""
+        return self._request("/v1/score/ip", query={"ip": ip, "strictness": strictness})
+
+    def verify_email(self, email: str, *, strictness: Strictness | None = None) -> dict[str, Any]:
+        """Syntax, MX, disposable, role account, homograph and domain age."""
+        return self._request("/v1/verify/email", query={"email": email, "strictness": strictness})
+
+    def lookup_phone(
+        self,
+        phone: str,
+        *,
+        country: str | None = None,
+        strictness: Strictness | None = None,
+    ) -> dict[str, Any]:
+        """Numbering-plan validation worldwide. ``country`` only for national format."""
+        return self._request(
+            "/v1/lookup/phone",
+            query={"phone": phone, "country": country, "strictness": strictness},
+        )
+
+    def score_domain(self, domain: str) -> dict[str, Any]:
+        """RDAP registration date, registrar, MX/SPF/DMARC, risky TLD."""
+        return self._request("/v1/score/domain", query={"domain": domain})
+
+    def score_user(
+        self,
+        *,
+        ip: str | None = None,
+        email: str | None = None,
+        phone: str | None = None,
+        phone_country: str | None = None,
+        domain: str | None = None,
+        device_id: str | None = None,
+        strictness: Strictness | None = None,
+    ) -> dict[str, Any]:
+        """Score a whole signup. A hard block on one component is never averaged away."""
+        payload = {
+            k: v
+            for k, v in {
+                "ip": ip,
+                "email": email,
+                "phone": phone,
+                "phone_country": phone_country,
+                "domain": domain,
+                "device_id": device_id,
+                "strictness": strictness,
+            }.items()
+            if v is not None
+        }
+        if not payload:
+            raise ValueError("score_user: provide at least one of ip, email or phone.")
+        return self._request("/v1/score/user", body=payload)
+
+    def batch(
+        self,
+        type: Literal["ip", "email", "phone", "domain"],
+        items: Sequence[str],
+        *,
+        strictness: Strictness | None = None,
+        phone_country: str | None = None,
+    ) -> dict[str, Any]:
+        """Up to 500 values of one type. Each item carries its own error."""
+        if len(items) > 500:
+            raise ValueError(
+                f"batch: {len(items)} items exceeds the limit of 500 — send several batches."
+            )
+        payload: dict[str, Any] = {"type": type, "items": list(items)}
+        if strictness is not None:
+            payload["strictness"] = strictness
+        if phone_country is not None:
+            payload["phone_country"] = phone_country
+        return self._request("/v1/batch", body=payload)

layercall-1.0.0/layercall.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: layercall
+Version: 1.0.0
+Summary: Official LayerCall client — score an IP, email, phone, domain or a whole signup for fraud in one call. Zero dependencies.
+Author: LayerCall
+License: MIT
+Project-URL: Homepage, https://www.layercall.com
+Project-URL: Documentation, https://www.layercall.com/docs
+Project-URL: Source, https://github.com/hirajha/layercall-sdk
+Keywords: fraud,fraud-detection,vpn-detection,proxy-detection,tor,email-validation,disposable-email,phone-validation,ip-lookup,bot-detection,signup-fraud,risk-score
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# layercall
+
+Official Python client for [LayerCall](https://www.layercall.com) — score an
+IP, email, phone number, domain, or a whole signup for fraud in a single call.
+
+**Zero dependencies.** Standard library only. A trust check sits on your signup
+path, which is the worst place to add a dependency tree that has to resolve
+against whatever your app already pins.
+
+```bash
+pip install layercall
+```
+
+## Quick start
+
+```python
+import os
+from layercall import LayerCall
+
+lc = LayerCall(os.environ["LAYERCALL_API_KEY"])
+
+result = lc.score_user(ip=request.remote_addr, email=form["email"])
+
+if result["verdict"] == "review":
+    send_otp(form["email"])      # a real user clears it themselves
+elif result["verdict"] == "block":
+    queue_for_review(result)
+```
+
+[Get a free API key](https://www.layercall.com/get-key) — 1,000 lookups a
+month, no card.
+
+## Acting on a verdict
+
+| Verdict | Do this | Not this |
+| --- | --- | --- |
+| `allow` | Let them through | — |
+| `review` | **Step up** — OTP, SMS, 3-D Secure | Don't reject. This band includes ordinary VPN users. |
+| `block` | Reject, or send to a human queue | Don't reject silently |
+
+Prefer a challenge over a rejection. A real user clears it in seconds; an
+attacker cannot. A false positive then costs friction instead of a customer.
+
+**Already send an OTP to everyone?** Passwordless products can't use an email
+code as a step-up — it's already mandatory. Score after sign-in and use a
+different lever: a limited account state, a delayed payout, or a review queue.
+
+## Methods
+
+```python
+lc.score_ip("185.220.101.1")
+lc.verify_email("someone@mailinator.com")
+lc.lookup_phone("+14155552671")
+lc.lookup_phone("4155552671", country="US")
+lc.score_domain("example.com")
+lc.score_user(ip=ip, email=email, phone=phone, device_id=device_id)
+lc.batch("email", ["a@x.com", "b@y.com"])       # up to 500
+```
+
+Every method takes `strictness` (`0` lenient → `3` paranoid). It moves the
+verdict thresholds only; the risk score never changes, so you can re-tune
+without re-scoring anything.
+
+## None means unknown, never "no"
+
+```python
+signals = lc.score_domain("example.de")["signals"]
+signals["newly_registered"]   # None — .de publishes no RDAP, so age is unknown
+```
+
+`None` means we could not determine it. It is **not** a negative finding.
+Treating it as "established" is exactly the mistake the field exists to
+prevent.
+
+Same for `mailbox_exists`: Gmail and Yahoo accept mail for addresses that do
+not exist, so we return `None` rather than a guess.
+
+## Errors
+
+```python
+from layercall import LayerCallError
+
+try:
+    lc.score_ip(ip)
+except LayerCallError as err:
+    if err.is_quota:   # 402 — out of quota or spend cap reached
+        ...
+    if err.is_auth:    # 401/403 — bad or revoked key
+        ...
+    print(err.request_id)   # quote this in a support ticket
+except Exception:
+    pass   # fail open: let the signup through
+```
+
+429s and 5xx retry automatically (2 attempts, short backoff). Other 4xx fail
+fast — they will not succeed on a retry.
+
+## Server-side only
+
+An API key in anything a user can read is public and bills to your account.
+
+## License
+
+MIT

layercall-1.0.0/layercall.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+layercall/__init__.py
+layercall.egg-info/PKG-INFO
+layercall.egg-info/SOURCES.txt
+layercall.egg-info/dependency_links.txt
+layercall.egg-info/top_level.txt

layercall-1.0.0/layercall.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

layercall-1.0.0/layercall.egg-info/top_level.txt

@@ -0,0 +1 @@
+layercall

layercall-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "layercall"
+version = "1.0.0"
+description = "Official LayerCall client — score an IP, email, phone, domain or a whole signup for fraud in one call. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "LayerCall" }]
+keywords = ["fraud", "fraud-detection", "vpn-detection", "proxy-detection", "tor", "email-validation", "disposable-email", "phone-validation", "ip-lookup", "bot-detection", "signup-fraud", "risk-score"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://www.layercall.com"
+Documentation = "https://www.layercall.com/docs"
+Source = "https://github.com/hirajha/layercall-sdk"
+
+[tool.setuptools.packages.find]
+include = ["layercall*"]

layercall-1.0.0/setup.cfg

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