@keverdjs/fraud-sdk-react 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Keverd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,340 @@
+# @keverdjs/fraud-sdk-react
+
+React SDK for Keverd fraud detection and device fingerprinting. This SDK provides real-time risk assessment by analyzing device characteristics, behavioral biometrics, and session patterns.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```bash
+npm install @keverdjs/fraud-sdk-react
+```
+
+or
+
+```bash
+yarn add @keverdjs/fraud-sdk-react
+```
+
+## Quick Start
+
+### 1. Wrap your application with KeverdProvider
+
+In your `_app.tsx` (Next.js) or root component:
+
+```tsx
+import { KeverdProvider } from '@keverdjs/fraud-sdk-react';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <KeverdProvider
+      loadOptions={{
+        apiKey: 'your-api-key-here',
+      }}
+    >
+      <Component {...pageProps} />
+    </KeverdProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### 2. Use the hook in your components
+
+```tsx
+import { useKeverdVisitorData } from '@keverdjs/fraud-sdk-react';
+
+export default function Home() {
+  const { isLoading, error, data, getData } = useKeverdVisitorData({
+    immediate: true, // Automatically fetch on mount
+    extendedResult: true,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>Risk Score: {data?.riskScore}%</h1>
+      <p>Action: {data?.action}</p>
+      <p>Reasons: {data?.reasons.join(', ')}</p>
+      <button onClick={() => getData()}>Refresh Data</button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### KeverdProvider
+
+The provider component that initializes the SDK and makes it available to child components.
+
+**Props:**
+
+```typescript
+interface KeverdProviderProps {
+  loadOptions: KeverdLoadOptions;
+  children: React.ReactNode;
+}
+```
+
+**KeverdLoadOptions:**
+
+```typescript
+interface KeverdLoadOptions {
+  apiKey: string;              // Required: Your Keverd API key
+  endpoint?: string;           // Optional: Custom API endpoint (default: https://app.keverd.com)
+  debug?: boolean;             // Optional: Enable debug logging (default: false)
+}
+```
+
+### useKeverdVisitorData
+
+Hook to access visitor data and risk assessment results.
+
+**Usage:**
+
+```tsx
+const { 
+  data,           // KeverdVisitorData | null
+  isLoading,      // boolean
+  error,          // KeverdError | null
+  getData         // () => Promise<void>
+} = useKeverdVisitorData(options?);
+```
+
+**Options:**
+
+```typescript
+interface KeverdVisitorDataHookOptions {
+  extendedResult?: boolean;    // Include extended device/session info (default: false)
+  immediate?: boolean;          // Automatically fetch data on mount (default: false)
+  ignoreCache?: boolean;        // Ignore cached data (default: false)
+}
+```
+
+**Return Value:**
+
+```typescript
+interface KeverdVisitorDataResult {
+  isLoading: boolean;          // Loading state
+  error: KeverdError | null;   // Error if any
+  data: KeverdVisitorData | null; // Visitor data
+  getData: (options?: KeverdVisitorDataOptions) => Promise<KeverdVisitorData>;
+}
+
+interface KeverdVisitorData {
+  visitorId: string;
+  riskScore: number;           // 0-100
+  score: number;               // 0.0-1.0
+  action: 'allow' | 'soft_challenge' | 'hard_challenge' | 'block';
+  reasons: string[];           // Array of risk reasons
+  sessionId: string;           // Session identifier
+  requestId: string;           // Request identifier
+  simSwapEngine?: KeverdSimSwapEngine; // SIM swap detection (null for web)
+  confidence?: number;         // Confidence score (if available)
+}
+```
+
+### useKeverdContext
+
+Hook to access the underlying SDK instance (for advanced usage).
+
+```tsx
+import { useKeverdContext } from '@keverdjs/fraud-sdk-react';
+
+const sdk = useKeverdContext();
+// Use sdk methods directly
+```
+
+## Configuration
+
+### Custom Endpoint
+
+If you're using a custom backend endpoint:
+
+```tsx
+<KeverdProvider
+  loadOptions={{
+    apiKey: 'your-api-key',
+    endpoint: 'https://api.yourdomain.com/v1/fingerprint/score',
+  }}
+>
+  {children}
+</KeverdProvider>
+```
+
+### Debug Mode
+
+Enable debug logging for development:
+
+```tsx
+<KeverdProvider
+  loadOptions={{
+    apiKey: 'your-api-key',
+    debug: true,
+  }}
+>
+  {children}
+</KeverdProvider>
+```
+
+## Data Collection
+
+The SDK automatically collects:
+
+- **Device Information**: Screen resolution, timezone, language, user agent
+- **Device Fingerprinting**: Canvas, WebGL fingerprints
+- **Behavioral Biometrics**: Typing patterns, mouse movements, scroll behavior
+- **Session Information**: Session duration, page views, interactions
+
+**Note**: SIM data is not collected for web applications (only for mobile SDKs).
+
+## Error Handling
+
+The SDK provides error information through the `error` property:
+
+```tsx
+const { error } = useKeverdVisitorData();
+
+if (error) {
+  switch (error.code) {
+    case 'NETWORK_ERROR':
+      // Handle network issues
+      break;
+    case 'INVALID_API_KEY':
+      // Handle invalid API key
+      break;
+    case 'SDK_NOT_INITIALIZED':
+      // SDK not initialized
+      break;
+    default:
+      // Handle other errors
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions. All types are exported for use in your code:
+
+```typescript
+import type {
+  KeverdConfig,
+  KeverdLoadOptions,
+  KeverdVisitorData,
+  KeverdVisitorDataOptions,
+  KeverdVisitorDataHookOptions,
+  KeverdVisitorDataResult,
+  KeverdDeviceInfo,
+  KeverdSessionInfo,
+  KeverdBehavioralData,
+  KeverdError,
+} from '@keverdjs/fraud-sdk-react';
+
+## Next.js Integration
+
+The SDK works seamlessly with Next.js. Wrap your app in `_app.tsx`:
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import { KeverdProvider } from '@keverdjs/fraud-sdk-react';
+
+function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <KeverdProvider
+      loadOptions={{
+        apiKey: process.env.NEXT_PUBLIC_KEVERD_API_KEY!,
+      }}
+    >
+      <Component {...pageProps} />
+    </KeverdProvider>
+  );
+}
+
+export default MyApp;
+```
+
+For Next.js App Router, wrap your root layout:
+
+```tsx
+// app/layout.tsx
+import { KeverdProvider } from '@keverdjs/fraud-sdk-react';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        <KeverdProvider
+          loadOptions={{
+            apiKey: process.env.NEXT_PUBLIC_KEVERD_API_KEY!,
+          }}
+        >
+          {children}
+        </KeverdProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Advanced Usage
+
+### Manual Data Collection
+
+You can access the SDK instance directly for manual operations:
+
+```tsx
+import { useKeverdContext } from '@keverdjs/fraud-sdk-react';
+
+function MyComponent() {
+  const sdk = useKeverdContext();
+  
+  const handleManualCheck = async () => {
+    const result = await sdk.getVisitorData({ extendedResult: true });
+    console.log('Risk assessment:', result);
+  };
+
+  return <button onClick={handleManualCheck}>Check Risk</button>;
+}
+```
+
+### Using Collectors Directly
+
+For advanced use cases, you can use collectors directly:
+
+```tsx
+import { KeverdDeviceCollector, KeverdBehavioralCollector } from '@keverd/fraud-sdk-react';
+
+const deviceCollector = new KeverdDeviceCollector();
+const behavioralCollector = new KeverdBehavioralCollector();
+
+// Start collectors
+behavioralCollector.start();
+
+// Collect data manually
+const deviceInfo = deviceCollector.collect();
+const behavioralData = behavioralCollector.getData();
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/keverd/keverd-fraud-sdk-web).

package/dist/index.d.mts

@@ -0,0 +1,365 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Keverd Fraud SDK React - Type Definitions
+ */
+interface KeverdDeviceInfo {
+    deviceId: string;
+    fingerprint: string;
+    manufacturer?: string;
+    model?: string;
+    brand?: string;
+    device?: string;
+    product?: string;
+    hardware?: string;
+    sdkVersion?: string;
+    osVersion?: string;
+    screenWidth?: string;
+    screenHeight?: string;
+    screenDensity?: string;
+    locale?: string;
+    timezone: string;
+}
+interface KeverdSessionInfo {
+    sessionId?: string;
+    installId?: string;
+    sessionCount?: string;
+    firstSession?: string;
+    timestamp?: string;
+}
+interface KeverdBehavioralData {
+    typing_dwell_ms?: number[];
+    typing_flight_ms?: number[];
+    swipe_velocity?: number;
+    session_entropy?: number;
+}
+interface KeverdFingerprintRequest {
+    userId?: string;
+    device: KeverdDeviceInfo;
+    session?: KeverdSessionInfo;
+    behavioral?: KeverdBehavioralData;
+}
+interface KeverdSimSwapEngine {
+    userId?: string;
+    risk: number;
+    flags: {
+        sim_changed?: boolean;
+        device_changed?: boolean;
+        behavior_anomaly?: boolean;
+        time_anomaly?: boolean;
+        velocity_anomaly?: boolean;
+    };
+    updatedProfile?: Record<string, unknown>;
+}
+interface KeverdFingerprintResponse {
+    risk_score: number;
+    score: number;
+    action: 'allow' | 'soft_challenge' | 'hard_challenge' | 'block';
+    reason: string[];
+    session_id: string;
+    requestId: string;
+    sim_swap_engine?: KeverdSimSwapEngine;
+}
+interface KeverdVisitorData {
+    visitorId: string;
+    riskScore: number;
+    score: number;
+    action: 'allow' | 'soft_challenge' | 'hard_challenge' | 'block';
+    reasons: string[];
+    sessionId: string;
+    requestId: string;
+    simSwapEngine?: KeverdSimSwapEngine;
+    confidence?: number;
+}
+interface KeverdConfig {
+    apiKey: string;
+    endpoint?: string;
+    userId?: string;
+    debug?: boolean;
+    extendedResult?: boolean;
+    ignoreCache?: boolean;
+}
+interface KeverdLoadOptions {
+    apiKey: string;
+    endpoint?: string;
+    debug?: boolean;
+}
+interface KeverdVisitorDataOptions {
+    extendedResult?: boolean;
+    ignoreCache?: boolean;
+    tag?: string;
+}
+interface KeverdVisitorDataHookOptions {
+    extendedResult?: boolean;
+    immediate?: boolean;
+    ignoreCache?: boolean;
+}
+interface KeverdError {
+    message: string;
+    code?: string;
+    statusCode?: number;
+}
+interface KeverdVisitorDataResult$1 {
+    isLoading: boolean;
+    error: KeverdError | null;
+    data: KeverdVisitorData | null;
+    getData: (options?: KeverdVisitorDataOptions) => Promise<KeverdVisitorData>;
+}
+
+/**
+ * Keverd Fraud SDK Core
+ * Main SDK class for fingerprinting and risk assessment
+ */
+
+declare class KeverdSDK {
+    private config;
+    private deviceCollector;
+    private behavioralCollector;
+    private isInitialized;
+    private sessionId;
+    constructor();
+    /**
+     * Initialize the SDK with configuration
+     */
+    init(config: KeverdConfig): void;
+    /**
+     * Get visitor data (fingerprint and risk assessment)
+     */
+    getVisitorData(options?: KeverdVisitorDataOptions): Promise<KeverdVisitorData>;
+    /**
+     * Send fingerprint request to backend
+     */
+    private sendFingerprintRequest;
+    /**
+     * Transform API response to visitor data format
+     */
+    private transformResponse;
+    /**
+     * Get default endpoint
+     */
+    private getDefaultEndpoint;
+    /**
+     * Generate a session ID
+     */
+    private generateSessionId;
+    /**
+     * Destroy the SDK instance
+     */
+    destroy(): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): KeverdConfig | null;
+    /**
+     * Check if SDK is initialized
+     */
+    isReady(): boolean;
+}
+
+interface KeverdContextValue {
+    sdk: KeverdSDK;
+    isReady: boolean;
+}
+interface KeverdProviderProps {
+    loadOptions: KeverdLoadOptions;
+    children: ReactNode;
+}
+/**
+ * KeverdProvider - Wrap your app with this component to enable Keverd SDK
+ */
+declare function KeverdProvider({ loadOptions, children }: KeverdProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Keverd SDK from context
+ */
+declare function useKeverdContext(): KeverdContextValue;
+
+/**
+ * useKeverdVisitorData Hook
+ * React hook for accessing visitor data and risk assessment
+ */
+
+interface KeverdVisitorDataResult {
+    isLoading: boolean;
+    error: KeverdError | null;
+    data: KeverdVisitorData | null;
+    getData: (options?: KeverdVisitorDataOptions) => Promise<KeverdVisitorData>;
+}
+/**
+ * Hook to get visitor data and risk assessment
+ *
+ * @param options - Configuration options for the hook
+ * @returns Object containing loading state, error, data, and getData function
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isLoading, error, data, getData } = useKeverdVisitorData({
+ *     extendedResult: true,
+ *     immediate: true
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Risk Score: {data?.riskScore}</p>
+ *       <p>Action: {data?.action}</p>
+ *       <button onClick={() => getData({ ignoreCache: true })}>
+ *         Reload data
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useKeverdVisitorData(options?: KeverdVisitorDataHookOptions): KeverdVisitorDataResult;
+
+/**
+ * Keverd Device Fingerprint Collector
+ * Collects device information, canvas fingerprint, WebGL fingerprint, and generates a stable device ID
+ */
+
+declare class KeverdDeviceCollector {
+    private cachedDeviceInfo;
+    /**
+     * Collect all device information and generate fingerprint
+     */
+    collect(): KeverdDeviceInfo;
+    /**
+     * Generate a stable device fingerprint using multiple browser characteristics
+     * Returns SHA-256 hash (64 hex characters) as required by backend
+     */
+    private generateDeviceFingerprint;
+    /**
+     * Generate canvas fingerprint
+     */
+    private getCanvasFingerprint;
+    /**
+     * Generate WebGL fingerprint
+     */
+    private getWebGLFingerprint;
+    /**
+     * Generate a stable device ID from fingerprint
+     */
+    private generateDeviceId;
+    /**
+     * Get manufacturer from user agent
+     */
+    private getManufacturer;
+    /**
+     * Get model from user agent
+     */
+    private getModel;
+    /**
+     * Get brand from user agent
+     */
+    private getBrand;
+    /**
+     * Get device type
+     */
+    private getDevice;
+    /**
+     * Get product name
+     */
+    private getProduct;
+    /**
+     * Get hardware info
+     */
+    private getHardware;
+    /**
+     * Get OS version
+     */
+    private getOSVersion;
+    /**
+     * Get screen density
+     */
+    private getScreenDensity;
+    /**
+     * Hash a string using SHA-256 (required for backend compatibility)
+     * Backend expects SHA-256 hash (64 hex characters)
+     * Uses Web Crypto API synchronously via a cached approach
+     */
+    private hashString;
+    /**
+     * SHA-256-like hash function (synchronous, deterministic)
+     * Produces 64-character hex string matching SHA-256 format
+     * This is a deterministic hash that mimics SHA-256 characteristics
+     */
+    private sha256LikeHash;
+    /**
+     * Clear cached device info (useful for testing)
+     */
+    clearCache(): void;
+}
+
+/**
+ * Keverd Behavioral Data Collector
+ * Collects typing patterns, mouse movements, swipe gestures, and calculates session entropy
+ */
+
+declare class KeverdBehavioralCollector {
+    private keystrokes;
+    private mouseMovements;
+    private lastKeyDownTime;
+    private lastKeyUpTime;
+    private isActive;
+    private sessionStartTime;
+    private typingDwellTimes;
+    private typingFlightTimes;
+    private swipeVelocities;
+    private sessionEvents;
+    private touchStartPositions;
+    private keyDownHandler;
+    private keyUpHandler;
+    private mouseMoveHandler;
+    private touchStartHandler;
+    private touchEndHandler;
+    /**
+     * Start collecting behavioral data
+     */
+    start(): void;
+    /**
+     * Stop collecting behavioral data
+     */
+    stop(): void;
+    /**
+     * Get collected behavioral data
+     */
+    getData(): KeverdBehavioralData;
+    /**
+     * Reset collected data
+     */
+    reset(): void;
+    /**
+     * Handle keydown event
+     */
+    private handleKeyDown;
+    /**
+     * Handle keyup event
+     */
+    private handleKeyUp;
+    /**
+     * Handle mouse move event
+     */
+    private handleMouseMove;
+    /**
+     * Handle touch start (for swipe detection)
+     */
+    private handleTouchStart;
+    /**
+     * Handle touch end (calculate swipe velocity)
+     */
+    private handleTouchEnd;
+    /**
+     * Calculate session entropy based on event diversity
+     */
+    private calculateSessionEntropy;
+    /**
+     * Check if key should be ignored
+     */
+    private shouldIgnoreKey;
+}
+
+export { KeverdBehavioralCollector, type KeverdBehavioralData, type KeverdConfig, KeverdDeviceCollector, type KeverdDeviceInfo, type KeverdError, type KeverdFingerprintRequest, type KeverdFingerprintResponse, type KeverdLoadOptions, KeverdProvider, KeverdSDK, type KeverdSessionInfo, type KeverdSimSwapEngine, type KeverdVisitorData, type KeverdVisitorDataHookOptions, type KeverdVisitorDataOptions, type KeverdVisitorDataResult$1 as KeverdVisitorDataResult, useKeverdContext, useKeverdVisitorData };