Guardian Server SDK

Server-side SDK to retrieve processed fraud detection events and quickly assess risk categories.

Install

npm install @guardianstack/guardianjs-server

Usage

import {
  createGuardianClient,
  isBot,
  isVPN,
  isIncognito,
  isTampering,
  isPrivacySettings,
  isVirtualized,
} from "@guardianstack/guardianjs-server";

const client = createGuardianClient({
  secret: process.env.GUARDIAN_SECRET!,
});

// Fetch processed event
const event = await client.getEvent("evt_123");

// Primary detections
const detected = {
  bot: isBot(event),
  vpn: isVPN(event),
  incognito: isIncognito(event),
  tampering: isTampering(event),
  privacy: isPrivacySettings(event),
  virtualized: isVirtualized(event),
};

// Example gating
if (detected.bot || detected.vpn || detected.tampering || detected.virtualized) {
  // block, challenge, or add friction
}

API

• createGuardianClient(options) → GuardianServerClient
  • options.secret string (required)
  • options.fetch? custom fetch implementation
  • options.timeoutMs? request timeout (default 10000)
• client.getEvent(eventId) → ProcessedEventResponse

Helpers

All helpers are null-safe and accept ProcessedEventResponse | null | undefined.

isVPN(event)

Returns true if VPN/proxy is detected.

function isVPN(evt?: ProcessedEventResponse | null): boolean;

if (isVPN(event)) {
  // e.g. require additional verification
}

isBot(event)

Returns true if automation/bot signals were detected.

function isBot(evt?: ProcessedEventResponse | null): boolean;

if (isBot(event)) {
  // throttle, challenge, or block
}

isIncognito(event)

Returns true if an incognito/private mode fingerprint was recognized.

function isIncognito(evt?: ProcessedEventResponse | null): boolean;

isTampering(event)

Returns true when signs of environment tampering are present (e.g. anti-detect browser, spoofed APIs, abnormal entropy).

function isTampering(evt?: ProcessedEventResponse | null): boolean;

isPrivacySettings(event)

Returns true when aggressive privacy features are detected (e.g. fingerprinting protections, content blocking) that impact signal quality.

function isPrivacySettings(evt?: ProcessedEventResponse | null): boolean;

isVirtualized(event)

Returns true when the session appears to run in a VM/emulated environment.

function isVirtualized(evt?: ProcessedEventResponse | null): boolean;

getRiskScoreSummary(event)

Returns a compact set of numeric scores, if available.

function getRiskScoreSummary(evt?: ProcessedEventResponse | null): {
  bot?: number;
  tampering?: number;
  privacy?: number;
  incognito?: number;
};

const scores = getRiskScoreSummary(event);
// Example decision
if ((scores.bot ?? 0) >= 80 || (scores.tampering ?? 0) >= 80) {
  // high-risk
}

getLocation(event)

Returns the geolocation payload or null when not available.

function getLocation(evt?: ProcessedEventResponse | null): {
  is_eu_member?: boolean;
  calling_code?: string;
  currency_code?: string;
  continent?: string;
  country?: string;
  country_code?: string;
  state?: string;
  city?: string;
  latitude?: number;
  longitude?: number;
  zip?: string;
  timezone?: string;
  local_time?: string;
  is_dst?: boolean;
} | null;

const loc = getLocation(event);

getBrowser(event)

Returns parsed browser info.

function getBrowser(evt?: ProcessedEventResponse | null):
  | {
      browserName?: string;
      browserMajorVersion?: string;
      browserFullVersion?: string;
      os?: string;
      osVersion?: string;
      device?: string;
      userAgent?: string;
    }
  | undefined;

getIp(event)

Returns the client IP string when available.

function getIp(evt?: ProcessedEventResponse | null): string | undefined;

Additional getters

getEventId(evt): string | undefined;
getTimestamp(evt): string | undefined; // ISO timestamp
getUrl(evt): string | undefined;
isEU(evt): boolean;
getCountry(evt): string | undefined;
getCountryCode(evt): string | undefined;
getContinent(evt): string | undefined;
getRegion(evt): string | undefined; // state / region
getCity(evt): string | undefined;
getCoordinates(evt): { latitude?: number; longitude?: number } | null;
getTimezone(evt): string | undefined;
getTimezones(evt): { browserTimezone?: string; ipTimezone?: string };
getTimezoneDifference(evt): number | undefined; // minutes
getVpnConfidence(evt): string | undefined;
getVpnReason(evt): string | undefined;
getBotScore(evt): number | undefined;
getTamperingScore(evt): number | undefined;
getPrivacyScore(evt): number | undefined;
getIncognitoScore(evt): number | undefined;
getBotIndicators(evt): { source: string; severity: string }[];
getTamperingIndicators(evt): { source: string; severity: string }[];
getPrivacyIndicators(evt): { source: string; severity: string }[];
getIncognitoIndicators(evt): { source: string; severity: string }[];
getVirtualizationIndicators(evt): { source: string; confidence: string }[];
getVirtualizationConfidence(evt): string | undefined;
getUserAgent(evt): string | undefined;
getBrowserName(evt): string | undefined;
getBrowserMajorVersion(evt): string | undefined;
getBrowserFullVersion(evt): string | undefined;
getOs(evt): string | undefined;
getOsVersion(evt): string | undefined;
getDevice(evt): string | undefined;
getIpInfo(evt): any; // sanitized IP data (whois removed)
getIspName(evt): string | undefined;
getOrganization(evt): string | undefined; // ASN org name
getAsn(evt): string | number | undefined;
getVelocity(evt): { "5m": number; "1h": number; "24h": number } | undefined;
getVisitorVelocity(evt): { "5m": number; "1h": number; "24h": number; "7d": number } | undefined;

Types

• ProcessedEventResponse mirrors backend response shape.