sentinelsup 0.1.0__py3-none-any.whl

sentinel/__init__.py

@@ -0,0 +1,156 @@
+"""
+Sentinel Python SDK — thin, dependency-free wrapper around the Sentinel
+fraud detection API at https://sntlhq.com/v1/evaluate.
+
+Usage:
+    from sentinel import Sentinel
+    s = Sentinel(api_key=os.environ["SENTINEL_KEY"])
+    result = s.evaluate(token=request.json["sentinelToken"])
+    if result.is_suspicious:
+        abort(403)
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+from urllib import error, request
+
+DEFAULT_ENDPOINT = "https://sntlhq.com"
+DEFAULT_TIMEOUT = 5.0
+__version__ = "0.1.0"
+
+
+class SentinelError(Exception):
+    """Raised on any Sentinel API or transport failure."""
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body or {}
+
+
+@dataclass
+class EvaluateResult:
+    """Structured response from /v1/evaluate."""
+
+    decision: Optional[str] = None
+    risk_score: Optional[int] = None
+    ip: Optional[str] = None
+    country: Optional[str] = None
+    asn: Optional[str] = None
+    asn_org: Optional[str] = None
+    network: Dict[str, Any] = field(default_factory=dict)
+    device: Dict[str, Any] = field(default_factory=dict)
+    reasons: list = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_suspicious(self) -> bool:
+        """True if the decision is anything other than 'allow'."""
+        return self.decision is not None and self.decision != "allow"
+
+    @property
+    def is_blocked(self) -> bool:
+        return self.decision == "block"
+
+
+class Sentinel:
+    """Sentinel API client. Pass an API key from https://sntlhq.com/dashboard."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        api_key = api_key or os.environ.get("SENTINEL_API_KEY")
+        if not api_key or not isinstance(api_key, str):
+            raise SentinelError(
+                "Sentinel: api_key is required. "
+                "Pass it explicitly or set SENTINEL_API_KEY. "
+                "Get one free at https://sntlhq.com/signup"
+            )
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+
+    def evaluate(
+        self,
+        token: str,
+        fingerprint_event_id: Optional[str] = None,
+    ) -> EvaluateResult:
+        """Evaluate a visitor session for fraud signals.
+
+        Args:
+            token: Sentinel client-side token from the frontend SDK.
+            fingerprint_event_id: Optional Fingerprint event id for device signals.
+
+        Returns:
+            EvaluateResult with decision, risk_score, network, device, and reasons.
+
+        Raises:
+            SentinelError: on network failure, timeout, or non-2xx response.
+        """
+        if not token or not isinstance(token, str):
+            raise SentinelError(
+                "Sentinel.evaluate: token (client-side Sentinel token) is required"
+            )
+
+        payload: Dict[str, Any] = {"token": token}
+        if fingerprint_event_id:
+            payload["fingerprintEventId"] = fingerprint_event_id
+
+        body = json.dumps(payload).encode("utf-8")
+        req = request.Request(
+            f"{self.endpoint}/v1/evaluate",
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"sentinel-python/{__version__}",
+            },
+        )
+
+        try:
+            with request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                data = json.loads(raw) if raw else {}
+        except error.HTTPError as e:
+            try:
+                err_body = json.loads(e.read().decode("utf-8"))
+            except Exception:
+                err_body = {}
+            msg = err_body.get("error") if isinstance(err_body, dict) else None
+            raise SentinelError(
+                f"Sentinel: API returned {e.code}"
+                + (f" — {msg}" if msg else ""),
+                status=e.code,
+                body=err_body,
+            ) from None
+        except error.URLError as e:
+            raise SentinelError(f"Sentinel: network error — {e.reason}") from None
+        except Exception as e:
+            raise SentinelError(f"Sentinel: unexpected error — {e}") from None
+
+        return EvaluateResult(
+            decision=data.get("decision"),
+            risk_score=data.get("risk_score"),
+            ip=data.get("ip"),
+            country=data.get("country"),
+            asn=data.get("asn"),
+            asn_org=data.get("asn_org"),
+            network=data.get("network") or {},
+            device=data.get("device") or {},
+            reasons=data.get("reasons") or [],
+            raw=data,
+        )
+
+
+__all__ = ["Sentinel", "SentinelError", "EvaluateResult", "__version__"]

