sentinelsup 0.1.0__tar.gz → 0.2.2__tar.gz

sentinelsup-0.2.2/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: sentinelsup
+Version: 0.2.2
+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
+
+# sentinelsup — Sentinel Python SDK
+
+Official Python SDK for [Sentinel](https://sntlhq.com) — a real-time fraud detection API that flags VPNs, residential proxies, antidetect browsers (Kameleo, GoLogin, Multilogin), Tor exit nodes, and AI bots in under 40 ms.
+
+[![PyPI](https://img.shields.io/pypi/v/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
+[![license](https://img.shields.io/pypi/l/sentinelsup.svg)](./LICENSE)
+
+Zero dependencies — just the standard library. Works with Flask, Django, FastAPI, or bare `urllib`.
+
+## Set up with AI (fastest)
+
+Using Claude Code, Cursor, Copilot, or any AI coding assistant? Paste this one
+prompt and it wires the whole integration — frontend script, backend check,
+env var, and a test:
+
+> Fetch https://sntlhq.com/integrate.md and follow it to add Sentinel fraud
+> protection to this app — protect signup, login, and checkout. My API key
+> is sk_live_YOUR_KEY; put it in a SENTINEL_KEY env var, never in
+> client-side code. Then show me how to test it.
+
+[`integrate.md`](https://sntlhq.com/integrate.md) is the canonical
+machine-readable integration guide, kept in sync with the live API.
+
+## Install
+
+```bash
+pip install sentinelsup
+```
+
+Python 3.8+. Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
+
+## Quick start
+
+```python
+import os
+from sentinel import Sentinel
+
+s = Sentinel(api_key=os.environ["SENTINEL_KEY"])  # or omit — reads the env var itself
+
+result = s.evaluate(token=request.json["sentinelToken"])  # token from the frontend SDK
+
+if result.is_blocked:            # decision == 'block'
+    abort(403)
+
+print(result.decision)        # 'allow' | 'review' | 'block' — route on this
+print(result.risk_score)      # 0..100
+print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True, ...}
+print(result.reasons)         # ['vpn_detected', 'datacenter_asn', ...]
+```
+
+Check the signup email against the disposable-domain feed (checked
+transiently, never stored), or look up an arbitrary IP with no browser
+token at all:
+
+```python
+result = s.evaluate(token=tok, email=data["email"])
+if result.raw.get("email", {}).get("disposable"):
+    ...  # burner domain — decision is escalated allow → review
+
+info = s.lookup("185.220.101.34")   # GET /v1/lookup/{ip} — same key & quota
+print(info["verdict"])              # 'allow' | 'review' | 'block'
+print(info["signals"])              # {'vpn': ..., 'proxied': ..., 'tor': ..., 'dch': ..., 'anon': ...}
+```
+
+## What you get back
+
+`evaluate()` returns an `EvaluateResult` dataclass:
+
+```python
+@dataclass
+class EvaluateResult:
+    decision: str | None        # 'allow' | 'review' | 'block'
+    risk_score: int | None      # 0..100
+    ip: str | None
+    country: str | None         # ISO-2
+    network: dict               # {vpn, proxy, datacenter, anonymous, tor, residential, service}
+    device: dict                # antidetect / automation / emulator signals
+    reasons: list[str]          # machine-readable codes
+    email: dict | None          # {disposable: bool} — present when you passed email=
+    decision_source: str | None # 'rules' | 'exception' when your policy matched
+    engine_decision: str | None # engine's own verdict when policy changed the decision
+    test: bool                  # True for test-token / test-key calls
+    raw: dict                   # full upstream response
+
+    is_suspicious: bool         # True if decision != 'allow'
+    is_blocked: bool            # True if decision == 'block'
+```
+
+Try the live sample (same shape, no key needed):
+
+```bash
+curl "https://sntlhq.com/v1/evaluate/sample?scenario=vpn"
+```
+
+Or use the [interactive playground](https://sntlhq.com/api#playground).
+
+## Frontend setup
+
+Add the Sentinel SDK to your frontend. One script loads **both** layers —
+network (VPN/proxy/datacenter) and device (antidetect/bot/tampering):
+
+```html
+<script async src="https://sntlhq.com/assets/sentinel.js"></script>
+
+<!-- Add class="monocle-enriched" to any form you want evaluated -->
+<form class="monocle-enriched" id="signup-form">
+  <!-- The SDK injects both:
+       <input type="hidden" name="monocle"     value="eyJ...">  (network)
+       <input type="hidden" name="sentinel_fp" value="a1b2..."> (device) -->
+</form>
+```
+
+Forward both fields to your backend with the form submission and pass them to
+`evaluate()` as `token` and `fingerprint_event_id` — without the second one,
+the device-layer signals (antidetect, automation, emulator) never fire. For
+fetch/XHR submissions, collect them explicitly:
+
+```js
+const { token, fingerprintEventId } = await window.Sentinel.collect();
+```
+
+## Examples
+
+### Flask — block VPN/proxy signups
+
+```python
+from flask import Flask, request, abort, jsonify
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_KEY (or 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 — middleware for high-value endpoints
+
+```python
+from django.http import JsonResponse
+from sentinel import Sentinel
+
+sentinel = Sentinel()  # reads SENTINEL_KEY (or 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)
+```
+
+Runnable versions live in [`examples/`](./examples/).
+
+## API
+
+### `Sentinel(api_key=None, endpoint="https://sntlhq.com", timeout=5.0)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | `$SENTINEL_KEY` (falls back to `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
+| `endpoint` | `https://sntlhq.com` | Override base URL (for testing) |
+| `timeout` | `5.0` | Per-request timeout in seconds |
+
+### `sentinel.evaluate(token, fingerprint_event_id=None, account_id=None, email=None)`
+
+Returns `EvaluateResult`. Raises `SentinelError` on network/API failure.
+
+- `fingerprint_event_id` — adds the `device` signal block (antidetect, automation, emulator, …).
+- `account_id` — your own user id for this session; enables multi-accounting detection (`device.linked_accounts` / `device.multi_account`).
+- `email` — adds `email.disposable` to the raw response; burner domains escalate `allow` to `review`.
+
+### `sentinel.lookup(ip)`
+
+Returns the raw response dict for any public IPv4/IPv6 address (wraps `GET /v1/lookup/{ip}`): `verdict` (`allow`/`review`/`block`), `risk_score` (0–100), `known`, `signals` (`{vpn, proxied, tor, dch, anon}` or `None`), `network` (`{asn, org, country, city}`), `latency_ms`. Shares the per-key hourly quota with `evaluate()`. `known: False` means our feeds hold no data — it is **not** a clean guarantee.
+
+## Testing
+
+Deterministic test tokens exercise your allow / review / block handling end-to-end — no browser needed. Test calls are authenticated and rate-limited like real ones but never billed, stored, or webhooked, and the response carries `test=True`:
+
+```python
+result = s.evaluate(token="test_vpn")       # also: test_clean, test_proxy, test_datacenter, test_tor
+assert result.decision == "review"
+assert result.test
+```
+
+No account yet? The public sandbox key accepts the same test tokens:
+
+```python
+s = Sentinel(api_key="sk_test_sandbox")     # CI/staging — nothing billed, nothing stored
+```
+
+Every account also has a personal `sk_test_...` key (Settings → API Key) that runs the *complete* live pipeline — real tokens, your rules and exception pins included — while events stay flagged as test and never count toward usage or webhooks.
+
+## 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:
+        pass    # back off
+    elif e.status and 400 <= e.status < 500:
+        pass    # bad input, won't recover by retrying
+    else:
+        pass    # transient — retry once or fail open
+```
+
+## Rate limits
+
+Free tier: **1,000 requests/hour** per API key. No monthly cap, no credit
+card. Upgrade at [sntlhq.com](https://sntlhq.com) when you need more.
+
+## What Sentinel detects
+
+VPNs (commercial + self-hosted) · residential proxies (Bright Data, IPRoyal,
+and similar networks) · datacenter IPs · Tor exit nodes · antidetect browsers
+(Kameleo, GoLogin, Multilogin, Dolphin{anty}, AdsPower) · headless browsers
+and automation (Puppeteer, Playwright, Selenium) · AI agents · emulators and
+virtual machines · browser tampering.
+
+## Related
+
+- **Node.js SDK** — [`@sentinelsup/sdk`](https://github.com/sentinelsup/sentinel-node) on npm
+- **API docs** — [sntlhq.com/api](https://sntlhq.com/api)
+- **Free IP lookup tool** — [sntlhq.com/ip-lookup](https://sntlhq.com/ip-lookup)
+
+## License
+
+MIT © [Sentinel Edge Networks LTD](https://sntlhq.com). See [LICENSE](LICENSE).

sentinelsup-0.2.2/README.md

@@ -0,0 +1,257 @@
+# sentinelsup — Sentinel Python SDK
+
+Official Python SDK for [Sentinel](https://sntlhq.com) — a real-time fraud detection API that flags VPNs, residential proxies, antidetect browsers (Kameleo, GoLogin, Multilogin), Tor exit nodes, and AI bots in under 40 ms.
+
+[![PyPI](https://img.shields.io/pypi/v/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sentinelsup.svg)](https://pypi.org/project/sentinelsup/)
+[![license](https://img.shields.io/pypi/l/sentinelsup.svg)](./LICENSE)
+
+Zero dependencies — just the standard library. Works with Flask, Django, FastAPI, or bare `urllib`.
+
+## Set up with AI (fastest)
+
+Using Claude Code, Cursor, Copilot, or any AI coding assistant? Paste this one
+prompt and it wires the whole integration — frontend script, backend check,
+env var, and a test:
+
+> Fetch https://sntlhq.com/integrate.md and follow it to add Sentinel fraud
+> protection to this app — protect signup, login, and checkout. My API key
+> is sk_live_YOUR_KEY; put it in a SENTINEL_KEY env var, never in
+> client-side code. Then show me how to test it.
+
+[`integrate.md`](https://sntlhq.com/integrate.md) is the canonical
+machine-readable integration guide, kept in sync with the live API.
+
+## Install
+
+```bash
+pip install sentinelsup
+```
+
+Python 3.8+. Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
+
+## Quick start
+
+```python
+import os
+from sentinel import Sentinel
+
+s = Sentinel(api_key=os.environ["SENTINEL_KEY"])  # or omit — reads the env var itself
+
+result = s.evaluate(token=request.json["sentinelToken"])  # token from the frontend SDK
+
+if result.is_blocked:            # decision == 'block'
+    abort(403)
+
+print(result.decision)        # 'allow' | 'review' | 'block' — route on this
+print(result.risk_score)      # 0..100
+print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True, ...}
+print(result.reasons)         # ['vpn_detected', 'datacenter_asn', ...]
+```
+
+Check the signup email against the disposable-domain feed (checked
+transiently, never stored), or look up an arbitrary IP with no browser
+token at all:
+
+```python
+result = s.evaluate(token=tok, email=data["email"])
+if result.raw.get("email", {}).get("disposable"):
+    ...  # burner domain — decision is escalated allow → review
+
+info = s.lookup("185.220.101.34")   # GET /v1/lookup/{ip} — same key & quota
+print(info["verdict"])              # 'allow' | 'review' | 'block'
+print(info["signals"])              # {'vpn': ..., 'proxied': ..., 'tor': ..., 'dch': ..., 'anon': ...}
+```
+
+## What you get back
+
+`evaluate()` returns an `EvaluateResult` dataclass:
+
+```python
+@dataclass
+class EvaluateResult:
+    decision: str | None        # 'allow' | 'review' | 'block'
+    risk_score: int | None      # 0..100
+    ip: str | None
+    country: str | None         # ISO-2
+    network: dict               # {vpn, proxy, datacenter, anonymous, tor, residential, service}
+    device: dict                # antidetect / automation / emulator signals
+    reasons: list[str]          # machine-readable codes
+    email: dict | None          # {disposable: bool} — present when you passed email=
+    decision_source: str | None # 'rules' | 'exception' when your policy matched
+    engine_decision: str | None # engine's own verdict when policy changed the decision
+    test: bool                  # True for test-token / test-key calls
+    raw: dict                   # full upstream response
+
+    is_suspicious: bool         # True if decision != 'allow'
+    is_blocked: bool            # True if decision == 'block'
+```
+
+Try the live sample (same shape, no key needed):
+
+```bash
+curl "https://sntlhq.com/v1/evaluate/sample?scenario=vpn"
+```
+
+Or use the [interactive playground](https://sntlhq.com/api#playground).
+
+## Frontend setup
+
+Add the Sentinel SDK to your frontend. One script loads **both** layers —
+network (VPN/proxy/datacenter) and device (antidetect/bot/tampering):
+
+```html
+<script async src="https://sntlhq.com/assets/sentinel.js"></script>
+
+<!-- Add class="monocle-enriched" to any form you want evaluated -->
+<form class="monocle-enriched" id="signup-form">
+  <!-- The SDK injects both:
+       <input type="hidden" name="monocle"     value="eyJ...">  (network)
+       <input type="hidden" name="sentinel_fp" value="a1b2..."> (device) -->
+</form>
+```
+
+Forward both fields to your backend with the form submission and pass them to
+`evaluate()` as `token` and `fingerprint_event_id` — without the second one,
+the device-layer signals (antidetect, automation, emulator) never fire. For
+fetch/XHR submissions, collect them explicitly:
+
+```js
+const { token, fingerprintEventId } = await window.Sentinel.collect();
+```
+
+## Examples
+
+### Flask — block VPN/proxy signups
+
+```python
+from flask import Flask, request, abort, jsonify
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_KEY (or 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 — middleware for high-value endpoints
+
+```python
+from django.http import JsonResponse
+from sentinel import Sentinel
+
+sentinel = Sentinel()  # reads SENTINEL_KEY (or 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)
+```
+
+Runnable versions live in [`examples/`](./examples/).
+
+## API
+
+### `Sentinel(api_key=None, endpoint="https://sntlhq.com", timeout=5.0)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | `$SENTINEL_KEY` (falls back to `$SENTINEL_API_KEY`) | Your key starting with `sk_live_` |
+| `endpoint` | `https://sntlhq.com` | Override base URL (for testing) |
+| `timeout` | `5.0` | Per-request timeout in seconds |
+
+### `sentinel.evaluate(token, fingerprint_event_id=None, account_id=None, email=None)`
+
+Returns `EvaluateResult`. Raises `SentinelError` on network/API failure.
+
+- `fingerprint_event_id` — adds the `device` signal block (antidetect, automation, emulator, …).
+- `account_id` — your own user id for this session; enables multi-accounting detection (`device.linked_accounts` / `device.multi_account`).
+- `email` — adds `email.disposable` to the raw response; burner domains escalate `allow` to `review`.
+
+### `sentinel.lookup(ip)`
+
+Returns the raw response dict for any public IPv4/IPv6 address (wraps `GET /v1/lookup/{ip}`): `verdict` (`allow`/`review`/`block`), `risk_score` (0–100), `known`, `signals` (`{vpn, proxied, tor, dch, anon}` or `None`), `network` (`{asn, org, country, city}`), `latency_ms`. Shares the per-key hourly quota with `evaluate()`. `known: False` means our feeds hold no data — it is **not** a clean guarantee.
+
+## Testing
+
+Deterministic test tokens exercise your allow / review / block handling end-to-end — no browser needed. Test calls are authenticated and rate-limited like real ones but never billed, stored, or webhooked, and the response carries `test=True`:
+
+```python
+result = s.evaluate(token="test_vpn")       # also: test_clean, test_proxy, test_datacenter, test_tor
+assert result.decision == "review"
+assert result.test
+```
+
+No account yet? The public sandbox key accepts the same test tokens:
+
+```python
+s = Sentinel(api_key="sk_test_sandbox")     # CI/staging — nothing billed, nothing stored
+```
+
+Every account also has a personal `sk_test_...` key (Settings → API Key) that runs the *complete* live pipeline — real tokens, your rules and exception pins included — while events stay flagged as test and never count toward usage or webhooks.
+
+## 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:
+        pass    # back off
+    elif e.status and 400 <= e.status < 500:
+        pass    # bad input, won't recover by retrying
+    else:
+        pass    # transient — retry once or fail open
+```
+
+## Rate limits
+
+Free tier: **1,000 requests/hour** per API key. No monthly cap, no credit
+card. Upgrade at [sntlhq.com](https://sntlhq.com) when you need more.
+
+## What Sentinel detects
+
+VPNs (commercial + self-hosted) · residential proxies (Bright Data, IPRoyal,
+and similar networks) · datacenter IPs · Tor exit nodes · antidetect browsers
+(Kameleo, GoLogin, Multilogin, Dolphin{anty}, AdsPower) · headless browsers
+and automation (Puppeteer, Playwright, Selenium) · AI agents · emulators and
+virtual machines · browser tampering.
+
+## Related
+
+- **Node.js SDK** — [`@sentinelsup/sdk`](https://github.com/sentinelsup/sentinel-node) on npm
+- **API docs** — [sntlhq.com/api](https://sntlhq.com/api)
+- **Free IP lookup tool** — [sntlhq.com/ip-lookup](https://sntlhq.com/ip-lookup)
+
+## License
+
+MIT © [Sentinel Edge Networks LTD](https://sntlhq.com). See [LICENSE](LICENSE).

{sentinelsup-0.1.0 → sentinelsup-0.2.2}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 # would install a stranger's code. "sentinelsup" matches the npm scope
 # (@sentinelsup/sdk).
 name = "sentinelsup"
-version = "0.1.0"
+version = "0.2.2"
 description = "Sentinel — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response."
 readme = "README.md"
 requires-python = ">=3.8"

{sentinelsup-0.1.0 → sentinelsup-0.2.2}/sentinel/__init__.py

@@ -4,9 +4,9 @@ fraud detection API at https://sntlhq.com/v1/evaluate.
 
 Usage:
     from sentinel import Sentinel
-    s = Sentinel(api_key=os.environ["SENTINEL_KEY"])
+    s = Sentinel()  # reads SENTINEL_KEY or SENTINEL_API_KEY from the env
     result = s.evaluate(token=request.json["sentinelToken"])
-    if result.is_suspicious:
+    if result.is_blocked:
         abort(403)
 """
 
@@ -14,11 +14,11 @@ import json
 import os
 from dataclasses import dataclass, field
 from typing import Any, Dict, Optional
-from urllib import error, request
+from urllib import error, parse, request
 
 DEFAULT_ENDPOINT = "https://sntlhq.com"
 DEFAULT_TIMEOUT = 5.0
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 
 class SentinelError(Exception):
@@ -43,11 +43,13 @@ class EvaluateResult:
     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)
+    email: Optional[Dict[str, Any]] = None
+    decision_source: Optional[str] = None
+    engine_decision: Optional[str] = None
+    test: bool = False
     raw: Dict[str, Any] = field(default_factory=dict)
 
     @property
@@ -69,48 +71,30 @@ class Sentinel:
         endpoint: str = DEFAULT_ENDPOINT,
         timeout: float = DEFAULT_TIMEOUT,
     ) -> None:
-        api_key = api_key or os.environ.get("SENTINEL_API_KEY")
+        # SENTINEL_KEY is the name every doc surface uses; SENTINEL_API_KEY
+        # is kept for existing installs that already adopted it.
+        api_key = api_key or os.environ.get("SENTINEL_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. "
+                "Pass it explicitly or set SENTINEL_KEY. "
                 "Get one free at https://sntlhq.com/signup"
             )
         self.api_key = api_key
         self.endpoint = endpoint.rstrip("/")
         self.timeout = timeout
 
-    def evaluate(
+    def _request(
         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")
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Shared transport: auth header, timeout, JSON parsing, error mapping."""
+        body = json.dumps(payload).encode("utf-8") if payload is not None else None
         req = request.Request(
-            f"{self.endpoint}/v1/evaluate",
+            f"{self.endpoint}{path}",
             data=body,
-            method="POST",
+            method="POST" if payload is not None else "GET",
             headers={
                 "Authorization": f"Bearer {self.api_key}",
                 "Content-Type": "application/json",
@@ -121,7 +105,7 @@ class Sentinel:
         try:
             with request.urlopen(req, timeout=self.timeout) as resp:
                 raw = resp.read().decode("utf-8")
-                data = json.loads(raw) if raw else {}
+                return json.loads(raw) if raw else {}
         except error.HTTPError as e:
             try:
                 err_body = json.loads(e.read().decode("utf-8"))
@@ -139,18 +123,86 @@ class Sentinel:
         except Exception as e:
             raise SentinelError(f"Sentinel: unexpected error — {e}") from None
 
+    def evaluate(
+        self,
+        token: str,
+        fingerprint_event_id: Optional[str] = None,
+        account_id: Optional[str] = None,
+        email: 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.
+            account_id: Optional account/user id — enables multi-accounting
+                detection (device.linked_accounts / device.multi_account).
+            email: Optional signup email. Adds ``email.disposable`` to the raw
+                response (burner domains escalate allow to review). Checked
+                transiently — never stored or logged.
+
+        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
+        if account_id:
+            payload["accountId"] = account_id
+        if email:
+            payload["email"] = email
+
+        data = self._request("/v1/evaluate", payload)
+
         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 [],
+            email=data.get("email"),
+            decision_source=data.get("decision_source"),
+            engine_decision=data.get("engine_decision"),
+            test=bool(data.get("test")),
             raw=data,
         )
 
+    def lookup(self, ip: str) -> Dict[str, Any]:
+        """Look up an arbitrary public IP address — no browser token needed.
+
+        Wraps ``GET /v1/lookup/{ip}``. Useful for batch scoring, log
+        enrichment, and server-side screening. Shares the per-key hourly
+        quota with :meth:`evaluate`.
+
+        Args:
+            ip: Public IPv4 or IPv6 address, e.g. ``"185.220.101.34"``.
+
+        Returns:
+            The raw response dict: ``verdict`` ('allow' | 'review' | 'block'),
+            ``risk_score`` (0-100), ``known``, ``signals``
+            ({vpn, proxied, tor, dch, anon} or None), ``network``
+            ({asn, org, country, city}), ``latency_ms``. Note ``known: False``
+            means our feeds hold no data for the IP — it is NOT a clean
+            guarantee.
+
+        Raises:
+            SentinelError: on network failure, timeout, or non-2xx response.
+        """
+        if not ip or not isinstance(ip, str):
+            raise SentinelError(
+                "Sentinel.lookup: ip (public IPv4 or IPv6 address) is required"
+            )
+        return self._request(f"/v1/lookup/{parse.quote(ip.strip(), safe='')}")
+
 
 __all__ = ["Sentinel", "SentinelError", "EvaluateResult", "__version__"]

sentinelsup-0.1.0/PKG-INFO

@@ -1,177 +0,0 @@
-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/README.md

@@ -1,148 +0,0 @@
-# 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).