@sentinelsup/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentinel Edge Networks LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @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 client-side SDK to your frontend so Sentinel can collect the token:
+
+```html
+<script async src="https://fp.sntlhq.com/agent"></script>
+```
+
+Read the token from the rendered 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)

package/index.d.ts

@@ -0,0 +1,60 @@
+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 };

package/index.js

@@ -0,0 +1,140 @@
+/**
+ * Sentinel Node.js SDK — thin, zero-dependency wrapper around the
+ * Sentinel fraud detection API at https://sntlhq.com/v1/evaluate.
+ *
+ * Usage:
+ *   const Sentinel = require('@sentinel/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
+ */

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sentinelsup/sdk",
+  "version": "0.1.0",
+  "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"
+  }
+}