@gamma-sweep/web-intelligence-sdk

GS Web Intelligence SDK — a tiny (< 40 KB gzip), zero-dependency browser script that collects device, browser-tamper, network, GPS, storage, and behavioral signals on the page and seals them into a single opaque, encrypted, single-use token. Your backend forwards that token verbatim to /fraud-check; it never parses or understands the contents. The GS edge decrypts it with a private key that only exists in our environment, enriches it, and feeds the scoring engine.

No client PII leaves the page beyond a random true_device_id UUID (disabled entirely with persistence: false). Behavioral signals are timing/motion metadata only — never keystroke identities, field values, or DOM content.

Install

npm / bundler

npm install @gamma-sweep/web-intelligence-sdk

import { gs } from "@gamma-sweep/web-intelligence-sdk";

gs.config({
  client_id: "YOUR_CLIENT_ID",
  session_id: crypto.randomUUID(), // fresh per protected action
  gps: "prompt",
  behavior: true,
});

// On login / checkout / signup submit:
const session = await gs.getSession(); // opaque JWE string, send to your backend

The package ships ESM (dist/gs.esm.js), CJS (dist/gs.cjs), an IIFE browser build (dist/gs.js), and TypeScript declarations (dist/index.d.ts).

CDN / <script> (IIFE global window.gs)

<script async src="https://cdn.gammasweep.com/v1/gs.js"
        integrity="sha384-<from dist/sri.json>"
        crossorigin="anonymous"></script>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    gs.config({
      client_id: 'YOUR_CLIENT_ID',
      session_id: crypto.randomUUID(),
      gps: 'prompt',
      behavior: true,
    });
  });
</script>

Pin to the immutable /v1/gs.js URL in production and publish the matching integrity hash from dist/sri.json. /latest/gs.js exists for staging only.

API

gs.config(options)

Call once on page load. Behavioral capture starts immediately so dynamics accumulate across the full page lifetime.

| Option | Type | Default | Purpose | |--------|------|---------|---------| | client_id | string \| null | null | Stamped into the token. | | session_id | string | auto UUID | Use a fresh value per protected action. | | gps | 'off' \| 'silent' \| 'prompt' \| 'required' | 'prompt' | GPS consent state machine. off/silent never prompt. | | behavior | boolean | true | Always-on behavioral biometrics (timing only). | | persistence | boolean | true | Persist the long-lived true_device_id. Set false for GDPR mode. | | max_wait_time | number (ms) | 4000 | Hard wall-clock budget for all collectors before the token seals. | | sandbox | boolean | false | Emit an unencrypted sandbox payload for gk_test_ keys. | | debug | boolean | false | Verbose console.info logging. |

gs.getSession(): Promise<string>

Mints a fresh, single-use opaque token (~6–10 KB). Generate one per protected user-action. Tokens are single-use and expire after 5 minutes (30s skew); replaying a token returns 409 DEVICE_TOKEN_REPLAYED from /fraud-check.

With gps: 'required', getSession() throws GpsRequiredError (code: "GPS_REQUIRED") when location was not captured.

gs.getDeviceId(): Promise<string>

Returns just the persistent device identity (true_device_id) without minting a full token.

gs.getLastGps(): GpsSignals | null

Returns the last GPS block captured by getSession() — useful for integration diagnostics.

Backend handoff

Your backend forwards the token straight through to /fraud-check under any of session, device_token, gs_session, or sessionKey. Verified device identity and GPS from the token override any caller-supplied device_info / device_fingerprint.

await fetch('https://<edge>/fraud-check', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
  body: JSON.stringify({ action_type: 'login', email, ip, session }),
});

See the full integration guide: docs/DEVELOPER_INTEGRATION.md.

Sandbox mode

With sandbox: true, getSession() returns an unencrypted payload prefixed gsds_sandbox.. Paired with a gk_test_ API key the backend returns mock responses and stores zero rows — ideal for local integration testing.

Browser support

Chromium-based browsers and recent Firefox/Safari. Individual collectors fail-soft to null when an API is unavailable, so the token always seals within max_wait_time. The SDK uses no inline scripts and no unsafe-eval (CSP-safe).

Local development

npm ci          # in packages/gs-web-sdk
npm run build:sri   # build dist/ + dist/sri.json
npm test

Releasing

See docs/web-sdk-publishing.md. Releases publish to npm automatically when a sdk-v<x.y.z> git tag is pushed.

Roadmap

Planned signal extensions (specs, not yet shipped) are tracked in docs/web-sdk-roadmap.md.