sentinelsup 0.2.2__tar.gz → 0.2.4__tar.gz

sentinelsup-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: Python SDK
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m unittest discover -s tests -v
+      - name: Build and check distributions
+        if: matrix.python == '3.14'
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+          python -m pip install --no-deps dist/*.whl
+          cd "$RUNNER_TEMP"
+          python -c "from sentinel import Sentinel, SentinelError; assert Sentinel('sk_test_fixture').api_key == 'sk_test_fixture'"

{sentinelsup-0.2.2 → sentinelsup-0.2.4}/.gitignore

@@ -1,7 +1,7 @@
-__pycache__/
-*.py[cod]
-*.egg-info/
-build/
-dist/
-.venv/
-.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/

{sentinelsup-0.2.2 → sentinelsup-0.2.4}/LICENSE

@@ -1,21 +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.
+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.

{sentinelsup-0.2.2 → sentinelsup-0.2.4}/PKG-INFO

@@ -1,12 +1,12 @@
 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>
+Version: 0.2.4
+Summary: Official Maskbreak SDK for browser-backed fraud checks and cloud/Tor IP lookups.
+Project-URL: Homepage, https://maskbreak.com
+Project-URL: Documentation, https://maskbreak.com/api
+Project-URL: Repository, https://github.com/sentinelsup/maskbreak-python
+Project-URL: Issues, https://github.com/sentinelsup/maskbreak-python/issues
+Author-email: Sentinel Edge Networks LTD <support@maskbreak.com>
 License: MIT
 License-File: LICENSE
 Keywords: antidetect-browser,api,bot-detection,device-fingerprinting,fraud-detection,proxy-detection,sentinel,vpn-detection
@@ -27,9 +27,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 
-# sentinelsup — Sentinel Python SDK
+# sentinelsup — Maskbreak 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.
+Official Python SDK for [Maskbreak](https://maskbreak.com). Evaluate SDK-backed
+visits for network and browser risk signals, or look up a public IP for cloud
+range and Tor signals. These are different evidence sources, not interchangeable
+checks. VPN/proxy service names are returned when known; a VPN alone routes to
+review under the default policy, not automatic blocking.
 
 [![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/)
@@ -37,18 +41,18 @@ Official Python SDK for [Sentinel](https://sntlhq.com) — a real-time fraud det
 
 Zero dependencies — just the standard library. Works with Flask, Django, FastAPI, or bare `urllib`.
 
-## Set up with AI (fastest)
+## Set up with an AI assistant
 
 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.
+> Fetch https://maskbreak.com/integrate.md and follow it to add Maskbreak fraud
+> protection to this app — protect signup, login, and checkout. Read the API key
+> from the server-only SENTINEL_KEY environment variable; I will configure the
+> secret separately. Never put it in client-side code. Show me how to test it.
 
-[`integrate.md`](https://sntlhq.com/integrate.md) is the canonical
+[`integrate.md`](https://maskbreak.com/integrate.md) is the canonical
 machine-readable integration guide, kept in sync with the live API.
 
 ## Install
@@ -57,7 +61,7 @@ machine-readable integration guide, kept in sync with the live API.
 pip install sentinelsup
 ```
 
-Python 3.8+. Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
+Python 3.8+. Get a free API key (no credit card) at [maskbreak.com/signup](https://maskbreak.com/signup).
 
 ## Quick start
 
@@ -67,7 +71,10 @@ 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
+result = s.evaluate(
+    token=request.json["sentinelToken"],
+    fingerprint_event_id=request.json.get("fingerprintEventId"),
+)
 
 if result.is_blocked:            # decision == 'block'
     abort(403)
@@ -78,6 +85,11 @@ print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True
 print(result.reasons)         # ['vpn_detected', 'datacenter_asn', ...]
 ```
 
+This is a handler fragment, not a complete signup implementation. Route `review`
+to your verification/review flow; only `allow` is an approval. Keep API keys on
+the server. An unavailable device layer or `raw["degraded"]` is not proof of a
+clean visit; `degraded` describes the network layer only.
+
 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:
@@ -94,7 +106,8 @@ print(info["signals"])              # {'vpn': ..., 'proxied': ..., 'tor': ..., '
 
 ## What you get back
 
-`evaluate()` returns an `EvaluateResult` dataclass:
+`evaluate()` returns an `EvaluateResult` dataclass. The type sketch below uses
+Python 3.10+ annotation syntax for readability; the package minimum stays 3.8:
 
 ```python
 @dataclass
@@ -112,25 +125,25 @@ class EvaluateResult:
     test: bool                  # True for test-token / test-key calls
     raw: dict                   # full upstream response
 
-    is_suspicious: bool         # True if decision != 'allow'
+    is_suspicious: bool         # True for a non-null decision other than '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"
+curl "https://maskbreak.com/v1/evaluate/sample?scenario=vpn"
 ```
 
-Or use the [interactive playground](https://sntlhq.com/api#playground).
+Or use the [interactive playground](https://maskbreak.com/api#playground).
 
 ## Frontend setup
 
-Add the Sentinel SDK to your frontend. One script loads **both** layers —
+Add the Maskbreak 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>
+<script async src="https://maskbreak.com/assets/sentinel.js"></script>
 
 <!-- Add class="monocle-enriched" to any form you want evaluated -->
 <form class="monocle-enriched" id="signup-form">
@@ -142,7 +155,7 @@ network (VPN/proxy/datacenter) and device (antidetect/bot/tampering):
 
 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
+the device-layer signals (antidetect, automation, emulator) are unavailable. For
 fetch/XHR submissions, collect them explicitly:
 
 ```js
@@ -151,7 +164,7 @@ const { token, fingerprintEventId } = await window.Sentinel.collect();
 
 ## Examples
 
-### Flask — block VPN/proxy signups
+### Flask — route signup decisions
 
 ```python
 from flask import Flask, request, abort, jsonify
@@ -164,7 +177,8 @@ sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
 def signup():
     data = request.get_json()
     try:
-        result = sentinel.evaluate(token=data["sentinelToken"])
+        result = sentinel.evaluate(token=data["sentinelToken"],
+                                   fingerprint_event_id=data.get("fingerprintEventId"))
     except SentinelError as e:
         # Fail open OR fail closed — your call. Logged either way.
         app.logger.warning("Sentinel error: %s", e)
@@ -173,6 +187,11 @@ def signup():
     if result and result.is_blocked:
         abort(403, "Signup blocked")
 
+    if result and result.decision == "review":
+        return jsonify({"needs_verification": True}), 202
+
+    # This example explicitly fails open on SDK errors. Choose an endpoint-
+    # specific fallback; do not reuse this policy for transfers or withdrawals.
     # ... your normal signup flow
     return jsonify({"ok": True})
 ```
@@ -181,7 +200,7 @@ def signup():
 
 ```python
 from django.http import JsonResponse
-from sentinel import Sentinel
+from sentinel import Sentinel, SentinelError
 
 sentinel = Sentinel()  # reads SENTINEL_KEY (or SENTINEL_API_KEY) from env
 
@@ -192,13 +211,17 @@ class FraudCheckMiddleware:
     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
+            if not token:
+                return JsonResponse({"error": "verification required"}, status=400)
+            try:
+                result = sentinel.evaluate(token=token,
+                    fingerprint_event_id=request.META.get("HTTP_X_SENTINEL_FINGERPRINT_EVENT_ID"))
+            except SentinelError:
+                return JsonResponse({"error": "verification unavailable"}, status=503)
+            if result.is_blocked:
+                return JsonResponse({"error": "blocked"}, status=403)
+            if result.decision == "review":
+                return JsonResponse({"error": "additional verification required"}, status=409)
         return self.get_response(request)
 ```
 
@@ -206,12 +229,12 @@ Runnable versions live in [`examples/`](./examples/).
 
 ## API
 
-### `Sentinel(api_key=None, endpoint="https://sntlhq.com", timeout=5.0)`
+### `Sentinel(api_key=None, endpoint="https://maskbreak.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) |
+| `endpoint` | `https://maskbreak.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)`
@@ -222,31 +245,66 @@ Returns `EvaluateResult`. Raises `SentinelError` on network/API failure.
 - `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`.
 
+This synchronous SDK forwards only these named inputs. It does not expose a
+timezone input, automatic retries, a circuit breaker, or every REST endpoint.
+Device availability and `degraded` remain accessible through `raw`; missing
+device evidence must not be treated as a clean device result. Account linking
+(`linked_accounts`) is customer-scoped; device `first_seen`/`times_seen` history
+is not customer-scoped.
+
 ### `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.
 
+Production bare-IP lookup checks cloud ranges and Tor exits, not live-visit
+VPN/proxy evidence. Legacy `vpn`/`proxied` keys in the shape do not imply those
+checks ran. Use `evaluate()` with browser evidence for VPN/proxy checks. When
+obtaining an IP behind a proxy, trust forwarded headers only from configured
+trusted proxies; never blindly take the first client-supplied value.
+
 ## 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`:
+Deterministic `test_*` tokens exercise response handling, not detection quality.
+SDK fixture calls use authentication and quota but do not increment billable
+usage or trigger webhooks; console-originated live-key fixtures can be stored
+as test events. Personal rules and exception pins can change fixture decisions.
 
 ```python
 result = s.evaluate(token="test_vpn")       # also: test_clean, test_proxy, test_datacenter, test_tor
-assert result.decision == "review"
+assert result.decision == "review"          # default policy, no overriding rules/pins
 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
+s = Sentinel(api_key="sk_test_sandbox")     # deterministic fixtures only, no live detection
+```
+
+The public sandbox is separately rate-limited, accepts only supported fixture
+tokens, and does not store events or run live detection. It is not a production
+allowance. A personal `sk_test_...` key runs the live pipeline with real browser
+evidence and your policy; resulting events can be stored with `is_test` set,
+without incrementing usage or firing webhooks. Test keys still have rate limits.
+
+Local checks require no API credentials:
+
+```bash
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
 ```
 
-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.
+The CI matrix targets Python 3.8–3.14 without raising the 3.8 minimum. A configured
+matrix is not a claim that every interpreter was tested locally; inspect its run.
 
 ## Errors
 
-All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+Transport/API failures and unusable success responses raise `SentinelError`.
+The exception carries `.status` (HTTP code) and `.body` (parsed error body) when
+available. Redirects are rejected to avoid forwarding credentials. Configure the
+final API base URL; the client does not retry automatically.
 
 ```python
 from sentinel import Sentinel, SentinelError
@@ -259,15 +317,15 @@ except SentinelError as e:
     elif e.status and 400 <= e.status < 500:
         pass    # bad input, won't recover by retrying
     else:
-        pass    # transient — retry once or fail open
+        pass    # unknown outcome — use the endpoint's explicit fallback policy
 ```
 
 ## 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.
+card.
 
-## What Sentinel detects
+## What Maskbreak detects
 
 VPNs (commercial + self-hosted) · residential proxies (Bright Data, IPRoyal,
 and similar networks) · datacenter IPs · Tor exit nodes · antidetect browsers
@@ -277,10 +335,10 @@ 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)
+- **Node.js SDK** — [`@sentinelsup/sdk`](https://github.com/sentinelsup/maskbreak-node) on npm
+- **API docs** — [maskbreak.com/api](https://maskbreak.com/api)
+- **Free IP lookup tool** — [maskbreak.com/ip-lookup](https://maskbreak.com/ip-lookup)
 
 ## License
 
-MIT © [Sentinel Edge Networks LTD](https://sntlhq.com). See [LICENSE](LICENSE).
+MIT © [Sentinel Edge Networks LTD](https://maskbreak.com). See [LICENSE](LICENSE).