@sentinelsup/sdk 0.1.1 → 0.2.1

package/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.

package/README.md

@@ -1,162 +1,248 @@
-# @sentinelsup/sdk
-
-Official Node.js SDK for [Sentinel](https://sntlhq.com) — real-time fraud detection that flags VPNs, residential proxies, antidetect browsers, and AI bots in under 40 ms.
-
-[![npm](https://img.shields.io/npm/v/@sentinelsup/sdk.svg)](https://www.npmjs.com/package/@sentinelsup/sdk)
-[![license](https://img.shields.io/npm/l/@sentinelsup/sdk.svg)](./LICENSE)
-
-## Install
-
-```bash
-npm install @sentinelsup/sdk
-```
-
-Zero dependencies. Works on Node 14+, Bun, Deno, Cloudflare Workers, and Vercel Edge (wherever `fetch` exists).
-
-## Quick start
-
-```js
-const Sentinel = require('@sentinelsup/sdk');
-
-const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
-
-const result = await sentinel.evaluate({
-  token: req.body.sentinelToken  // from the frontend SDK
-});
-
-if (result.isSuspicious) {
-  return res.status(403).json({ error: 'blocked' });
-}
-
-// Safe — let the request through
-```
-
-Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
-
-## What you get back
-
-```ts
-{
-  isSuspicious: boolean,     // combined network + device verdict
-  details: {
-    ip: '45.33.32.156',
-    cc: 'US',
-    vpn: false,
-    proxied: true,          // residential proxy detected
-    dch: false,             // datacenter
-    anon: false,
-    service: 'BrightData'
-  },
-  deviceIntel: {            // null unless you pass fingerprintEventId
-    visitorId: 'abc123...',
-    browserTampering: true, // antidetect browser detected
-    botDetected: false,
-    incognito: false,
-    virtualMachine: false,
-    emulator: false
-  }
-}
-```
-
-## Frontend setup
-
-Add the Sentinel Edge SDK to your frontend so Sentinel can collect the token:
-
-```html
-<script async src="https://sntlhq.com/assets/edge.js" id="_mcl"></script>
-
-<!-- Add class="monocle-enriched" to any form you want evaluated -->
-<form class="monocle-enriched" id="checkout-form">
-  <!-- The SDK injects: <input type="hidden" name="monocle" value="eyJ..."> -->
-</form>
-```
-
-Read the token from the injected form field and send it to your backend:
-
-```js
-const token = document.querySelector('input[name="monocle"]').value;
-fetch('/checkout', { method: 'POST', body: JSON.stringify({ sentinelToken: token }) });
-```
-
-## Examples
-
-### Stripe Checkout — block card testing
-
-```js
-const Sentinel = require('@sentinelsup/sdk');
-const stripe = require('stripe')(process.env.STRIPE_KEY);
-const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
-
-app.post('/checkout', async (req, res) => {
-  const { isSuspicious } = await sentinel.evaluate({ token: req.body.sentinelToken });
-  if (isSuspicious) return res.status(403).json({ error: 'declined' });
-
-  const intent = await stripe.paymentIntents.create({ /* ... */ });
-  res.json({ clientSecret: intent.client_secret });
-});
-```
-
-### Signup — block fake Google sign-ins
-
-```js
-app.post('/auth/google', async (req, res) => {
-  const { credential, sentinelToken } = req.body;
-  const ticket = await googleClient.verifyIdToken({ idToken: credential });
-
-  const result = await sentinel.evaluate({ token: sentinelToken });
-  if (result.isSuspicious) return res.status(403).json({ error: 'signup_blocked' });
-
-  await createUser(ticket.getPayload().email, result.deviceIntel?.visitorId);
-});
-```
-
-### Custom policy with `shouldBlock`
-
-```js
-// Only block when we see both residential proxy AND browser tampering
-const blocked = await sentinel.shouldBlock(
-  { token },
-  r => r.details.proxied && r.deviceIntel?.browserTampering
-);
-```
-
-## API
-
-### `new Sentinel({ apiKey, endpoint?, timeoutMs? })`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | string | required | Your key starting with `sk_live_` |
-| `endpoint` | string | `https://sntlhq.com` | Override base URL |
-| `timeoutMs` | number | `5000` | Per-request timeout |
-
-### `sentinel.evaluate({ token, fingerprintEventId? })`
-
-Returns `EvaluateResult`. Throws `SentinelError` on network/API failure — the error carries `.status` and `.body`.
-
-### `sentinel.shouldBlock({ token, fingerprintEventId? }, predicate?)`
-
-Convenience: runs `evaluate()` and returns a boolean. Default predicate is `r => r.isSuspicious`. Pass your own to build custom policies.
-
-## 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.
-
-## TypeScript
-
-Full types ship with the package. Importing `Sentinel` gives you the class plus `EvaluateResult`, `DeviceIntel`, `EvaluateDetails`, and `SentinelError` types.
-
-```ts
-import Sentinel, { EvaluateResult } from '@sentinelsup/sdk';
-```
-
-## License
-
-MIT © Sentinel Edge Networks LTD
-
-## Links
-
-- Website — [sntlhq.com](https://sntlhq.com)
-- API docs — [sntlhq.com/api](https://sntlhq.com/api)
-- Blog — [sntlhq.com/blog](https://sntlhq.com/blog)
-- X / Twitter — [@SentinelSup](https://x.com/SentinelSup)
+# @sentinelsup/sdk
+
+Official Node.js SDK for [Sentinel](https://sntlhq.com) — real-time fraud detection that flags VPNs, residential proxies, antidetect browsers, and AI bots in under 40 ms.
+
+[![npm](https://img.shields.io/npm/v/@sentinelsup/sdk.svg)](https://www.npmjs.com/package/@sentinelsup/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@sentinelsup/sdk.svg)](https://www.npmjs.com/package/@sentinelsup/sdk)
+[![types](https://img.shields.io/npm/types/@sentinelsup/sdk.svg)](./index.d.ts)
+[![license](https://img.shields.io/npm/l/@sentinelsup/sdk.svg)](./LICENSE)
+
+## 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
+npm install @sentinelsup/sdk
+```
+
+Zero dependencies. Works on Node 14+, Bun, Deno, Cloudflare Workers, and Vercel Edge (wherever `fetch` exists).
+
+## Quick start
+
+```js
+const Sentinel = require('@sentinelsup/sdk');
+
+const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
+
+const result = await sentinel.evaluate({
+  token: req.body.sentinelToken  // from the frontend SDK
+});
+
+if (result.decision === 'block') {
+  return res.status(403).json({ error: 'blocked' });
+}
+// 'review' → let through but flag; 'allow' → clean
+```
+
+Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
+
+## What you get back
+
+```ts
+{
+  decision: 'review',          // 'allow' | 'review' | 'block' — route on this
+  risk_score: 65,              // 0–100
+  isSuspicious: true,          // simple boolean verdict
+  ip: '198.51.100.18',
+  country: 'NL',
+  network: {
+    vpn: true, proxy: false, datacenter: true, anonymous: true,
+    tor: false, residential: false, service: 'PROTON_VPN'
+  },
+  device: {                    // present only when you pass fingerprintEventId
+    antidetect: false,         // antidetect browser detected
+    automation: false,         // bot / browser automation
+    emulator: false, virtual_machine: false, incognito: false,
+    ip_blocklisted: false, visitor_id: 'abc123', tampering_score: 0
+  },
+  reasons: ['vpn_detected', 'datacenter_asn'],  // machine-readable codes
+  evaluated_in_ms: 28
+}
+```
+
+Try the live sample (same shape, no key needed):
+`curl "https://sntlhq.com/v1/evaluate/sample?scenario=vpn"`
+
+Legacy `details` / `deviceIntel` fields are still returned for backwards
+compatibility with 0.1.0 integrations.
+
+## 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="checkout-form">
+  <!-- The SDK injects both:
+       <input type="hidden" name="monocle"     value="eyJ...">  (network)
+       <input type="hidden" name="sentinel_fp" value="a1b2..."> (device) -->
+</form>
+```
+
+Collect both and send them to your backend:
+
+```js
+const { token, fingerprintEventId } = await window.Sentinel.collect();
+fetch('/checkout', { method: 'POST', body: JSON.stringify({ token, fingerprintEventId }) });
+```
+
+## Examples
+
+### Stripe Checkout — block card testing
+
+```js
+const Sentinel = require('@sentinelsup/sdk');
+const stripe = require('stripe')(process.env.STRIPE_KEY);
+const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
+
+app.post('/checkout', async (req, res) => {
+  const { isSuspicious } = await sentinel.evaluate({ token: req.body.token, fingerprintEventId: req.body.fingerprintEventId });
+  if (isSuspicious) return res.status(403).json({ error: 'declined' });
+
+  const intent = await stripe.paymentIntents.create({ /* ... */ });
+  res.json({ clientSecret: intent.client_secret });
+});
+```
+
+### Signup — block fake Google sign-ins
+
+```js
+app.post('/auth/google', async (req, res) => {
+  const { credential, sentinelToken } = req.body;
+  const ticket = await googleClient.verifyIdToken({ idToken: credential });
+
+  const result = await sentinel.evaluate({ token: sentinelToken });
+  if (result.isSuspicious) return res.status(403).json({ error: 'signup_blocked' });
+
+  await createUser(ticket.getPayload().email, result.deviceIntel?.visitorId);
+});
+```
+
+### Custom policy with `shouldBlock`
+
+```js
+// Only block when we see both residential proxy AND an antidetect browser
+const blocked = await sentinel.shouldBlock(
+  { token },
+  r => r.network.proxy && r.device?.antidetect
+);
+```
+
+### Burner-email check at signup
+
+```js
+// Pass the signup email and Sentinel checks it against a continuously
+// refreshed disposable-domain feed. A hit adds the disposable_email
+// reason, raises risk_score, and escalates allow → review. The address
+// is checked transiently — never stored or logged.
+const result = await sentinel.evaluate({ token, email: req.body.email });
+if (result.email?.disposable) {
+  // e.g. require a real address before granting the trial
+}
+```
+
+### Look up an arbitrary IP — no browser token needed
+
+```js
+// Batch scoring, log enrichment, server-side screening. Same key,
+// same hourly quota as evaluate().
+const info = await sentinel.lookup('185.220.101.34');
+// info.verdict     → 'allow' | 'review' | 'block'
+// info.risk_score  → 0–100
+// info.signals     → { vpn, proxied, tor, dch, anon } (null when known:false)
+// info.network     → { asn, org, country, city }
+```
+
+## API
+
+### `new Sentinel({ apiKey, endpoint?, timeoutMs? })`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | required | Your key starting with `sk_live_` |
+| `endpoint` | string | `https://sntlhq.com` | Override base URL |
+| `timeoutMs` | number | `5000` | Per-request timeout |
+
+### `sentinel.evaluate({ token, fingerprintEventId?, accountId?, email? })`
+
+Returns `EvaluateResult`. Throws `SentinelError` on network/API failure — the error carries `.status` and `.body`.
+
+- `fingerprintEventId` — adds the `device` signal block (antidetect, automation, emulator, …), including device history (`device.times_seen`, `device.first_seen` — ISO timestamp of the first sighting, `device.returning`).
+- `accountId` — your own user id for this session; enables multi-accounting detection (`device.linked_accounts` / `device.multi_account`).
+- `email` — adds `email.disposable` to the response; burner domains escalate `allow` to `review`.
+
+### `sentinel.lookup(ip)`
+
+Returns `LookupResponse` for any public IPv4/IPv6 address (wraps `GET /v1/lookup/{ip}`): allow/review/block verdict, 0–100 risk score, VPN/proxy/Tor/datacenter signals, and network attribution. Shares the per-key hourly quota with `evaluate()`. `known: false` means our feeds hold no data for the IP — it is **not** a clean guarantee.
+
+### `sentinel.shouldBlock({ token, fingerprintEventId? }, predicate?)`
+
+Convenience: runs `evaluate()` and returns a boolean. Default predicate is `r => r.isSuspicious`. Pass your own to build custom policies.
+
+> `accountId`, `email`, and `lookup()` ship in the **next npm release (0.2.1)** — the published 0.1.2 silently ignores `accountId`/`email` — on npm today, use the raw HTTP endpoints documented at [sntlhq.com/api](https://sntlhq.com/api) until it lands.
+
+## Testing
+
+Deterministic test tokens exercise every decision path from a terminal — authenticated and rate-limited like real calls, but never billed, stored, or webhooked (responses carry `"test": true`):
+
+```js
+await sentinel.evaluate({ token: 'test_vpn' });   // → decision: 'review'/'block' path
+await sentinel.evaluate({ token: 'test_clean' }); // → decision: 'allow' path
+// also: test_proxy, test_datacenter, test_tor
+```
+
+- **No account yet?** The public sandbox key `sk_test_sandbox` answers the same `test_*` tokens with the same shapes — no signup, nothing stored.
+- **CI / staging with real traffic:** every account also has a personal `sk_test_…` key (Settings → API Key) that runs the complete live pipeline — device intelligence, your rules and exception pins — but events are flagged as test, excluded from usage, and never fire webhooks. It is exempt from the account's IP allowlist.
+
+## Rate limits
+
+Free tier: **1,000 requests/hour** per API key (`evaluate()` and `lookup()` share the bucket). No monthly cap, no credit card. Upgrade at [sntlhq.com](https://sntlhq.com) when you need more.
+
+On `429`, the thrown `SentinelError` has `.status === 429` — honor the `Retry-After` header and fail open (let the request through and log it) rather than blocking real users while you are throttled. Responses also carry `X-RateLimit-Limit` / `-Remaining` / `-Reset` for proactive backoff.
+
+## TypeScript
+
+Full types ship with the package. Importing `Sentinel` gives you the class plus `EvaluateResult`, `DeviceIntel`, `EvaluateDetails`, and `SentinelError` types.
+
+```ts
+import Sentinel, { EvaluateResult } from '@sentinelsup/sdk';
+```
+
+## 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
+
+- **Python SDK** — [`sentinelsup`](https://github.com/sentinelsup/sentinel-python) on PyPI
+- **Free IP lookup tool** — [sntlhq.com/ip-lookup](https://sntlhq.com/ip-lookup)
+
+## License
+
+MIT © Sentinel Edge Networks LTD
+
+## Links
+
+- Website — [sntlhq.com](https://sntlhq.com)
+- API docs — [sntlhq.com/api](https://sntlhq.com/api)
+- Blog — [sntlhq.com/blog](https://sntlhq.com/blog)
+- X / Twitter — [@SentinelSup](https://x.com/SentinelSup)

package/index.d.ts

@@ -1,60 +1,180 @@
-export interface EvaluateDetails {
-    ip: string;
-    cc: string;
-    vpn: boolean;
-    proxied: boolean;
-    dch: boolean;
-    anon: boolean;
-    crawler?: boolean;
-    service?: string;
-}
-
-export interface DeviceIntel {
-    visitorId: string | null;
-    browserTampering: boolean;
-    botDetected: boolean;
-    vpnDetected: boolean;
-    proxyDetected: boolean;
-    torDetected: boolean;
-    ipBlocklisted: boolean;
-    incognito: boolean;
-    virtualMachine: boolean;
-    emulator: boolean;
-    tamperingScore?: number;
-}
-
-export interface EvaluateResult {
-    status: string;
-    isSuspicious: boolean;
-    details: EvaluateDetails;
-    deviceIntel: DeviceIntel | null;
-}
-
-export interface SentinelOptions {
-    /** Your Sentinel API key (starts with sk_live_). Get one free at https://sntlhq.com/signup */
-    apiKey: string;
-    /** Override the API base URL (default: https://sntlhq.com) */
-    endpoint?: string;
-    /** Per-request timeout in ms (default: 5000) */
-    timeoutMs?: number;
-}
-
-export interface EvaluateInput {
-    /** Client-side Sentinel token from the frontend SDK */
-    token: string;
-    /** Optional Fingerprint event id for device-layer signals */
-    fingerprintEventId?: string;
-}
-
-export class SentinelError extends Error {
-    status?: number;
-    body?: unknown;
-}
-
-export default class Sentinel {
-    constructor(opts: SentinelOptions);
-    evaluate(input: EvaluateInput): Promise<EvaluateResult>;
-    shouldBlock(input: EvaluateInput, predicate?: (r: EvaluateResult) => boolean): Promise<boolean>;
-}
-
-export { Sentinel };
+export interface EvaluateDetails {
+    ip: string;
+    cc: string;
+    vpn: boolean;
+    proxied: boolean;
+    dch: boolean;
+    anon: boolean;
+    crawler?: boolean;
+    service?: string;
+}
+
+export interface DeviceIntel {
+    visitorId: string | null;
+    browserTampering: boolean;
+    botDetected: boolean;
+    vpnDetected: boolean;
+    proxyDetected: boolean;
+    torDetected: boolean;
+    ipBlocklisted: boolean;
+    incognito: boolean;
+    virtualMachine: boolean;
+    emulator: boolean;
+    tamperingScore?: number;
+}
+
+export interface NetworkSignals {
+    vpn: boolean;
+    proxy: boolean;
+    datacenter: boolean;
+    anonymous: boolean;
+    tor: boolean;
+    residential: boolean;
+    service: string | null;
+}
+
+export interface DeviceSignals {
+    antidetect: boolean;
+    automation: boolean;
+    emulator: boolean;
+    virtual_machine: boolean;
+    incognito: boolean;
+    privacy_mode: boolean;
+    ip_blocklisted: boolean;
+    visitor_id: string | null;
+    tampering_score: number;
+    high_activity: boolean;
+    /** Sightings of this device for your account (present when the device is identified) */
+    times_seen?: number;
+    /** ISO 8601 timestamp of when Sentinel first saw this device (present when the device is identified) */
+    first_seen?: string;
+    returning?: boolean;
+    /** Distinct accountIds seen on this device (present when accountId was supplied) */
+    linked_accounts?: number;
+    multi_account?: boolean;
+}
+
+export type ReasonCode =
+    | 'vpn_detected' | 'proxy_detected' | 'datacenter_asn' | 'tor_exit_node'
+    | 'anonymous_network' | 'antidetect_browser' | 'automation_detected'
+    | 'emulator_detected' | 'virtual_machine' | 'ip_blocklisted' | 'private_browsing'
+    | 'high_activity_device' | 'multi_account_device' | 'disposable_email';
+
+export interface EmailSignals {
+    /** True when the address uses a disposable/burner domain */
+    disposable: boolean;
+}
+
+export interface EvaluateResult {
+    /** "allow" | "review" | "block" — route on this */
+    decision: 'allow' | 'review' | 'block';
+    /** 0–100 weighted risk score */
+    risk_score: number;
+    /** Legacy convenience flag: VPN/proxy/antidetect/automation/emulator.
+     *  Does NOT cover Tor or datacenter — route on `decision` instead. */
+    isSuspicious: boolean;
+    ip: string | null;
+    country: string | null;
+    network: NetworkSignals;
+    /** Present only when fingerprintEventId was supplied */
+    device?: DeviceSignals;
+    /** Machine-readable reason codes for the verdict */
+    reasons: ReasonCode[];
+    evaluated_in_ms: number;
+    /** Present when the optional `email` input was supplied */
+    email?: EmailSignals;
+    /** Present only when your own rules/exceptions changed `decision`:
+     *  the engine's own risk-score verdict */
+    engine_decision?: 'allow' | 'review' | 'block';
+    /** Who authored the final decision when it was not the engine */
+    decision_source?: 'rules' | 'exception';
+    /** Signals that triggered a custom rule (decision_source === 'rules') */
+    rule_matched?: string[];
+    /** Matched per-IP/visitor pins (decision_source === 'exception') */
+    exception_matched?: string[];
+    /** Present on test-token / sk_test_ key responses — never billed */
+    test?: boolean;
+    /** Legacy fields (kept for backwards compatibility) */
+    status: string;
+    details: EvaluateDetails;
+    deviceIntel?: DeviceIntel | null;
+}
+
+export interface LookupSignals {
+    vpn: boolean;
+    /** Proxy detected (legacy field spelling) */
+    proxied: boolean;
+    tor: boolean;
+    /** Datacenter hosting (legacy field spelling) */
+    dch: boolean;
+    /** Anonymizing behaviors observed */
+    anon: boolean;
+}
+
+export interface LookupNetwork {
+    asn: number | null;
+    org: string | null;
+    country: string | null;
+    city: string | null;
+    /** Cloud provider name, present on a provider-range hit */
+    cloud?: string;
+}
+
+export interface LookupResponse {
+    ip: string;
+    /** Whether our reputation feeds hold data for this IP.
+     *  false does NOT assert the IP is clean. */
+    known: boolean;
+    verdict: 'allow' | 'review' | 'block';
+    /** 0–100 */
+    risk_score: number;
+    /** Null when known is false */
+    signals: LookupSignals | null;
+    network: LookupNetwork | null;
+    latency_ms: number;
+    /** Present only when an exception pin changed `verdict` */
+    engine_verdict?: 'allow' | 'review' | 'block';
+    verdict_source?: 'exception';
+    exception_matched?: string[];
+    /** Present when the call used the per-account sk_test_ key */
+    test?: boolean;
+}
+
+export interface SentinelOptions {
+    /** Your Sentinel API key (starts with sk_live_). Get one free at https://sntlhq.com/signup */
+    apiKey: string;
+    /** Override the API base URL (default: https://sntlhq.com) */
+    endpoint?: string;
+    /** Per-request timeout in ms (default: 5000) */
+    timeoutMs?: number;
+}
+
+export interface EvaluateInput {
+    /** Client-side Sentinel token from the frontend SDK */
+    token: string;
+    /** Optional Fingerprint event id for device-layer signals */
+    fingerprintEventId?: string;
+    /** Optional account/user id — enables multi-accounting detection
+     *  (device.linked_accounts / device.multi_account) */
+    accountId?: string;
+    /** Optional signup email — adds `email.disposable` to the response
+     *  (burner domains escalate allow → review). Checked transiently,
+     *  never stored or logged. */
+    email?: string;
+}
+
+export class SentinelError extends Error {
+    status?: number;
+    body?: unknown;
+}
+
+export default class Sentinel {
+    constructor(opts: SentinelOptions);
+    evaluate(input: EvaluateInput): Promise<EvaluateResult>;
+    /** Look up an arbitrary public IP address (GET /v1/lookup/{ip}).
+     *  Shares the per-key hourly quota with evaluate(). */
+    lookup(ip: string): Promise<LookupResponse>;
+    shouldBlock(input: EvaluateInput, predicate?: (r: EvaluateResult) => boolean): Promise<boolean>;
+}
+
+export { Sentinel };

package/index.js

@@ -1,140 +1,198 @@
-/**
- * Sentinel Node.js SDK — thin, zero-dependency wrapper around the
- * Sentinel fraud detection API at https://sntlhq.com/v1/evaluate.
- *
- * Usage:
- *   const Sentinel = require('@sentinelsup/sdk');
- *   const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
- *   const result = await sentinel.evaluate({ token });
- *   if (result.isSuspicious) return res.status(403).end();
- */
-
-const DEFAULT_ENDPOINT = 'https://sntlhq.com';
-
-class SentinelError extends Error {
-    constructor(message, { status, body } = {}) {
-        super(message);
-        this.name = 'SentinelError';
-        this.status = status;
-        this.body = body;
-    }
-}
-
-class Sentinel {
-    /**
-     * @param {object} opts
-     * @param {string} opts.apiKey — your Sentinel API key (starts with sk_live_)
-     * @param {string} [opts.endpoint] — override the default API base URL (for testing)
-     * @param {number} [opts.timeoutMs=5000] — per-request timeout
-     */
-    constructor(opts) {
-        if (!opts || typeof opts.apiKey !== 'string' || !opts.apiKey) {
-            throw new SentinelError('Sentinel: apiKey is required. Get one free at https://sntlhq.com/signup');
-        }
-        this.apiKey = opts.apiKey;
-        this.endpoint = (opts.endpoint || DEFAULT_ENDPOINT).replace(/\/$/, '');
-        this.timeoutMs = opts.timeoutMs || 5000;
-    }
-
-    /**
-     * Evaluate a visitor session for fraud signals.
-     *
-     * @param {object} input
-     * @param {string} input.token — Sentinel client-side token from the frontend SDK
-     * @param {string} [input.fingerprintEventId] — optional Fingerprint event id for device signals
-     * @returns {Promise<EvaluateResult>}
-     */
-    async evaluate({ token, fingerprintEventId } = {}) {
-        if (!token || typeof token !== 'string') {
-            throw new SentinelError('Sentinel.evaluate: token (client-side Sentinel token) is required');
-        }
-
-        const controller = new AbortController();
-        const abortTimer = setTimeout(() => controller.abort(), this.timeoutMs);
-
-        let res;
-        try {
-            res = await fetch(`${this.endpoint}/v1/evaluate`, {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'Content-Type': 'application/json'
-                },
-                body: JSON.stringify({ token, fingerprintEventId }),
-                signal: controller.signal
-            });
-        } catch (err) {
-            if (err.name === 'AbortError') {
-                throw new SentinelError(`Sentinel: request timed out after ${this.timeoutMs}ms`);
-            }
-            throw new SentinelError(`Sentinel: network error — ${err.message}`);
-        } finally {
-            clearTimeout(abortTimer);
-        }
-
-        let json;
-        try { json = await res.json(); } catch { json = null; }
-
-        if (!res.ok) {
-            throw new SentinelError(
-                `Sentinel: API returned ${res.status}${json && json.error ? ` — ${json.error}` : ''}`,
-                { status: res.status, body: json }
-            );
-        }
-
-        return json;
-    }
-
-    /**
-     * Convenience helper: returns true if the session should be blocked.
-     * Defaults to blocking when the API's own isSuspicious flag is set.
-     * Pass a custom predicate to build your own policy.
-     *
-     * @param {object} input — same as evaluate()
-     * @param {(r: EvaluateResult) => boolean} [predicate]
-     * @returns {Promise<boolean>}
-     */
-    async shouldBlock(input, predicate) {
-        const result = await this.evaluate(input);
-        return predicate ? !!predicate(result) : !!result.isSuspicious;
-    }
-}
-
-Sentinel.SentinelError = SentinelError;
-module.exports = Sentinel;
-module.exports.default = Sentinel;
-module.exports.Sentinel = Sentinel;
-module.exports.SentinelError = SentinelError;
-
-/**
- * @typedef {object} EvaluateResult
- * @property {boolean} isSuspicious — true if network or device signals flag the session
- * @property {EvaluateDetails} details — network / IP signals from Spur Monocle
- * @property {DeviceIntel|null} deviceIntel — device signals if fingerprintEventId was supplied
- */
-
-/**
- * @typedef {object} EvaluateDetails
- * @property {string} ip
- * @property {string} cc — 2-letter country code
- * @property {boolean} vpn
- * @property {boolean} proxied
- * @property {boolean} dch — datacenter flag
- * @property {boolean} anon
- * @property {boolean} [crawler]
- * @property {string} [service]
- */
-
-/**
- * @typedef {object} DeviceIntel
- * @property {string|null} visitorId
- * @property {boolean} browserTampering
- * @property {boolean} botDetected
- * @property {boolean} vpnDetected
- * @property {boolean} proxyDetected
- * @property {boolean} torDetected
- * @property {boolean} ipBlocklisted
- * @property {boolean} incognito
- * @property {boolean} virtualMachine
- * @property {boolean} emulator
- */
+/**
+ * Sentinel Node.js SDK — thin, zero-dependency wrapper around the
+ * Sentinel fraud detection API at https://sntlhq.com/v1/evaluate.
+ *
+ * Usage:
+ *   const Sentinel = require('@sentinelsup/sdk');
+ *   const sentinel = new Sentinel({ apiKey: process.env.SENTINEL_KEY });
+ *   const result = await sentinel.evaluate({ token });
+ *   if (result.decision === 'block') return res.status(403).end();
+ */
+
+const DEFAULT_ENDPOINT = 'https://sntlhq.com';
+
+class SentinelError extends Error {
+    constructor(message, { status, body } = {}) {
+        super(message);
+        this.name = 'SentinelError';
+        this.status = status;
+        this.body = body;
+    }
+}
+
+class Sentinel {
+    /**
+     * @param {object} opts
+     * @param {string} opts.apiKey — your Sentinel API key (starts with sk_live_)
+     * @param {string} [opts.endpoint] — override the default API base URL (for testing)
+     * @param {number} [opts.timeoutMs=5000] — per-request timeout
+     */
+    constructor(opts) {
+        if (!opts || typeof opts.apiKey !== 'string' || !opts.apiKey) {
+            throw new SentinelError('Sentinel: apiKey is required. Get one free at https://sntlhq.com/signup');
+        }
+        this.apiKey = opts.apiKey;
+        this.endpoint = (opts.endpoint || DEFAULT_ENDPOINT).replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs || 5000;
+    }
+
+    /**
+     * Shared transport: auth header, timeout, JSON parsing, error mapping.
+     * @private
+     */
+    async _request(path, init) {
+        const controller = new AbortController();
+        const abortTimer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        let res;
+        try {
+            res = await fetch(`${this.endpoint}${path}`, {
+                ...init,
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    ...(init && init.headers)
+                },
+                signal: controller.signal
+            });
+        } catch (err) {
+            if (err.name === 'AbortError') {
+                throw new SentinelError(`Sentinel: request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new SentinelError(`Sentinel: network error — ${err.message}`);
+        } finally {
+            clearTimeout(abortTimer);
+        }
+
+        let json;
+        try { json = await res.json(); } catch { json = null; }
+
+        if (!res.ok) {
+            throw new SentinelError(
+                `Sentinel: API returned ${res.status}${json && json.error ? ` — ${json.error}` : ''}`,
+                { status: res.status, body: json }
+            );
+        }
+
+        return json;
+    }
+
+    /**
+     * Evaluate a visitor session for fraud signals.
+     *
+     * @param {object} input
+     * @param {string} input.token — Sentinel client-side token from the frontend SDK
+     * @param {string} [input.fingerprintEventId] — optional Fingerprint event id for device signals
+     * @param {string} [input.accountId] — optional account/user id for multi-accounting detection
+     * @param {string} [input.email] — optional signup email; adds `email.disposable` to the
+     *   response (burner domains escalate allow → review). Checked transiently, never stored.
+     * @returns {Promise<EvaluateResult>}
+     */
+    async evaluate({ token, fingerprintEventId, accountId, email } = {}) {
+        if (!token || typeof token !== 'string') {
+            throw new SentinelError('Sentinel.evaluate: token (client-side Sentinel token) is required');
+        }
+        return this._request('/v1/evaluate', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token, fingerprintEventId, accountId, email })
+        });
+    }
+
+    /**
+     * Look up an arbitrary public IP address — no browser token needed.
+     * Wraps GET /v1/lookup/{ip}: allow/review/block verdict, 0–100 risk
+     * score, VPN/proxy/Tor/datacenter signals, and network attribution.
+     * Shares the per-key hourly quota with evaluate().
+     *
+     * @param {string} ip — public IPv4 or IPv6 address, e.g. '185.220.101.34'
+     * @returns {Promise<LookupResponse>}
+     */
+    async lookup(ip) {
+        if (!ip || typeof ip !== 'string') {
+            throw new SentinelError('Sentinel.lookup: ip (public IPv4 or IPv6 address) is required');
+        }
+        return this._request(`/v1/lookup/${encodeURIComponent(ip.trim())}`, { method: 'GET' });
+    }
+
+    /**
+     * Convenience helper: returns true if the session should be blocked.
+     * Defaults to blocking when the API's own isSuspicious flag is set.
+     * Pass a custom predicate to build your own policy.
+     *
+     * @param {object} input — same as evaluate()
+     * @param {(r: EvaluateResult) => boolean} [predicate]
+     * @returns {Promise<boolean>}
+     */
+    async shouldBlock(input, predicate) {
+        const result = await this.evaluate(input);
+        return predicate ? !!predicate(result) : !!result.isSuspicious;
+    }
+}
+
+Sentinel.SentinelError = SentinelError;
+module.exports = Sentinel;
+module.exports.default = Sentinel;
+module.exports.Sentinel = Sentinel;
+module.exports.SentinelError = SentinelError;
+
+/**
+ * @typedef {object} EvaluateResult
+ * @property {'allow'|'review'|'block'} decision — route on this
+ * @property {number} risk_score — 0–100 weighted risk score
+ * @property {boolean} isSuspicious — true if network or device signals flag the session
+ * @property {string|null} ip
+ * @property {string|null} country — 2-letter country code
+ * @property {object} network — { vpn, proxy, datacenter, anonymous, tor, residential, service }
+ * @property {object} [device] — { antidetect, automation, emulator, virtual_machine, incognito, visitor_id, tampering_score, ... } when fingerprintEventId was supplied
+ * @property {string[]} reasons — machine-readable reason codes (vpn_detected, proxy_detected, ...)
+ * @property {number} evaluated_in_ms
+ * @property {{disposable: boolean}} [email] — present when the optional email input was supplied
+ * @property {'allow'|'review'|'block'} [engine_decision] — present when your own rules/exceptions changed `decision`
+ * @property {'rules'|'exception'} [decision_source] — who authored the final decision when it was not the engine
+ * @property {string[]} [rule_matched] — signals that triggered a custom rule
+ * @property {string[]} [exception_matched] — matched per-IP/visitor pins
+ * @property {boolean} [test] — present on test-token / test-key responses (never billed)
+ * @property {EvaluateDetails} details — legacy network signals (backwards compatibility)
+ * @property {DeviceIntel|null} [deviceIntel] — legacy device signals (backwards compatibility)
+ */
+
+/**
+ * @typedef {object} LookupResponse
+ * @property {string} ip
+ * @property {boolean} known — whether our reputation feeds hold data for this IP (false ≠ clean)
+ * @property {'allow'|'review'|'block'} verdict
+ * @property {number} risk_score — 0–100
+ * @property {{vpn: boolean, proxied: boolean, tor: boolean, dch: boolean, anon: boolean}|null} signals — null when known is false
+ * @property {{asn: number|null, org: string|null, country: string|null, city: string|null, cloud?: string}|null} network
+ * @property {number} latency_ms
+ * @property {'allow'|'review'|'block'} [engine_verdict] — present when an exception pin changed `verdict`
+ * @property {'exception'} [verdict_source]
+ * @property {string[]} [exception_matched]
+ * @property {boolean} [test] — present when the call used the per-account sk_test_ key
+ */
+
+/**
+ * @typedef {object} EvaluateDetails
+ * @property {string} ip
+ * @property {string} cc — 2-letter country code
+ * @property {boolean} vpn
+ * @property {boolean} proxied
+ * @property {boolean} dch — datacenter flag
+ * @property {boolean} anon
+ * @property {boolean} [crawler]
+ * @property {string} [service]
+ */
+
+/**
+ * @typedef {object} DeviceIntel
+ * @property {string|null} visitorId
+ * @property {boolean} browserTampering
+ * @property {boolean} botDetected
+ * @property {boolean} vpnDetected
+ * @property {boolean} proxyDetected
+ * @property {boolean} torDetected
+ * @property {boolean} ipBlocklisted
+ * @property {boolean} incognito
+ * @property {boolean} virtualMachine
+ * @property {boolean} emulator
+ */

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@sentinelsup/sdk",
-  "version": "0.1.1",
-  "description": "Official Node.js SDK for Sentinel — real-time fraud detection, VPN/residential-proxy/antidetect-browser detection in under 40ms.",
-  "keywords": [
-    "fraud-detection",
-    "bot-detection",
-    "vpn-detection",
-    "proxy-detection",
-    "residential-proxy",
-    "antidetect-browser",
-    "stripe",
-    "shopify",
-    "chargeback",
-    "sentinel",
-    "sntlhq"
-  ],
-  "main": "index.js",
-  "types": "index.d.ts",
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sentinelsup/sentinel-node.git"
-  },
-  "homepage": "https://sntlhq.com",
-  "bugs": {
-    "url": "https://github.com/sentinelsup/sentinel-node/issues"
-  },
-  "author": "Sentinel Edge Networks LTD <support@sntlhq.com>",
-  "license": "MIT",
-  "engines": {
-    "node": ">=14"
-  },
-  "scripts": {
-    "test": "node --test test.js"
-  }
-}
+{
+  "name": "@sentinelsup/sdk",
+  "version": "0.2.1",
+  "description": "Official Node.js SDK for Sentinel — real-time fraud detection, VPN/residential-proxy/antidetect-browser detection in under 40ms.",
+  "keywords": [
+    "fraud-detection",
+    "bot-detection",
+    "vpn-detection",
+    "proxy-detection",
+    "residential-proxy",
+    "antidetect-browser",
+    "stripe",
+    "shopify",
+    "chargeback",
+    "sentinel",
+    "sntlhq"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sentinelsup/sentinel-node.git"
+  },
+  "homepage": "https://sntlhq.com",
+  "bugs": {
+    "url": "https://github.com/sentinelsup/sentinel-node/issues"
+  },
+  "author": "Sentinel Edge Networks LTD <support@sntlhq.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "node --test test.js"
+  }
+}