@keverdjs/fraud-sdk

Vanilla JavaScript SDK for Keverd fraud detection and device fingerprinting. Works in any JavaScript environment (browser, Node.js, etc.).

Installation

npm install @keverdjs/fraud-sdk

Quick Start

import { Keverd } from '@keverdjs/fraud-sdk';

// Initialize with API key
Keverd.init('your-api-key');

// Get visitor data and risk assessment
const result = await Keverd.getVisitorData();

console.log('Risk Score:', result.risk_score);
console.log('Action:', result.action);
console.log('Session ID:', result.session_id);

With Configuration Object

import { Keverd } from '@keverdjs/fraud-sdk';

// Initialize with configuration
Keverd.init({
  apiKey: 'your-api-key',
  endpoint: 'https://app.keverd.com', // Optional
  debug: true, // Optional: enable debug logging
});

// Get visitor data
const result = await Keverd.getVisitorData();

API Reference

Keverd.init(config)

Initialize the SDK with your API key.

Parameters:

• config (string | SDKConfig): API key string or configuration object

Example:

// Simple initialization
Keverd.init('your-api-key');

// With options
Keverd.init({
  apiKey: 'your-api-key',
  endpoint: 'https://app.keverd.com',
  userId: 'optional-user-id',
  debug: false
});

Keverd.getVisitorData()

Get visitor data and risk assessment. This is the main method for fraud detection.

Returns: Promise

Example:

const result = await Keverd.getVisitorData();

// Result structure:
// {
//   risk_score: 25,           // 0-100
//   score: 0.25,              // 0.0-1.0
//   action: 'allow',          // 'allow' | 'soft_challenge' | 'hard_challenge' | 'block'
//   reason: ['new_user'],     // Array of risk reasons
//   session_id: 'uuid',       // Session identifier
//   requestId: 'uuid',        // Request identifier
//   sim_swap_engine: {...}    // SIM swap detection results (null for web)
// }

Keverd.createTransactionID(metadata?)

Legacy method for backward compatibility. Returns the session ID from getVisitorData().

Parameters:

• metadata (TransactionMetadata, optional): Transaction metadata

Returns: Promise - Session ID

Example:

const transactionId = await Keverd.createTransactionID({
  amount: 1000,
  currency: 'KES',
  recipient: '254712345678'
});

Keverd.destroy()

Destroy the SDK instance and stop all data collection.

Example:

Keverd.destroy();

Response Structure

interface FingerprintResponse {
  risk_score: number;        // 0-100 risk score
  score: number;             // 0.0-1.0 normalized score
  action: 'allow' | 'soft_challenge' | 'hard_challenge' | 'block';
  reason: string[];          // Array of risk reasons
  session_id: string;        // UUID session identifier
  requestId: string;         // UUID request identifier
  sim_swap_engine?: {        // SIM swap detection (null for web SDKs)
    userId?: string;
    risk: number;
    flags: {
      sim_changed?: boolean;
      device_changed?: boolean;
      behavior_anomaly?: boolean;
      time_anomaly?: boolean;
      velocity_anomaly?: boolean;
    };
    updatedProfile?: Record<string, unknown>;
  };
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.