@sentinelsup/sdk 0.1.1 → 0.1.2

package/README.md

@@ -5,6 +5,20 @@ Official Node.js SDK for [Sentinel](https://sntlhq.com) — real-time fraud dete
 [![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)
 
+## 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
@@ -24,11 +38,10 @@ const result = await sentinel.evaluate({
   token: req.body.sentinelToken  // from the frontend SDK
 });
 
-if (result.isSuspicious) {
+if (result.decision === 'block') {
   return res.status(403).json({ error: 'blocked' });
 }
-
-// Safe — let the request through
+// 'review' → let through but flag; 'allow' → clean
 ```
 
 Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/signup).
@@ -37,27 +50,32 @@ Get a free API key (no credit card) at [sntlhq.com/signup](https://sntlhq.com/si
 
 ```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'
+  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
   },
-  deviceIntel: {            // null unless you pass fingerprintEventId
-    visitorId: 'abc123...',
-    browserTampering: true, // antidetect browser detected
-    botDetected: false,
-    incognito: false,
-    virtualMachine: false,
-    emulator: false
-  }
+  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 Edge SDK to your frontend so Sentinel can collect the token:
@@ -113,10 +131,10 @@ app.post('/auth/google', async (req, res) => {
 ### Custom policy with `shouldBlock`
 
 ```js
-// Only block when we see both residential proxy AND browser tampering
+// Only block when we see both residential proxy AND an antidetect browser
 const blocked = await sentinel.shouldBlock(
   { token },
-  r => r.details.proxied && r.deviceIntel?.browserTampering
+  r => r.network.proxy && r.device?.antidetect
 );
 ```
 

package/index.d.ts

@@ -23,11 +23,52 @@ export interface DeviceIntel {
     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;
+}
+
+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';
+
 export interface EvaluateResult {
-    status: string;
+    /** "allow" | "review" | "block" — route on this */
+    decision: 'allow' | 'review' | 'block';
+    /** 0–100 weighted risk score */
+    risk_score: number;
+    /** Simple boolean verdict (network or device signals flagged) */
     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;
+    /** Legacy fields (kept for backwards compatibility) */
+    status: string;
     details: EvaluateDetails;
-    deviceIntel: DeviceIntel | null;
+    deviceIntel?: DeviceIntel | null;
 }
 
 export interface SentinelOptions {

package/index.js

@@ -6,7 +6,7 @@
  *   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();
+ *   if (result.decision === 'block') return res.status(403).end();
  */
 
 const DEFAULT_ENDPOINT = 'https://sntlhq.com';
@@ -108,9 +108,17 @@ 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 {EvaluateDetails} details — network / IP signals from Spur Monocle
- * @property {DeviceIntel|null} deviceIntel — device signals if fingerprintEventId was supplied
+ * @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 {EvaluateDetails} details — legacy network signals (backwards compatibility)
+ * @property {DeviceIntel|null} [deviceIntel] — legacy device signals (backwards compatibility)
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentinelsup/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Official Node.js SDK for Sentinel — real-time fraud detection, VPN/residential-proxy/antidetect-browser detection in under 40ms.",
   "keywords": [
     "fraud-detection",