@facesmash/sdk 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,292 @@
+import PocketBase from 'pocketbase';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+/** Configuration for the FaceSmash client */
+interface FaceSmashConfig {
+    /** PocketBase API URL (default: https://api.facesmash.app) */
+    apiUrl?: string;
+    /** URL to load face-api.js models from (default: jsdelivr CDN) */
+    modelUrl?: string;
+    /** Minimum confidence for SSD MobileNet face detection (default: 0.3) */
+    minDetectionConfidence?: number;
+    /** Similarity threshold for face matching (default: 0.45) */
+    matchThreshold?: number;
+    /** Minimum quality score to accept a face scan (default: 0.2) */
+    minQualityScore?: number;
+    /** Maximum face templates stored per user (default: 10) */
+    maxTemplatesPerUser?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/** Resolved config with all defaults applied */
+interface ResolvedConfig {
+    apiUrl: string;
+    modelUrl: string;
+    minDetectionConfidence: number;
+    matchThreshold: number;
+    minQualityScore: number;
+    maxTemplatesPerUser: number;
+    debug: boolean;
+}
+/** Head pose estimation */
+interface HeadPose {
+    yaw: number;
+    pitch: number;
+    roll: number;
+    isFrontal: boolean;
+}
+/** Face size validation result */
+interface FaceSizeCheck {
+    isValid: boolean;
+    ratio: number;
+    reason?: string;
+}
+/** Lighting analysis */
+interface LightingAnalysis {
+    score: number;
+    brightness: number;
+    contrast: number;
+    evenness: number;
+    conditions: {
+        tooDark: boolean;
+        tooBright: boolean;
+        uneven: boolean;
+        optimal: boolean;
+    };
+}
+/** Full face analysis result */
+interface FaceAnalysis {
+    descriptor: Float32Array;
+    normalizedDescriptor: Float32Array;
+    confidence: number;
+    qualityScore: number;
+    lightingScore: number;
+    headPose: HeadPose;
+    faceSizeCheck: FaceSizeCheck;
+    eyeAspectRatio: number;
+    rejectionReason?: string;
+}
+/** Face match result */
+interface MatchResult {
+    isMatch: boolean;
+    similarity: number;
+    adaptedThreshold: number;
+}
+/** Multi-template match result */
+interface MultiTemplateMatchResult {
+    isMatch: boolean;
+    bestSimilarity: number;
+    avgSimilarity: number;
+    matchCount: number;
+}
+/** A stored face template */
+interface FaceTemplate {
+    id: string;
+    user_email: string;
+    descriptor: number[];
+    quality_score: number;
+    created: string;
+}
+/** A user profile from PocketBase */
+interface UserProfile {
+    id: string;
+    name: string;
+    email: string;
+    face_embedding: number[];
+    created: string;
+    updated: string;
+}
+/** Login result */
+interface LoginResult {
+    success: boolean;
+    user?: UserProfile;
+    similarity?: number;
+    error?: string;
+}
+/** Registration result */
+interface RegisterResult {
+    success: boolean;
+    user?: UserProfile;
+    error?: string;
+}
+/** Model loading progress callback */
+type OnProgress = (progress: number) => void;
+/** Event types emitted by the SDK */
+type FaceSmashEvent = {
+    type: 'models-loading';
+    progress: number;
+} | {
+    type: 'models-loaded';
+} | {
+    type: 'models-error';
+    error: string;
+} | {
+    type: 'face-detected';
+    analysis: FaceAnalysis;
+} | {
+    type: 'face-lost';
+} | {
+    type: 'login-start';
+} | {
+    type: 'login-success';
+    user: UserProfile;
+    similarity: number;
+} | {
+    type: 'login-failed';
+    error: string;
+    bestSimilarity?: number;
+} | {
+    type: 'register-start';
+} | {
+    type: 'register-success';
+    user: UserProfile;
+} | {
+    type: 'register-failed';
+    error: string;
+};
+type FaceSmashEventListener = (event: FaceSmashEvent) => void;
+
+declare class FaceSmashClient {
+    readonly config: ResolvedConfig;
+    readonly pb: PocketBase;
+    private listeners;
+    private _modelsLoaded;
+    constructor(config?: FaceSmashConfig);
+    on(listener: FaceSmashEventListener): () => void;
+    private emit;
+    get isReady(): boolean;
+    init(onProgress?: OnProgress): Promise<boolean>;
+    analyzeFace(imageData: string): Promise<FaceAnalysis | null>;
+    login(images: string[]): Promise<LoginResult>;
+    register(name: string, images: string[], email?: string): Promise<RegisterResult>;
+    private ensureReady;
+    private storeLoginScan;
+}
+
+declare function loadModels(config: ResolvedConfig, onProgress?: (progress: number) => void): Promise<boolean>;
+declare function areModelsLoaded(): boolean;
+declare function extractDescriptor(input: string | HTMLVideoElement | HTMLCanvasElement | HTMLImageElement, config: ResolvedConfig): Promise<Float32Array | null>;
+declare function analyzeFace(imageData: string, config: ResolvedConfig): Promise<FaceAnalysis | null>;
+declare function processImages(images: string[], config: ResolvedConfig): Promise<Float32Array | null>;
+declare function normalizeDescriptor(descriptor: Float32Array): Float32Array;
+
+/** Calculate cosine similarity between two face descriptors (1 - euclidean distance) */
+declare function calculateSimilarity(d1: Float32Array, d2: Float32Array): number;
+/** Check if two face descriptors match */
+declare function facesMatch(d1: Float32Array, d2: Float32Array, threshold?: number): boolean;
+/**
+ * Enhanced face matching with adaptive threshold.
+ * Adjusts threshold based on lighting conditions and user confidence boost.
+ */
+declare function enhancedMatch(descriptor1: Float32Array, descriptor2: Float32Array, baseThreshold?: number, confidenceBoost?: number, lightingScore?: number): MatchResult;
+/** Match a face descriptor against multiple stored templates */
+declare function multiTemplateMatch(newDescriptor: Float32Array, templates: {
+    descriptor: Float32Array;
+    quality: number;
+    weight: number;
+}[], baseThreshold: number, lightingScore?: number): MultiTemplateMatchResult;
+/** Calculate a learning weight based on scan quality */
+declare function calculateLearningWeight(qualityScore: number, lightingScore: number, confidence: number): number;
+
+declare function createFaceSmash(config?: FaceSmashConfig): FaceSmashClient;
+
+interface FaceSmashContextValue {
+    client: FaceSmashClient;
+    isReady: boolean;
+    isLoading: boolean;
+    loadProgress: number;
+    error: string | null;
+    retryInit: () => void;
+}
+interface FaceSmashProviderProps {
+    children: ReactNode;
+    /** SDK configuration */
+    config?: FaceSmashConfig;
+    /** Called when models finish loading */
+    onReady?: () => void;
+    /** Called on model loading error */
+    onError?: (error: string) => void;
+    /** Called for any SDK event */
+    onEvent?: (event: FaceSmashEvent) => void;
+}
+declare function FaceSmashProvider({ children, config, onReady, onError, onEvent, }: FaceSmashProviderProps): react_jsx_runtime.JSX.Element;
+declare function useFaceSmash(): FaceSmashContextValue;
+
+interface FaceLoginProps {
+    /** Called with the login result when authentication completes */
+    onResult: (result: LoginResult) => void;
+    /** Number of images to capture for matching (default: 3) */
+    captureCount?: number;
+    /** Delay between captures in ms (default: 500) */
+    captureDelay?: number;
+    /** Auto-start scanning when component mounts (default: true) */
+    autoStart?: boolean;
+    /** Custom className for the container */
+    className?: string;
+    /** Custom overlay content rendered on top of the video */
+    overlay?: React.ReactNode;
+    /** Custom loading content */
+    loadingContent?: React.ReactNode;
+    /** Custom error content */
+    errorContent?: (error: string, retry: () => void) => React.ReactNode;
+}
+/**
+ * Drop-in face login component.
+ * Renders a webcam feed, auto-detects a face, captures images, and authenticates.
+ */
+declare function FaceLogin({ onResult, captureCount, captureDelay, autoStart, className, overlay, loadingContent, errorContent, }: FaceLoginProps): react_jsx_runtime.JSX.Element;
+
+interface FaceRegisterProps {
+    /** User's display name */
+    name: string;
+    /** Optional email */
+    email?: string;
+    /** Called with the registration result */
+    onResult: (result: RegisterResult) => void;
+    /** Number of images to capture (default: 3) */
+    captureCount?: number;
+    /** Delay between captures in ms (default: 500) */
+    captureDelay?: number;
+    /** Auto-start when component mounts (default: true) */
+    autoStart?: boolean;
+    /** Custom className for the container */
+    className?: string;
+    /** Custom overlay */
+    overlay?: React.ReactNode;
+    /** Custom loading content */
+    loadingContent?: React.ReactNode;
+    /** Custom error content */
+    errorContent?: (error: string, retry: () => void) => React.ReactNode;
+}
+/**
+ * Drop-in face registration component.
+ * Renders a webcam feed, captures face images, and registers a new user.
+ */
+declare function FaceRegister({ name, email, onResult, captureCount, captureDelay, autoStart, className, overlay, loadingContent, errorContent, }: FaceRegisterProps): react_jsx_runtime.JSX.Element;
+
+/** Hook for face login flow */
+declare function useFaceLogin(): {
+    login: (images: string[]) => Promise<LoginResult>;
+    isScanning: boolean;
+    result: LoginResult | null;
+    reset: () => void;
+    isReady: boolean;
+};
+/** Hook for face registration flow */
+declare function useFaceRegister(): {
+    register: (name: string, images: string[], email?: string) => Promise<RegisterResult>;
+    isRegistering: boolean;
+    result: RegisterResult | null;
+    reset: () => void;
+    isReady: boolean;
+};
+/** Hook for face analysis (quality scoring, detection) */
+declare function useFaceAnalysis(): {
+    analyze: (imageData: string) => Promise<FaceAnalysis | null>;
+    analysis: FaceAnalysis | null;
+    isAnalyzing: boolean;
+    isReady: boolean;
+};
+
+export { type FaceAnalysis, FaceLogin, type FaceLoginProps, FaceRegister, type FaceRegisterProps, type FaceSizeCheck, FaceSmashClient, type FaceSmashConfig, type FaceSmashEvent, type FaceSmashEventListener, FaceSmashProvider, type FaceSmashProviderProps, type FaceTemplate, type HeadPose, type LightingAnalysis, type LoginResult, type MatchResult, type MultiTemplateMatchResult, type OnProgress, type RegisterResult, type ResolvedConfig, type UserProfile, analyzeFace, areModelsLoaded, calculateLearningWeight, calculateSimilarity, createFaceSmash, enhancedMatch, extractDescriptor, facesMatch, loadModels, multiTemplateMatch, normalizeDescriptor, processImages, useFaceAnalysis, useFaceLogin, useFaceRegister, useFaceSmash };