inlineshield 1.0.1__tar.gz

inlineshield-1.0.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.1 (2026-11-03)
+
+- MIT licence (`LICENSE`, in the wheel and the sdist); `pyproject.toml` says `license = "MIT"` (SPDX; the sdist now builds with setuptools 77 or later).
+- `VerifyResult` and `SiteverifyResult` now declare `mailboxStatus` (`"exists" | "not_found" | "catch_all" | "unknown"`) and `linked` (the new `Linked` TypedDict: `groupId`, `size`, `strength`, `linkedToFraud`; or `None`). The fail-open results do not carry them.
+- The API already sent these fields and 1.0.0 passed them through; only the declared types change.
+
+## 1.0.0 (2026-11-03)
+
+- First release: `Client` with `verify`, `siteverify`, `feedback` and `get_review`; `verify_webhook`.
+- Fail-open by default (`fail_open`), a 3 s timeout (`timeout_ms`), retry of failed connections only (`max_retries`).
+- Typed errors: `AuthError`, `ApiError`, `UnavailableError`, `RateLimitError`, `QuotaError`, `WebhookVerificationError`.
+- Python 3.9 or later, standard library only.

inlineshield-1.0.1/LICENSE

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

inlineshield-1.0.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: inlineshield
+Version: 1.0.1
+Summary: Official Python client for the InlineShield sign-up screening API: verify, siteverify, feedback, review status and webhook signature checks.
+License-Expression: MIT
+License-File: LICENSE
+Project-URL: Documentation, https://inlineshield.io/docs/sdks/python/
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# inlineshield
+
+The official Python client for the [InlineShield](https://inlineshield.io) sign-up screening API.
+
+- Python 3.9 or later; standard library only (`urllib`, `hmac`, `json`); typed.
+- Fail-open by default: an outage never blocks your sign-ups.
+
+Docs: https://inlineshield.io/docs/sdks/python/
+
+## Install
+
+Until the package is on PyPI:
+
+```sh
+pip install https://inlineshield.io/downloads/sdk/inlineshield-1.0.1-py3-none-any.whl
+```
+
+## Use
+
+```python
+import os
+from inlineshield import Client, verify_webhook
+
+shield = Client(os.environ["INLINESHIELD_API_KEY"])  # bs_live_... or bs_test_...
+
+# With the browser script: redeem its token, fall back to a server-side screening.
+# Check `unavailable` first (fail-open: action "allow"), then `success`, then the error.
+result = shield.siteverify(token, email)
+if not result["unavailable"] and not result["success"]:
+    if result["error"] != "NO_TOKEN":
+        return reject(result["error"])  # INVALID_TOKEN, EXPIRED_TOKEN, ...
+    result = shield.verify(email, ip=visitor_ip, user_agent=visitor_user_agent)
+# result["action"]: "allow", "hold" or "block".
+
+shield.feedback(request_id, "fraud", category="bonus_abuse")
+review = shield.get_review(review_id)  # pending, approved or rejected
+
+event = verify_webhook(signature_header, raw_body, os.environ["INLINESHIELD_WEBHOOK_SECRET"])
+```
+
+Results are dicts with the API's field names, plus `unavailable`.
+
+## siteverify results
+
+Check `unavailable` first: it is true when InlineShield could not answer (fail-open: `action` is "allow" and `success` is false, because no token was redeemed). Otherwise `success` true carries the decision; on `error` NO_TOKEN screen with verify; on any other error reject the sign-up.
+
+## Options
+
+`Client(api_key=None, *, base_url=None, timeout_ms=3000, fail_open=True, max_retries=1)`
+
+- `api_key`: without one, `INLINESHIELD_API_KEY` from the environment.
+- `base_url`: default `INLINESHIELD_BASE_URL`, else `https://api.inlineshield.io`.
+- `fail_open=True`: when InlineShield cannot be reached, times out, answers 5xx, 429 or is over quota, the methods
+  return `{"unavailable": True, "error": ..., "action": "allow", ...}` instead of raising. `False`: they raise.
+- `timeout_ms` is a deadline for the whole request (the answer is read in a worker thread that is cut off at the
+  deadline); `base_url` must use https (plain http only for localhost).
+- `max_retries`: only a failed connection (nothing sent) is retried; never a timeout or an answer.
+
+A rate limit (429) or an exhausted quota also fails open by default: every further sign-up is admitted unscreened until the limit resets. To choose otherwise, check `error` on an unavailable result (`RATE_LIMIT_EXCEEDED`, `TEST_LIMIT`, `QUOTA_EXCEEDED`) and hold or reject those sign-ups, or turn fail-open off and handle the errors.
+
+## Errors
+
+All extend `InlineShieldError` (`code`, `status`):
+
+| Class | When |
+|---|---|
+| `AuthError` | 401, or 403 TENANT_SUSPENDED, or no key (MISSING_API_KEY). Always raised. |
+| `ApiError` | 400, 404, 422, or a redirect (UNEXPECTED_REDIRECT). Always raised. |
+| `UnavailableError` | TIMEOUT or UNAVAILABLE, with `fail_open=False`. |
+| `RateLimitError` | RATE_LIMIT_EXCEEDED or TEST_LIMIT (`retry_after`), with `fail_open=False`. |
+| `QuotaError` | QUOTA_EXCEEDED, with `fail_open=False`. |
+| `WebhookVerificationError` | NO_SECRET, MALFORMED_HEADER, TIMESTAMP_OUT_OF_RANGE, SIGNATURE_MISMATCH, INVALID_PAYLOAD. |
+
+Messages never contain the API key or an email address, and the SDK writes nothing to any output.
+
+## Webhooks
+
+`verify_webhook(signature_header, raw_body, secret, tolerance_sec=300)` checks `X-InlineShield-Signature`
+(`t=<seconds>,v1=<hex>`): HMAC-SHA256 of `<t>.<raw body>` with the whole `whsec_...` secret, compared in constant
+time, and `t` within `tolerance_sec` of now. Pass the raw body bytes (Flask: `request.get_data()`).
+
+## Licence
+
+MIT. See `LICENSE`.

inlineshield-1.0.1/README.md

@@ -0,0 +1,84 @@
+# inlineshield
+
+The official Python client for the [InlineShield](https://inlineshield.io) sign-up screening API.
+
+- Python 3.9 or later; standard library only (`urllib`, `hmac`, `json`); typed.
+- Fail-open by default: an outage never blocks your sign-ups.
+
+Docs: https://inlineshield.io/docs/sdks/python/
+
+## Install
+
+Until the package is on PyPI:
+
+```sh
+pip install https://inlineshield.io/downloads/sdk/inlineshield-1.0.1-py3-none-any.whl
+```
+
+## Use
+
+```python
+import os
+from inlineshield import Client, verify_webhook
+
+shield = Client(os.environ["INLINESHIELD_API_KEY"])  # bs_live_... or bs_test_...
+
+# With the browser script: redeem its token, fall back to a server-side screening.
+# Check `unavailable` first (fail-open: action "allow"), then `success`, then the error.
+result = shield.siteverify(token, email)
+if not result["unavailable"] and not result["success"]:
+    if result["error"] != "NO_TOKEN":
+        return reject(result["error"])  # INVALID_TOKEN, EXPIRED_TOKEN, ...
+    result = shield.verify(email, ip=visitor_ip, user_agent=visitor_user_agent)
+# result["action"]: "allow", "hold" or "block".
+
+shield.feedback(request_id, "fraud", category="bonus_abuse")
+review = shield.get_review(review_id)  # pending, approved or rejected
+
+event = verify_webhook(signature_header, raw_body, os.environ["INLINESHIELD_WEBHOOK_SECRET"])
+```
+
+Results are dicts with the API's field names, plus `unavailable`.
+
+## siteverify results
+
+Check `unavailable` first: it is true when InlineShield could not answer (fail-open: `action` is "allow" and `success` is false, because no token was redeemed). Otherwise `success` true carries the decision; on `error` NO_TOKEN screen with verify; on any other error reject the sign-up.
+
+## Options
+
+`Client(api_key=None, *, base_url=None, timeout_ms=3000, fail_open=True, max_retries=1)`
+
+- `api_key`: without one, `INLINESHIELD_API_KEY` from the environment.
+- `base_url`: default `INLINESHIELD_BASE_URL`, else `https://api.inlineshield.io`.
+- `fail_open=True`: when InlineShield cannot be reached, times out, answers 5xx, 429 or is over quota, the methods
+  return `{"unavailable": True, "error": ..., "action": "allow", ...}` instead of raising. `False`: they raise.
+- `timeout_ms` is a deadline for the whole request (the answer is read in a worker thread that is cut off at the
+  deadline); `base_url` must use https (plain http only for localhost).
+- `max_retries`: only a failed connection (nothing sent) is retried; never a timeout or an answer.
+
+A rate limit (429) or an exhausted quota also fails open by default: every further sign-up is admitted unscreened until the limit resets. To choose otherwise, check `error` on an unavailable result (`RATE_LIMIT_EXCEEDED`, `TEST_LIMIT`, `QUOTA_EXCEEDED`) and hold or reject those sign-ups, or turn fail-open off and handle the errors.
+
+## Errors
+
+All extend `InlineShieldError` (`code`, `status`):
+
+| Class | When |
+|---|---|
+| `AuthError` | 401, or 403 TENANT_SUSPENDED, or no key (MISSING_API_KEY). Always raised. |
+| `ApiError` | 400, 404, 422, or a redirect (UNEXPECTED_REDIRECT). Always raised. |
+| `UnavailableError` | TIMEOUT or UNAVAILABLE, with `fail_open=False`. |
+| `RateLimitError` | RATE_LIMIT_EXCEEDED or TEST_LIMIT (`retry_after`), with `fail_open=False`. |
+| `QuotaError` | QUOTA_EXCEEDED, with `fail_open=False`. |
+| `WebhookVerificationError` | NO_SECRET, MALFORMED_HEADER, TIMESTAMP_OUT_OF_RANGE, SIGNATURE_MISMATCH, INVALID_PAYLOAD. |
+
+Messages never contain the API key or an email address, and the SDK writes nothing to any output.
+
+## Webhooks
+
+`verify_webhook(signature_header, raw_body, secret, tolerance_sec=300)` checks `X-InlineShield-Signature`
+(`t=<seconds>,v1=<hex>`): HMAC-SHA256 of `<t>.<raw body>` with the whole `whsec_...` secret, compared in constant
+time, and `t` within `tolerance_sec` of now. Pass the raw body bytes (Flask: `request.get_data()`).
+
+## Licence
+
+MIT. See `LICENSE`.

inlineshield-1.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "inlineshield"
+version = "1.0.1"
+description = "Official Python client for the InlineShield sign-up screening API: verify, siteverify, feedback, review status and webhook signature checks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://inlineshield.io/docs/sdks/python/"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+inlineshield = ["py.typed"]

inlineshield-1.0.1/src/inlineshield/__init__.py

@@ -0,0 +1,30 @@
+"""inlineshield: the official Python client for the InlineShield sign-up screening API.
+
+Docs: https://inlineshield.io/docs/sdks/python/
+"""
+from ._client import DEFAULT_BASE_URL, Client
+from ._errors import (
+    ApiError,
+    AuthError,
+    InlineShieldError,
+    QuotaError,
+    RateLimitError,
+    UnavailableError,
+    WebhookVerificationError,
+)
+from ._version import __version__
+from ._webhook import verify_webhook
+
+__all__ = [
+    "Client",
+    "DEFAULT_BASE_URL",
+    "verify_webhook",
+    "InlineShieldError",
+    "AuthError",
+    "RateLimitError",
+    "QuotaError",
+    "UnavailableError",
+    "ApiError",
+    "WebhookVerificationError",
+    "__version__",
+]

inlineshield-1.0.1/src/inlineshield/_client.py

@@ -0,0 +1,409 @@
+"""The InlineShield API client (standard library only: urllib, json)."""
+import errno
+import http.client
+import json
+import math
+import os
+import re
+import socket
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional, Tuple, TypeVar, Union
+
+from ._errors import ApiError, AuthError, QuotaError, RateLimitError, UnavailableError
+from ._types import FeedbackResult, FeedbackTarget, ReviewResult, SiteverifyResult, VerifyResult
+from ._version import __version__
+from ._webhook import verify_webhook as _verify_webhook
+
+DEFAULT_BASE_URL = "https://api.inlineshield.io"
+_RETRY_DELAY_S = 0.15
+_EMAIL_LIKE = re.compile(r"[^\s@\"'<>]+@[^\s@\"'<>]+")
+_CODE = re.compile(r"[A-Z0-9_]{1,64}", re.ASCII)
+_T = TypeVar("_T")
+
+
+class _NotSent(Exception):
+    """A connection that failed before anything was sent: the only failure that is retried."""
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(detail)
+        self.detail = detail
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Never follow a redirect: the API key would go with it."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+def _tracking_opener(connections: list) -> urllib.request.OpenerDirector:
+    """An opener (no redirects, the environment's proxies) that records every connection it opens, so a request
+    still running at the deadline can be cut off by closing its socket."""
+
+    class _Http(urllib.request.HTTPHandler):
+        def http_open(self, req):  # type: ignore[no-untyped-def]
+            return self.do_open(self._connect, req)
+
+        def _connect(self, host, **kw):  # type: ignore[no-untyped-def]
+            conn = http.client.HTTPConnection(host, **kw)
+            connections.append(conn)
+            return conn
+
+    class _Https(urllib.request.HTTPSHandler):
+        def https_open(self, req):  # type: ignore[no-untyped-def]
+            return self.do_open(self._connect, req)
+
+        def _connect(self, host, **kw):  # type: ignore[no-untyped-def]
+            conn = http.client.HTTPSConnection(host, **kw)
+            connections.append(conn)
+            return conn
+
+    return urllib.request.build_opener(_NoRedirect, _Http, _Https)
+
+
+def _plain_http_allowed(url: str) -> bool:
+    """http:// only for this machine (local tests); anything else would send the key in clear text."""
+    return re.match(r"http://(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(/|$)", url, re.IGNORECASE) is not None
+
+
+def _non_empty(value: Any, what: str) -> str:
+    if not isinstance(value, str) or value.strip() == "":
+        raise ValueError("%s must be a non-empty string." % what)
+    return value
+
+
+class Client:
+    """The InlineShield API client. Server-side only: it holds your secret API key.
+
+    Example::
+
+        shield = Client(os.environ["INLINESHIELD_API_KEY"])
+        result = shield.verify(email, ip=ip, user_agent=user_agent)
+    """
+
+    __slots__ = ("_api_key", "base_url", "timeout_ms", "fail_open", "max_retries")
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout_ms: float = 3000,
+        fail_open: bool = True,
+        max_retries: int = 1,
+    ) -> None:
+        """
+        :param api_key: your secret API key (bs_live_... or bs_test_...). Without one, INLINESHIELD_API_KEY from the
+            environment.
+        :param base_url: the API origin. Default: INLINESHIELD_BASE_URL from the environment, else
+            https://api.inlineshield.io.
+        :param timeout_ms: the deadline of each request in milliseconds (default 3000): connecting, sending and
+            reading the whole answer. A DNS lookup that hangs is abandoned at the deadline too.
+        :param fail_open: True (default): when InlineShield cannot be reached, times out, answers 5xx, 429 or is over
+            quota, the methods return an "unavailable" result (``unavailable: True``, action "allow") instead of
+            raising. False: they raise UnavailableError, RateLimitError or QuotaError.
+        :param max_retries: retries after a failed connection (nothing was sent; default 1). Answers and timeouts are
+            never retried.
+        :raises AuthError: MISSING_API_KEY when there is no key at all.
+        """
+        if api_key is not None and not isinstance(api_key, str):
+            raise TypeError("api_key must be a string.")
+        key = api_key or os.environ.get("INLINESHIELD_API_KEY", "")
+        if not key:
+            raise AuthError(
+                "No InlineShield API key: pass one to Client() or set INLINESHIELD_API_KEY.", "MISSING_API_KEY", None
+            )
+        url = base_url if base_url is not None else (os.environ.get("INLINESHIELD_BASE_URL") or DEFAULT_BASE_URL)
+        if not isinstance(url, str) or not re.match(r"https?://[^\s/?#]+", url, re.IGNORECASE):
+            raise ValueError("base_url must be an http(s) URL.")
+        if url.lower().startswith("http://") and not _plain_http_allowed(url):
+            raise ValueError("base_url must use https:// (plain http only for localhost).")
+        if (isinstance(timeout_ms, bool) or not isinstance(timeout_ms, (int, float)) or not math.isfinite(timeout_ms)
+                or not timeout_ms > 0):
+            raise ValueError("timeout_ms must be a number of milliseconds above 0.")
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int) or max_retries < 0:
+            raise ValueError("max_retries must be an integer, 0 or more.")
+        if not isinstance(fail_open, bool):
+            raise TypeError("fail_open must be True or False.")
+        self._api_key = key
+        self.base_url = url.rstrip("/")
+        self.timeout_ms = timeout_ms
+        self.fail_open = fail_open
+        self.max_retries = max_retries
+
+    def __repr__(self) -> str:
+        return "Client(base_url=%r, timeout_ms=%r, fail_open=%r)" % (self.base_url, self.timeout_ms, self.fail_open)
+
+    # ── API ──────────────────────────────────────────────────────────────────
+
+    def verify(
+        self,
+        email: str,
+        *,
+        ip: Optional[str] = None,
+        user_agent: Optional[str] = None,
+        username: Optional[str] = None,
+        client_dwell_ms: Optional[float] = None,
+        honeypot: Optional[str] = None,
+    ) -> VerifyResult:
+        """Screen a sign-up on the server (POST /api/v1/verify).
+
+        Pass the player's IP and User-Agent from your incoming request; without an IP, InlineShield sees your server's.
+        """
+        body: Dict[str, Any] = {"email": _non_empty(email, "email")}
+        for key, value in (("ip", ip), ("userAgent", user_agent), ("username", username), ("honeypot", honeypot)):
+            if value is not None:
+                body[key] = str(value)
+        # An unmeasured dwell time is sent as nothing (unknown), never as 0 (which reads as a bot).
+        if isinstance(client_dwell_ms, (int, float)) and not isinstance(client_dwell_ms, bool) and math.isfinite(client_dwell_ms):
+            body["clientDwellMs"] = client_dwell_ms
+
+        def call() -> VerifyResult:
+            data = self._send("POST", "/api/v1/verify", body)
+            if not isinstance(data.get("decision"), str) or not isinstance(data.get("action"), str):
+                raise UnavailableError("InlineShield sent an answer without a decision.", "UNAVAILABLE", 200)
+            return dict(data, unavailable=False)  # type: ignore[return-value]
+
+        return self._fail_open(call, lambda code: {
+            "unavailable": True, "error": code, "requestId": None, "decision": "ALLOWED", "verdict": "ALLOWED",
+            "action": "allow", "recommendedAction": "allow", "riskScore": 0, "reasons": [], "triggers": [],
+        })
+
+    def siteverify(self, token: Optional[str], email: str) -> SiteverifyResult:
+        """Redeem the single-use token of the browser script (POST /api/v1/siteverify).
+
+        Check ``unavailable`` first: it is True when InlineShield could not answer (fail-open; ``action`` is "allow",
+        and ``success`` is False because no token was redeemed). Otherwise, ``success: True`` carries the decision; on
+        ``error == "NO_TOKEN"`` screen the sign-up with verify() instead; on the other errors reject it.
+
+        :param token: the betshield_token form field (None or "" when absent).
+        :param email: the email the player submitted: the one the token was issued for.
+        """
+        if token is not None and not isinstance(token, str):
+            raise TypeError("token must be a string.")
+        body = {"token": token or "", "email": _non_empty(email, "email")}
+
+        def call() -> SiteverifyResult:
+            data = self._send("POST", "/api/v1/siteverify", body)
+            if data.get("success") is False and data.get("error") == "QUOTA_EXCEEDED":
+                raise QuotaError("The InlineShield account is over its monthly quota (QUOTA_EXCEEDED).", "QUOTA_EXCEEDED", 200)
+            if not isinstance(data.get("success"), bool):
+                raise UnavailableError("InlineShield sent an unexpected answer.", "UNAVAILABLE", 200)
+            return dict(data, unavailable=False)  # type: ignore[return-value]
+
+        return self._fail_open(call, lambda code: {
+            "unavailable": True, "success": False, "error": code, "requestId": None, "decision": "ALLOWED",
+            "action": "allow", "recommendedAction": "allow", "riskScore": 0, "reasons": [],
+        })
+
+    def feedback(
+        self,
+        target: FeedbackTarget,
+        outcome: str,
+        *,
+        category: Optional[str] = None,
+        note: Optional[str] = None,
+    ) -> FeedbackResult:
+        """Report the real outcome of a screened sign-up (POST /api/v1/feedback), e.g. after a chargeback or a passed KYC.
+
+        :param target: the requestId InlineShield returned, or ``{"token": ...}`` (the /check token, for about a day).
+        :param outcome: "fraud" or "legit".
+        """
+        body: Dict[str, Any] = {}
+        if isinstance(target, str):
+            body["requestId"] = _non_empty(target, "request_id")
+        elif isinstance(target, dict) and "token" in target:
+            body["token"] = _non_empty(target["token"], "token")
+        elif isinstance(target, dict) and "requestId" in target:
+            body["requestId"] = _non_empty(target["requestId"], "requestId")
+        else:
+            raise TypeError('feedback() takes a requestId or {"token": ...}.')
+        body["outcome"] = outcome
+        if category is not None:
+            body["category"] = category
+        if note is not None:
+            body["note"] = note
+
+        def call() -> FeedbackResult:
+            return dict(self._send("POST", "/api/v1/feedback", body), unavailable=False)  # type: ignore[return-value]
+
+        return self._fail_open(call, lambda code: {"unavailable": True, "success": False, "error": code})
+
+    def get_review(self, review_id: str) -> ReviewResult:
+        """The status of a held sign-up (GET /api/v1/reviews/{reviewId}): pending, approved or rejected."""
+        rid = _non_empty(review_id, "review_id")
+
+        def call() -> ReviewResult:
+            path = "/api/v1/reviews/" + urllib.parse.quote(rid, safe="")
+            return dict(self._send("GET", path, None), unavailable=False)  # type: ignore[return-value]
+
+        return self._fail_open(call, lambda code: {
+            "unavailable": True, "error": code, "reviewId": rid, "status": "pending", "decisionReason": None,
+            "decidedAt": None, "expiresAt": None,
+        })
+
+    @staticmethod
+    def verify_webhook(
+        signature_header: Optional[str],
+        raw_body: Union[bytes, bytearray, memoryview, str],
+        secret: Optional[str],
+        tolerance_sec: float = 300,
+    ) -> Dict[str, Any]:
+        """Same as inlineshield.verify_webhook()."""
+        return _verify_webhook(signature_header, raw_body, secret, tolerance_sec)
+
+    # ── Transport ────────────────────────────────────────────────────────────
+
+    def _fail_open(self, call: Callable[[], _T], unavailable: Callable[[str], Any]) -> _T:
+        try:
+            return call()
+        except (UnavailableError, RateLimitError, QuotaError) as err:
+            if self.fail_open:
+                return unavailable(err.code)  # type: ignore[no-any-return]
+            raise
+
+    def _send(self, method: str, path: str, body: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                status, retry_after, raw = self._once(method, path, body)
+            except _NotSent as err:
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(_RETRY_DELAY_S)
+                    continue
+                raise UnavailableError("InlineShield could not be reached (%s)." % err.detail, "UNAVAILABLE", None) from None
+            return self._interpret(status, retry_after, raw)
+
+    def _once(self, method: str, path: str, body: Optional[Dict[str, Any]]) -> Tuple[int, Optional[str], bytes]:
+        """One request under a wall-clock deadline of timeout_ms: connecting, sending and reading the whole answer.
+
+        urllib's own timeout bounds each socket operation, not the request (an answer that trickles in would never
+        time out), so the request runs in a worker thread; at the deadline its socket is closed and TIMEOUT raised.
+        """
+        deadline = time.monotonic() + self.timeout_ms / 1000.0
+        connections: list = []
+        box: Dict[str, Any] = {}
+
+        def work() -> None:
+            try:
+                box["ok"] = self._exchange(method, path, body, connections)
+            except BaseException as err:  # noqa: BLE001 - re-raised in the caller's thread
+                box["err"] = err
+
+        worker = threading.Thread(target=work, name="inlineshield-request", daemon=True)
+        worker.start()
+        worker.join(max(0.0, deadline - time.monotonic()))
+        if worker.is_alive():
+            for conn in list(connections):
+                sock = getattr(conn, "sock", None)
+                try:
+                    if sock is not None:
+                        sock.shutdown(socket.SHUT_RDWR)
+                except OSError:
+                    pass
+                try:
+                    conn.close()
+                except Exception:  # noqa: BLE001 - closing a broken connection
+                    pass
+            raise self._timeout()
+        if "err" in box:
+            raise box["err"]
+        return box["ok"]  # type: ignore[no-any-return]
+
+    def _exchange(
+        self, method: str, path: str, body: Optional[Dict[str, Any]], connections: list
+    ) -> Tuple[int, Optional[str], bytes]:
+        """One request and its whole answer (in the worker thread of _once)."""
+        headers = {
+            "X-Api-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": "inlineshield-python/" + __version__,
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+        timeout = self.timeout_ms / 1000.0
+        try:
+            with _tracking_opener(connections).open(req, timeout=timeout) as resp:
+                return resp.status, resp.headers.get("Retry-After"), resp.read()
+        except urllib.error.HTTPError as err:
+            try:
+                raw = err.read()
+            except Exception:  # noqa: BLE001 - a broken error body is an empty one
+                raw = b""
+            finally:
+                err.close()
+            return err.code, err.headers.get("Retry-After") if err.headers else None, raw
+        except urllib.error.URLError as err:
+            reason = err.reason
+            if isinstance(reason, (socket.timeout, TimeoutError)):
+                raise self._timeout() from None
+            if isinstance(reason, (ConnectionRefusedError, socket.gaierror)) or (
+                isinstance(reason, OSError) and reason.errno in (errno.EHOSTUNREACH, errno.ENETUNREACH)
+            ):
+                raise _NotSent(type(reason).__name__) from None
+            raise UnavailableError(
+                "InlineShield could not be reached (%s)." % type(reason).__name__, "UNAVAILABLE", None
+            ) from None
+        except (socket.timeout, TimeoutError):
+            raise self._timeout() from None
+        except (OSError, ValueError, http.client.HTTPException) as err:
+            # Connection reset, an incomplete answer, a broken HTTP response.
+            raise UnavailableError(
+                "InlineShield could not be reached (%s)." % type(err).__name__, "UNAVAILABLE", None
+            ) from None
+
+    def _timeout(self) -> UnavailableError:
+        return UnavailableError("InlineShield did not answer within %s ms." % (self.timeout_ms,), "TIMEOUT", None)
+
+    def _interpret(self, status: int, retry_after_header: Optional[str], raw: bytes) -> Dict[str, Any]:
+        try:
+            parsed = json.loads(raw.decode("utf-8"))
+        except ValueError:
+            parsed = None
+        data = parsed if isinstance(parsed, dict) else None
+        if 200 <= status < 300:
+            if data is None:
+                raise UnavailableError(
+                    "InlineShield sent an answer that is not JSON (HTTP %d)." % status, "UNAVAILABLE", status
+                )
+            return data
+        code = data.get("error") if data is not None else None
+        if not isinstance(code, str) or not _CODE.fullmatch(code):
+            code = None
+        message = data.get("message") if data is not None else None
+        detail = (": " + self._redact(message)) if isinstance(message, str) else "."
+        what = "(HTTP %d%s)" % (status, " " + code if code else "")
+        if 300 <= status < 400:
+            raise ApiError(
+                "InlineShield answered with a redirect (HTTP %d); check base_url." % status, "UNEXPECTED_REDIRECT", status
+            )
+        if status == 401:
+            raise AuthError("InlineShield refused the API key %s%s" % (what, detail), code or "UNAUTHORIZED", status)
+        if status == 403 and code == "TENANT_SUSPENDED":
+            raise AuthError("The InlineShield account is suspended %s%s" % (what, detail), code, status)
+        if status == 402:
+            raise QuotaError(
+                "The InlineShield account is over its monthly quota %s%s" % (what, detail), "QUOTA_EXCEEDED", status
+            )
+        if status == 429:
+            ra = retry_after_header.strip() if isinstance(retry_after_header, str) else ""
+            retry_after = int(ra) if ra.isdigit() and ra.isascii() else None
+            raise RateLimitError(
+                "InlineShield rate limit %s%s" % (what, detail), code or "RATE_LIMIT_EXCEEDED", status, retry_after
+            )
+        if status >= 500:
+            raise UnavailableError("InlineShield is unavailable %s%s" % (what, detail), "UNAVAILABLE", status)
+        raise ApiError("InlineShield refused the request %s%s" % (what, detail), code or "HTTP_%d" % status, status)
+
+    def _redact(self, text: str) -> str:
+        """The API key and anything that looks like an email address never go into a message."""
+        return _EMAIL_LIKE.sub("[redacted]", text.replace(self._api_key, "[redacted]"))[:300]
+

inlineshield-1.0.1/src/inlineshield/_errors.py

@@ -0,0 +1,53 @@
+"""Typed errors.
+
+Every error the SDK raises on purpose is an InlineShieldError with a ``code`` (the API's error code, or one of the
+SDK's own) and the HTTP ``status`` that carried it (None when there was no answer). Messages never contain the API
+key or an email address.
+"""
+from typing import Optional
+
+
+class InlineShieldError(Exception):
+    """Base class of the SDK's errors."""
+
+    def __init__(self, message: str, code: str, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AuthError(InlineShieldError):
+    """The API key is missing, unknown, revoked or expired (401), or the account is suspended (403 TENANT_SUSPENDED).
+
+    Always raised, whatever fail_open says: it is a configuration error.
+    """
+
+
+class RateLimitError(InlineShieldError):
+    """429: RATE_LIMIT_EXCEEDED, or TEST_LIMIT for test keys. Raised only with fail_open=False."""
+
+    def __init__(self, message: str, code: str, status: Optional[int], retry_after: Optional[int]) -> None:
+        super().__init__(message, code, status)
+        self.retry_after = retry_after
+
+
+class QuotaError(InlineShieldError):
+    """The account is over its monthly quota (402, or QUOTA_EXCEEDED from /siteverify). Raised only with fail_open=False."""
+
+
+class UnavailableError(InlineShieldError):
+    """InlineShield could not be reached or did not answer in time (code TIMEOUT), or answered with a server error or
+    something that is not JSON (code UNAVAILABLE). Raised only with fail_open=False."""
+
+
+class ApiError(InlineShieldError):
+    """The API refused the request (400 BAD_REQUEST or INVALID_IP, 404 NOT_FOUND, 422 SCREENING_TOO_OLD, ...), or
+    answered with a redirect (UNEXPECTED_REDIRECT: check base_url). Always raised: the request needs fixing."""
+
+
+class WebhookVerificationError(InlineShieldError):
+    """verify_webhook() refused a delivery: NO_SECRET, MALFORMED_HEADER, TIMESTAMP_OUT_OF_RANGE, SIGNATURE_MISMATCH or
+    INVALID_PAYLOAD. Answer such a request with 400."""
+
+    def __init__(self, message: str, code: str) -> None:
+        super().__init__(message, code, None)

inlineshield-1.0.1/src/inlineshield/_types.py

@@ -0,0 +1,87 @@
+"""The shapes of the results (plain dicts, as the API sends them, plus ``unavailable``)."""
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+Verdict = Literal["ALLOWED", "QUARANTINED", "BLOCKED"]
+Action = Literal["allow", "hold", "block"]
+RecommendedAction = Literal["allow", "allow_no_bonus", "review", "block", "require_kyc"]
+UnavailableCode = Literal["UNAVAILABLE", "TIMEOUT", "RATE_LIMIT_EXCEEDED", "TEST_LIMIT", "QUOTA_EXCEEDED"]
+Outcome = Literal["fraud", "legit"]
+FeedbackCategory = Literal["bonus_abuse", "multi_account", "chargeback", "kyc_failed", "bot", "good_customer", "other"]
+MailboxStatus = Literal["exists", "not_found", "catch_all", "unknown"]
+"""The mailbox check of the address (an SMTP RCPT check; no message is ever sent)."""
+
+
+class Linked(TypedDict):
+    """Linked accounts: the earlier sign-ups to your account that a screening is linked to."""
+
+    groupId: Optional[str]
+    size: int
+    strength: Literal["strong", "possible"]
+    linkedToFraud: bool
+
+
+class VerifyResult(TypedDict, total=False):
+    """POST /api/v1/verify. With ``unavailable: True`` (fail-open) the action is "allow" and ``error`` says why."""
+
+    unavailable: bool
+    error: UnavailableCode
+    requestId: Optional[str]
+    decision: Verdict
+    verdict: Verdict
+    action: Action
+    recommendedAction: RecommendedAction
+    reviewId: str
+    riskScore: int
+    reasons: List[str]
+    triggers: List[str]
+    policyVersion: str
+    processingTimeMs: float
+    forwardedToDatabase: bool
+    emailAnalysis: Dict[str, Any]
+    botAnalysis: Dict[str, Any]
+    ipRisk: Dict[str, Any]
+    mailboxStatus: MailboxStatus
+    """Not in an ``unavailable`` result."""
+    linked: Optional[Linked]
+    """The linked-accounts summary, or None. Not in an ``unavailable`` result."""
+
+
+class SiteverifyResult(TypedDict, total=False):
+    """POST /api/v1/siteverify: ``success: True`` with the decision, or ``success: False`` with ``error``."""
+
+    unavailable: bool
+    success: bool
+    error: str
+    requestId: Optional[str]
+    decision: Verdict
+    action: Action
+    recommendedAction: RecommendedAction
+    reviewId: str
+    riskScore: int
+    reasons: List[str]
+    mailboxStatus: MailboxStatus
+    """With ``success: True`` only."""
+    linked: Optional[Linked]
+    """With ``success: True`` only: the linked-accounts summary, or None."""
+
+
+class FeedbackResult(TypedDict, total=False):
+    unavailable: bool
+    success: bool
+    error: UnavailableCode
+    outcome: Outcome
+    category: Optional[FeedbackCategory]
+    changed: bool
+
+
+class ReviewResult(TypedDict, total=False):
+    unavailable: bool
+    error: UnavailableCode
+    reviewId: str
+    status: Literal["pending", "approved", "rejected"]
+    decisionReason: Optional[Literal["operator", "expired"]]
+    decidedAt: Optional[str]
+    expiresAt: Optional[str]
+
+
+FeedbackTarget = Union[str, Dict[str, str]]

inlineshield-1.0.1/src/inlineshield/_version.py

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

inlineshield-1.0.1/src/inlineshield/_webhook.py

@@ -0,0 +1,61 @@
+"""Webhook signature verification."""
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Dict, Optional, Union
+
+from ._errors import WebhookVerificationError
+
+# X-InlineShield-Signature: exactly ``t=<unix seconds>,v1=<64 lower-case hex>``, as InlineShield sends it.
+_SIGNATURE_HEADER = re.compile(r"t=(\d+),v1=([0-9a-f]{64})", re.ASCII)
+
+
+def verify_webhook(
+    signature_header: Optional[str],
+    raw_body: Union[bytes, bytearray, memoryview, str],
+    secret: Optional[str],
+    tolerance_sec: float = 300,
+) -> Dict[str, Any]:
+    """Verify a webhook delivery and return its parsed body.
+
+    The signature is HMAC-SHA256, keyed with your endpoint's whole secret (whsec_...), over ``<t>.<raw body>``,
+    hex-encoded, and compared in constant time. A delivery whose t is more than ``tolerance_sec`` seconds (default
+    300) before or after now is refused, so a captured delivery cannot be replayed later.
+
+    :param signature_header: the X-InlineShield-Signature header.
+    :param raw_body: the exact request body bytes (or the string they decode to), before any JSON parsing.
+    :param secret: your endpoint's signing secret.
+    :raises WebhookVerificationError: NO_SECRET, MALFORMED_HEADER, TIMESTAMP_OUT_OF_RANGE, SIGNATURE_MISMATCH or
+        INVALID_PAYLOAD.
+    """
+    if not isinstance(secret, str) or secret == "":
+        raise WebhookVerificationError("No webhook signing secret: never verify with an empty key.", "NO_SECRET")
+    if isinstance(tolerance_sec, bool) or not isinstance(tolerance_sec, (int, float)) or not tolerance_sec >= 0:
+        raise ValueError("tolerance_sec must be a number of seconds, 0 or more.")
+    if isinstance(raw_body, str):
+        body = raw_body.encode("utf-8")
+    elif isinstance(raw_body, (bytes, bytearray, memoryview)):
+        body = bytes(raw_body)
+    else:
+        raise TypeError("raw_body must be the raw request body: bytes or a string.")
+    m = _SIGNATURE_HEADER.fullmatch(signature_header) if isinstance(signature_header, str) else None
+    if m is None:
+        raise WebhookVerificationError(
+            "Malformed X-InlineShield-Signature header (expected t=<seconds>,v1=<hex>).", "MALFORMED_HEADER"
+        )
+    if abs(int(time.time()) - int(m.group(1))) > tolerance_sec:
+        raise WebhookVerificationError(
+            "The webhook timestamp is more than %s seconds away from now." % (tolerance_sec,), "TIMESTAMP_OUT_OF_RANGE"
+        )
+    expected = hmac.new(secret.encode("utf-8"), m.group(1).encode("ascii") + b"." + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, m.group(2)):
+        raise WebhookVerificationError("The webhook signature does not match.", "SIGNATURE_MISMATCH")
+    try:
+        event = json.loads(body.decode("utf-8"))
+    except ValueError:
+        event = None
+    if not isinstance(event, dict):
+        raise WebhookVerificationError("The webhook body is not a JSON object.", "INVALID_PAYLOAD")
+    return event