npm package: @guardianstack/guardianjs-server
Description: Server-side SDK for Guardian Fraud Detection: fetch processed events and utilities
Latest version: 0.2.2

# Guardian Server SDK

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

## Install

```bash
npm install @guardianstack/guardianjs-server
```

## Usage

```ts
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.

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

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

#### isBot(event)

Returns `true` if automation/bot signals were detected.

```ts
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.

```ts
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).

```ts
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.

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

#### isVirtualized(event)

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

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

#### getRiskScoreSummary(event)

Returns a compact set of numeric scores, if available.

```ts
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.

```ts
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.

```ts
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.

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

#### Additional getters

```ts
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.