sentinelsup-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: sentinelsup
+Version: 0.1.0
+Summary: Sentinel — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response.
+Project-URL: Homepage, https://sntlhq.com
+Project-URL: Documentation, https://sntlhq.com/api
+Project-URL: Repository, https://github.com/sentinelsup/sentinel-python
+Project-URL: Issues, https://github.com/sentinelsup/sentinel-python/issues
+Author-email: Sentinel Edge Networks LTD <support@sntlhq.com>
+License: MIT
+License-File: LICENSE
+Keywords: antidetect-browser,api,bot-detection,device-fingerprinting,fraud-detection,proxy-detection,sentinel,vpn-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Sentinel Python SDK
+
+Real-time fraud, VPN, proxy, and bot detection — free tier, sub-40ms global response.
+
+Zero dependencies. Just the standard library.
+
+## Install
+
+```bash
+pip install sentinelsup
+```
+
+## Quick start
+
+```python
+import os
+from sentinel import Sentinel
+
+s = Sentinel(api_key=os.environ["SENTINEL_API_KEY"])
+
+result = s.evaluate(token=request.json["sentinelToken"])
+
+if result.is_suspicious:
+    return abort(403, "Sentinel flagged this session")
+
+print(result.decision)        # 'allow' | 'review' | 'block'
+print(result.risk_score)      # 0..100
+print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True, ...}
+print(result.reasons)         # ['ip_in_known_vpn_range', 'datacenter_asn', ...]
+```
+
+## Get your API key
+
+Sign up at [sntlhq.com/signup](https://sntlhq.com/signup) — free, no credit card.
+
+## Flask example — block VPN/proxy signups
+
+```python
+from flask import Flask, request, abort, jsonify
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+@app.route("/signup", methods=["POST"])
+def signup():
+    data = request.get_json()
+    try:
+        result = sentinel.evaluate(token=data["sentinelToken"])
+    except SentinelError as e:
+        # Fail open OR fail closed — your call. Logged either way.
+        app.logger.warning("Sentinel error: %s", e)
+        result = None
+
+    if result and result.is_blocked:
+        abort(403, "Signup blocked")
+
+    # ... your normal signup flow
+    return jsonify({"ok": True})
+```
+
+## Django example — middleware for high-value endpoints
+
+```python
+from django.http import JsonResponse
+from sentinel import Sentinel
+
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+class FraudCheckMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if request.path.startswith("/api/checkout"):
+            token = request.META.get("HTTP_X_SENTINEL_TOKEN")
+            if token:
+                try:
+                    result = sentinel.evaluate(token=token)
+                    if result.is_blocked:
+                        return JsonResponse({"error": "blocked"}, status=403)
+                except Exception:
+                    pass  # fail open
+        return self.get_response(request)
+```
+
+## Configuration
+
+```python
+Sentinel(
+    api_key="sk_live_...",          # required (or via SENTINEL_API_KEY env var)
+    endpoint="https://sntlhq.com",  # override for testing
+    timeout=5.0,                    # seconds
+)
+```
+
+## Response shape
+
+```python
+@dataclass
+class EvaluateResult:
+    decision: str | None        # 'allow' | 'review' | 'block'
+    risk_score: int | None      # 0..100
+    ip: str | None
+    country: str | None         # ISO-2
+    asn: str | None             # 'AS16509'
+    asn_org: str | None         # 'Amazon.com, Inc.'
+    network: dict               # {vpn, proxy, datacenter, anonymous, residential}
+    device: dict                # {headless, automation, fingerprint_age_days}
+    reasons: list[str]
+    raw: dict                   # full upstream response
+
+    is_suspicious: bool         # True if decision != 'allow'
+    is_blocked: bool            # True if decision == 'block'
+```
+
+## Errors
+
+All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+
+```python
+from sentinel import Sentinel, SentinelError
+
+try:
+    result = sentinel.evaluate(token=tok)
+except SentinelError as e:
+    if e.status == 429:
+        # back off
+        pass
+    elif e.status and 400 <= e.status < 500:
+        # bad input, won't recover by retrying
+        pass
+    else:
+        # transient — retry once or fail open
+        pass
+```
+
+## Try the API without signing up
+
+```bash
+curl https://sntlhq.com/v1/evaluate/sample?scenario=vpn
+```
+
+Or use the [interactive playground](https://sntlhq.com/api#playground).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sentinelsup-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+sentinel/__init__.py,sha256=wL5SAk19iw6NiOtk412o5qF6auLtUOfj7qiUwumcW0o,5265
+sentinelsup-0.1.0.dist-info/METADATA,sha256=AA96z-2OP_RMFNJZ_FWmqC5x1UVMrNW4qz4eJbapIJs,5330
+sentinelsup-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sentinelsup-0.1.0.dist-info/licenses/LICENSE,sha256=jjWOHwHW6MDmLG8090VDWh61uzewugSs3UyHm03_CF4,1104
+sentinelsup-0.1.0.dist-info/RECORD,,

sentinelsup-0.1.0.dist-info/WHEEL

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

sentinelsup-0.1.0.dist-info/licenses/LICENSE

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