@harev/client

Browser Client for the Harev revenue recovery platform. Detects account sharing through behavioral telemetry, scores risk in real-time, and converts unauthorized usage into paid seats.

Install

npm install @harev/client

Or load via CDN:

<script src="https://cdn.jsdelivr.net/npm/@harev/[email protected]"></script>

Quick Start

import harev from '@harev/client';

harev.init({
  apiKey: 'pk_test_your_public_key',
  endpoint: 'https://t.harev.io/v1',
  mode: 'telemetry+evaluate',
  userId: currentUser.id,
  traits: {
    planType: currentUser.plan,
    seatCount: currentUser.seatCount,
  },
});

API Reference

init(config)

Initialize the Client. Must be called before any other method.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | (required) | Public API key for your tenant | | endpoint | string | https://t.harev.io/v1 | API base URL | | mode | 'telemetry-only' | 'telemetry+evaluate' | 'telemetry-only' | Runtime mode | | userId | string | — | Current user identifier | | traits | object | — | User traits (planType, seatCount, etc.) | | debug | boolean | false | Enable console error logging | | signalsLevel | 'standard' | 'essential' | 'standard' | Data collection tier — device signals and session tracking (see Signal Collection) |

identify(userId, traits?)

Update the current user context. Sends a telemetry event on each call.

evaluate(context?)

Request a risk evaluation from the API. Returns a decision and optional recommendation. Only available in telemetry+evaluate mode.

const result = await harev.evaluate({ currentPage: '/dashboard' });

if (result.ok) {
  console.log(result.decision.action);     // 'ALLOW' | 'SHOW_UPGRADE'
  console.log(result.decision.riskScore);  // 0.0 – 1.0
  console.log(result.recommendation);      // CTA + message + suggested plan
} else {
  console.log(result.reason); // 'not_initialized' | 'mode' | 'backend'
}

destroy()

Tear down the Client, end the current session, and release resources. Safe to call multiple times.

on(event, handler) / off(event, handler)

Subscribe to Client events:

| Event | Payload | |-------|---------| | decision | { action, riskScore, reasons, sessionId, scoringPhase } | | error | { code, message, source } | | session_start | { sessionId, timestamp } | | session_end | { sessionId, timestamp, reason } |

harev.on('decision', (decision) => {
  if (decision.action === 'SHOW_UPGRADE') {
    showUpgradeModal(decision);
  }
});

harev.on('error', (error) => {
  console.error(error.code, error.message);
});

Telemetry-Only Mode

Use when you want signal collection without runtime decisions:

harev.init({
  apiKey: 'pk_test_your_public_key',
  mode: 'telemetry-only',
});

const result = await harev.evaluate();
// { ok: false, reason: 'mode' }

Signal Collection

The Client collects device-level signals and session metrics to power the Harev risk scoring engine. These signals help detect account sharing patterns (device diversity, timezone spread, geo-velocity). The collection granularity is controlled by the signalsLevel config option.

standard (default)

Full collection for maximum risk accuracy. Includes all device signals and session behavioral tracking.

Device signals:

| Signal | Source | Purpose | |--------|--------|---------| | timezone | Intl.DateTimeFormat | Timezone spread detection | | language | navigator.language | Locale mismatch detection | | screenWidth | screen.width | Device fingerprinting | | screenHeight | screen.height | Device fingerprinting | | devicePixelRatio | window.devicePixelRatio | Device fingerprinting | | platform | navigator.platform | Device diversity scoring | | userAgent | navigator.userAgent | Device diversity scoring | | touchSupport | navigator.maxTouchPoints | Device category hint |

Session tracking: heartbeat (30s intervals), focus/blur count, visibility changes.

essential

Minimal collection for privacy-conscious integrations. Preserves the two core risk scoring signals (timezone and language) and session duration, while omitting device fingerprinting and user behavior tracking.

Device signals: timezone, language only.

Session tracking: heartbeat only (no focus/blur/visibility metrics).

// Default — full collection for maximum risk accuracy
harev.init({ apiKey: '...' });
// or explicitly:
harev.init({ apiKey: '...', signalsLevel: 'standard' });

// Privacy-conscious — timezone + language + session duration only
harev.init({ apiKey: '...', signalsLevel: 'essential' });

The 'essential' tier preserves the two highest-value risk scoring rules (GEO_IMPLAISIBLE and TIMEZONE_SPREAD) while omitting uniquely identifying signals like screen dimensions, platform, user agent, and user behavior metrics. No raw fingerprint values are ever transmitted — all data is sent as structured telemetry fields.

License

See harev.io.