genuine-verify-sdk/dist/index.d.mts

Privacy-first human verification widget using React, Next.js, and TensorFlow.js

import * as React from 'react';
import React__default from 'react';

interface PresenceToken {
    token: string;
    gesture: 'blink' | 'headTilt';
    issuedAt: string;
    expiresAt: string;
    version: number;
}

interface GenuineWidgetProps {
    gestureType: 'blink' | 'headTilt';
    onSuccess: (token: PresenceToken) => void;
    onError?: (error: Error) => void;
    onTokenExpired?: () => void;
    debug?: boolean;
    blinkThreshold?: number;
    headTiltThreshold?: number;
    showGestureFeedback?: boolean;
    persist?: boolean;
    trigger?: 'auto' | 'manual';
    onStartRef?: (startFn: () => void) => void;
    tokenTTL?: number;
    showExpirationWarning?: boolean;
    autoRefreshOnExpiry?: boolean;
    theme?: 'light' | 'dark';
    instructionalText?: string;
    instructionalTextStyle?: React__default.CSSProperties;
}
declare const GenuineWidget: React__default.FC<GenuineWidgetProps>;

interface FailureContext {
    /** Reason for the failure */
    reason: 'max_attempts_reached' | 'gesture_timeout' | 'camera_error' | 'model_error' | 'unknown';
    /** Number of attempts made */
    attempts: number;
    /** Maximum attempts allowed */
    maxAttempts: number;
    /** Error details if available */
    error?: Error;
    /** Timestamp of the failure */
    timestamp: string;
}
interface GenuineWidgetEmbeddableProps {
    /** Callback when a valid token is issued with metadata */
    onTokenIssued: (payload: {
        token: string;
        metadata: {
            issuedAt: string;
            expiresAt: string;
            gestureType: string;
        };
    }) => void;
    /** Callback when gesture detection fails after max attempts */
    onFailure?: (context: FailureContext) => void;
    /** Token time-to-live in seconds (default: 300) */
    tokenTTL?: number;
    /** Show debug panel in development */
    debug?: boolean;
    /** Head tilt threshold in degrees (default: 15) */
    headTiltThreshold?: number;
    /** Persist token in sessionStorage (default: true) */
    persist?: boolean;
    /** Trigger mode: 'auto' starts immediately, 'manual' requires user action, 'manualStart' requires explicit programmatic start */
    trigger?: 'auto' | 'manual' | 'manualStart';
    /** Callback for manual start function */
    onStartRef?: (startFn: () => void) => void;
    /** Callback for errors */
    onError?: (error: Error) => void;
    /** Maximum attempts before triggering fallback (default: 3) */
    maxAttempts?: number;
    /** Custom fallback component to render when max attempts reached */
    fallback?: React__default.ComponentType<{
        failureContext: FailureContext;
        triggerRetry: () => void;
    }>;
}
declare const GenuineWidgetEmbeddable: React__default.FC<GenuineWidgetEmbeddableProps>;

type DetectionState = 'idle' | 'camera-active' | 'eyes-detected' | 'head-tilt-left' | 'head-tilt-right' | 'head-tilt-success' | 'success' | 'failed' | 'recovering';
interface UnifiedDetectionState {
    hasFace: boolean;
    hasEyes: boolean;
    gestureMatched: boolean;
    isStable: boolean;
    confidence: number;
    lastUpdate: number;
}
interface FacePosition {
    x: number;
    y: number;
    width: number;
    height: number;
}
interface HeadTiltMetrics {
    leftEyeY: number;
    rightEyeY: number;
    noseBridgeY: number;
    chinY: number;
    tiltAngle: number;
    tiltDirection: 'left' | 'right' | 'none';
    isTilted: boolean;
    tiltStartTime: number | null;
    smoothedAngle: number;
    confidence: number;
    isStable: boolean;
    faceAlignment: number;
}

interface GenuineUIProps {
    detectionState: DetectionState;
    unifiedDetectionState: UnifiedDetectionState;
    isCameraActive: boolean;
    isModelLoading: boolean;
    error: string | null;
    errorDetails: string;
    status: string;
    timeRemaining: number;
    countdownMessage: string;
    facePosition: FacePosition | null;
    eyesDetected: boolean;
    positioningMessage: string;
    videoRef: React__default.RefObject<HTMLVideoElement>;
    canvasRef: React__default.RefObject<HTMLCanvasElement>;
    onStart: () => void;
    onReset: () => void;
    theme?: 'light' | 'dark';
    instructionalText?: string;
    instructionalTextStyle?: React__default.CSSProperties;
}
declare const GenuineUI: React__default.FC<GenuineUIProps>;

type DebugPanelMiniProps = {
    status: string;
    confidence: number;
    token?: string;
};
declare const DebugPanelMini: React__default.FC<DebugPanelMiniProps>;

interface ExpirationWarningProps {
    timeRemaining: number;
    onRefresh?: () => void;
    onDismiss?: () => void;
    formatTimeRemaining: (ms: number) => string;
    theme?: 'light' | 'dark';
}
declare const ExpirationWarning: React__default.FC<ExpirationWarningProps>;

/**
 * Token validation result interface
 */
interface TokenValidationResult {
    valid: boolean;
    reason: string | null;
    gestureType?: string;
    expiresIn?: number;
    issuedAt?: string;
}
/**
 * Token error types
 */
type TokenError = 'MISSING_TOKEN' | 'MALFORMED_TOKEN' | 'INVALID_STRUCTURE' | 'EXPIRED_TOKEN' | 'ALREADY_USED' | 'UNKNOWN_ERROR';
/**
 * Get a presence token for the specified gesture
 * @param gesture - The gesture type ('blink' | 'headTilt')
 * @param ttlMs - Time to live in milliseconds (default: 5 minutes)
 * @returns PresenceToken object
 */
declare function createPresenceToken(gesture: 'blink' | 'headTilt', ttlMs?: number): PresenceToken;
/**
 * Verify a token string and return validation result
 * @param token - The token string to verify
 * @param options - Verification options
 * @returns Promise<TokenValidationResult>
 */
declare function verifyToken(token: string, options?: {
    oneTimeUse?: boolean;
    baseUrl?: string;
}): Promise<TokenValidationResult>;
/**
 * Get token from storage (localStorage/sessionStorage)
 * @param key - Storage key (default: 'genuine-verify-token')
 * @param storage - Storage type ('localStorage' | 'sessionStorage', default: 'sessionStorage')
 * @returns string | null
 */
declare function getStoredToken$1(key?: string, storage?: 'localStorage' | 'sessionStorage'): string | null;
/**
 * Store token in storage
 * @param token - Token string to store
 * @param key - Storage key (default: 'genuine-verify-token')
 * @param storage - Storage type ('localStorage' | 'sessionStorage', default: 'sessionStorage')
 * @returns boolean - Success status
 */
declare function storeToken(token: string, key?: string, storage?: 'localStorage' | 'sessionStorage'): boolean;
/**
 * Clear stored token
 * @param key - Storage key (default: 'genuine-verify-token')
 * @param storage - Storage type ('localStorage' | 'sessionStorage', default: 'sessionStorage')
 * @returns boolean - Success status
 */
declare function clearStoredToken(key?: string, storage?: 'localStorage' | 'sessionStorage'): boolean;
/**
 * Check if a stored token is valid
 * @param key - Storage key (default: 'genuine-verify-token')
 * @param storage - Storage type ('localStorage' | 'sessionStorage', default: 'sessionStorage')
 * @returns Promise<boolean>
 */
declare function isStoredTokenValid(key?: string, storage?: 'localStorage' | 'sessionStorage'): Promise<boolean>;
/**
 * Development helper: Create a mock token for testing
 * @param gesture - Gesture type
 * @param expired - Whether the token should be expired
 * @returns PresenceToken
 */
declare function createMockToken(gesture?: 'blink' | 'headTilt', expired?: boolean): PresenceToken;

interface GenuineDetectionOptions {
    videoElement?: HTMLVideoElement;
    canvasElement?: HTMLCanvasElement;
}
declare function useGenuineDetection(options?: GenuineDetectionOptions & {
    gestureType?: 'headTilt';
    headTiltThreshold?: number;
    onSuccess?: (token: string) => void;
    onError?: (error: Error) => void;
    persist?: boolean;
    trigger?: 'auto' | 'manual';
    onStartRef?: (startFn: () => void) => void;
    debug?: boolean;
}): {
    detectionState: DetectionState;
    isCameraActive: boolean;
    isModelLoaded: boolean;
    isModelLoading: boolean;
    error: string | null;
    errorDetails: string;
    status: string;
    timeRemaining: number;
    countdownMessage: string;
    facePosition: FacePosition | null;
    eyesDetected: boolean;
    positioningMessage: string;
    verified: boolean;
    unifiedDetectionState: UnifiedDetectionState;
    gestureMatched: boolean;
    confidenceScore: number;
    fps: number;
    tokenStatus: {
        token: PresenceToken | null;
        expiresAt: string | undefined;
    };
    videoRef: React.MutableRefObject<HTMLVideoElement | null>;
    canvasRef: React.MutableRefObject<HTMLCanvasElement | null>;
    handleStartCamera: () => Promise<void>;
    handleCleanup: () => void;
    clearDetectionInterval: () => void;
    resetDetectionState: () => void;
    clearToken: () => void;
    headTiltMetrics: HeadTiltMetrics | null;
    manualStartFn: () => void;
};

declare function getStoredToken(): PresenceToken | null;
declare function usePresenceToken(persist?: boolean): {
    token: PresenceToken | null;
    isValid: boolean;
    saveToken: (token: PresenceToken) => void;
    clearToken: () => void;
    getStoredToken: typeof getStoredToken | undefined;
};

interface UseTokenTTLOptions {
    onTokenExpired?: () => void;
    showExpirationWarning?: boolean;
    autoRefreshOnExpiry?: boolean;
    warningThreshold?: number;
}
declare function useTokenTTL(token: PresenceToken | null, ttlMs?: number, // 5 minutes default
options?: UseTokenTTLOptions): {
    isExpired: boolean;
    isExpiringSoon: boolean;
    timeUntilExpiry: number | null;
    timeUntilWarning: number | null;
    formatTimeRemaining: (ms: number) => string;
    clearIntervals: () => void;
};

interface VerificationStatus {
    /** Whether the user is currently verified */
    isVerified: boolean;
    /** The current token (if valid) */
    token: string | null;
    /** Time remaining in seconds (null if not verified) */
    expiresIn: number | null;
    /** Whether the token is expiring soon (within 60 seconds) */
    isExpiringSoon: boolean;
    /** Formatted time remaining string */
    timeRemaining: string | null;
    /** Clear the stored token */
    clearToken: () => void;
    /** Refresh the verification status */
    refresh: () => void;
}
declare const useVerificationStatus: () => VerificationStatus;

interface GenuineTriggerControls {
    /** Start detection programmatically */
    startDetection: () => void;
    /** Stop detection and cleanup */
    stopDetection: () => void;
    /** Reset detection state */
    resetDetection: () => void;
    /** Check if detection is currently active */
    isDetectionActive: boolean;
    /** Check if model is loaded and ready */
    isModelReady: boolean;
}
interface UseGenuineTriggerOptions {
    /** Whether to auto-start detection when the hook is called */
    autoStart?: boolean;
    /** Callback when detection starts */
    onStart?: () => void;
    /** Callback when detection stops */
    onStop?: () => void;
    /** Callback when detection resets */
    onReset?: () => void;
}
declare const useGenuineTrigger: (startFn: (() => void) | null, stopFn: (() => void) | null, resetFn: (() => void) | null, isActive?: boolean, isModelReady?: boolean, options?: UseGenuineTriggerOptions) => GenuineTriggerControls;

interface GenuineAnalytics {
    successCount: number;
    failureCount: number;
    attemptCount: number;
    fps: number;
    lastEvent: 'success' | 'failure' | 'attempt' | null;
    log: (msg: string) => void;
    clear: () => void;
}
interface UseGenuineAnalyticsOptions {
    /** Enable localStorage persistence (default: false) */
    persist?: boolean;
    /** Enable console logging (default: true) */
    logToConsole?: boolean;
}
interface AnalyticsDetectionState {
    isCameraActive: boolean;
    gestureMatched: boolean;
    detectionState: string;
    fps: number;
}
declare function useGenuineAnalytics(detectionState: AnalyticsDetectionState, options?: UseGenuineAnalyticsOptions): {
    successCount: number;
    failureCount: number;
    attemptCount: number;
    fps: number;
    lastEvent: "success" | "failure" | "attempt" | null;
    log: (msg: string) => void;
    clear: () => void;
};

declare const DEFAULT_THRESHOLDS: {
    blinkThreshold: number;
    headTiltThreshold: number;
};

declare const VERSION = "0.1.0";

export { type AnalyticsDetectionState, DEFAULT_THRESHOLDS, DebugPanelMini as DebugPanel, type DetectionState, ExpirationWarning, type FacePosition, type GenuineAnalytics, type GenuineTriggerControls, GenuineUI, GenuineWidget, GenuineWidgetEmbeddable, type GenuineWidgetEmbeddableProps, type GenuineWidgetProps, type HeadTiltMetrics, type PresenceToken, type TokenError, type TokenValidationResult, type UnifiedDetectionState, type UseGenuineAnalyticsOptions, type UseGenuineTriggerOptions, VERSION, type VerificationStatus, clearStoredToken, createMockToken, createPresenceToken, getStoredToken$1 as getStoredToken, isStoredTokenValid, storeToken, useGenuineAnalytics, useGenuineDetection, useGenuineTrigger, usePresenceToken, useTokenTTL, useVerificationStatus, verifyToken };