face-validator-sdk 1.2.0 → 1.3.0

package/dist/types/core/types.d.ts

@@ -0,0 +1,91 @@
+import type { NormalizedLandmark } from '@mediapipe/tasks-vision';
+export declare enum ValidationStatus {
+    INITIALIZING = "INITIALIZING",
+    NO_FACE_DETECTED = "NO_FACE_DETECTED",
+    FACE_DETECTED = "FACE_DETECTED",
+    TOO_CLOSE = "TOO_CLOSE",
+    TOO_FAR = "TOO_FAR",
+    OFF_CENTER = "OFF_CENTER",
+    FACE_OBSTRUCTED = "FACE_OBSTRUCTED",
+    HEAD_NOT_STRAIGHT = "HEAD_NOT_STRAIGHT",
+    MULTIPLE_FACES = "MULTIPLE_FACES",
+    POOR_ILLUMINATION = "POOR_ILLUMINATION",
+    NOT_NEUTRAL_EXPRESSION = "NOT_NEUTRAL_EXPRESSION",
+    DARK_GLASSES = "DARK_GLASSES",
+    STAY_STILL = "STAY_STILL",
+    CAPTURING = "CAPTURING",
+    SUCCESS = "SUCCESS",
+    ERROR = "ERROR"
+}
+export type SupportedLocale = 'pt-BR' | 'en' | 'es';
+export interface FaceValidatorOptions {
+    /** Optional path to MediaPipe models WASM files. Default: auto-detected from CDN */
+    modelPath?: string;
+    /** Video element for the camera stream. */
+    videoElement: HTMLVideoElement;
+    /** Optional canvas for visual feedback (e.g. face outline). */
+    overlayCanvasElement?: HTMLCanvasElement | null;
+    /** Optional video width. Default: 640 */
+    videoWidth?: number;
+    /** Optional video height. Default: 480 */
+    videoHeight?: number;
+    /** UI language. Default: 'en' */
+    locale?: SupportedLocale;
+    /** Optional override for specific status messages. */
+    customMessages?: Partial<Record<ValidationStatus, string>>;
+    /** Callback on each validation status update. */
+    onStatusUpdate: (status: ValidationStatus, message: string) => void;
+    /** Callback when selfie is successfully captured (receives Blob). */
+    onCaptureSuccess: (imageBlob: Blob) => void;
+    /** Callback on error. */
+    onError: (errorType: ValidationStatus, error: Error) => void;
+    /** Optional min detection confidence (0–1). Default: 0.5 */
+    minDetectionConfidence?: number;
+    /** Optional min brightness (0–255). Default: 70 */
+    minIlluminationThreshold?: number;
+    /** Optional min face size factor. Default: 0.25 */
+    minFaceSizeFactor?: number;
+    /** Optional max face size factor. Default: 0.65 */
+    maxFaceSizeFactor?: number;
+    /** Optional stable time before capture (ms). Default: 1000 */
+    stabilizationTimeThreshold?: number;
+    /** Optional movement tolerance (px). Default: 5 */
+    stabilityMovementThreshold?: number;
+    /** Min face visibility score to accept (below = FACE_OBSTRUCTED). Default: 0.5 */
+    minFaceVisibilityScore?: number;
+    /** Max head tilt in degrees (roll and yaw only). Default: 28 */
+    maxHeadTiltDegrees?: number;
+    /** Max distance from hand to face (normalized, 0-1). Default: 0.15 */
+    maxHandFaceDistance?: number;
+    /** Optional debug mode. Default: false */
+    debugMode?: boolean;
+}
+/**
+ * Bounding box structure compatible with MediaPipe (normalized 0-1 coords)
+ */
+export interface BoundingBox {
+    xMin: number;
+    yMin: number;
+    width: number;
+    height: number;
+}
+/**
+ * Detected face data from MediaPipe FaceLandmarker
+ */
+export interface DetectedFaceData {
+    /** Bounding box (normalized coordinates 0-1) */
+    boundingBox: BoundingBox;
+    /** 478 face landmarks (normalized coordinates) */
+    landmarks: NormalizedLandmark[];
+    /** Detection timestamp */
+    timestamp: number;
+}
+/**
+ * Detected hand data from MediaPipe HandLandmarker
+ */
+export interface DetectedHandData {
+    /** 21 hand landmarks (normalized coordinates) */
+    landmarks: NormalizedLandmark[];
+    /** Hand classification (Left/Right) */
+    handedness: string;
+}

package/dist/types/core/utils.d.ts

@@ -0,0 +1,57 @@
+import type { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { DetectedFaceData, DetectedHandData, ValidationStatus, BoundingBox } from './types';
+/**
+ * Calcula o brilho médio de uma região da imagem (0-255).
+ */
+export declare function calculateAverageBrightness(imageData: ImageData): number;
+/**
+ * Verifica se a face está na distância adequada (baseado no tamanho do bounding box).
+ */
+export declare function checkFaceDistance(boundingBox: BoundingBox, minFaceSizeFactor?: number, maxFaceSizeFactor?: number): 'OK' | 'TOO_FAR' | 'TOO_CLOSE';
+/**
+ * Verifica se um ponto (normalizado 0-1) está dentro do oval de enquadramento.
+ */
+export declare function isPointInsideOval(pointX: number, pointY: number, frameWidth: number, frameHeight: number): boolean;
+/**
+ * Verifica se o bounding box da face cabe dentro do oval de enquadramento.
+ * Versão simplificada: verifica apenas o centro e limites principais sem margem excessiva.
+ */
+export declare function isFaceBoundingBoxInsideOval(boundingBox: BoundingBox, frameWidth: number, frameHeight: number): boolean;
+/**
+ * Verifica se a cabeça está reta (sem inclinação lateral, horizontal ou vertical).
+ * MediaPipe: usa landmarks dos olhos, nariz e boca.
+ */
+export declare function isHeadStraight(landmarks: NormalizedLandmark[], maxTiltDegrees?: number): boolean;
+/**
+ * Verifica se a geometria do rosto é plausível (boca visível, não obstruída por mão).
+ * MediaPipe: analisa distância nariz-boca e extensão vertical da boca.
+ */
+export declare function isFaceGeometryPlausible(landmarks: NormalizedLandmark[], boundingBox: BoundingBox): boolean;
+/**
+ * Detecta se a pessoa está usando óculos escuros através da análise de luminosidade dos olhos.
+ * Óculos de grau geralmente não bloqueiam completamente a luz, permitindo ver os olhos.
+ */
+export declare function hasDarkGlasses(video: HTMLVideoElement, landmarks: NormalizedLandmark[]): boolean;
+/**
+ * Verifica se a expressão facial é neutra (sem sorriso, boca fechada, olhos abertos).
+ * Rejeita: sorriso, boca aberta, olhos fechados.
+ */
+export declare function isNeutralExpression(landmarks: NormalizedLandmark[]): boolean;
+/**
+ * Verifica yaw (inclinação lateral) usando visibilidade das orelhas.
+ * Quando o rosto está virado para o lado, uma orelha fica mais visível que a outra.
+ */
+export declare function isYawAcceptable(landmarks: NormalizedLandmark[]): boolean;
+/**
+ * Verifica se a face está estável (sem movimento significativo entre frames).
+ */
+export declare function isFaceStable(currentFace: DetectedFaceData | null, previousFace: DetectedFaceData | null, movementThreshold?: number, frameWidth?: number, frameHeight?: number): boolean;
+/**
+ * Calcula distância entre um ponto da mão e o centro do rosto (normalizado).
+ * Retorna true se a mão estiver próxima ao rosto (indicando possível obstrução).
+ */
+export declare function isHandNearFace(handData: DetectedHandData, faceBoundingBox: BoundingBox, maxDistance?: number): boolean;
+/**
+ * Desenha overlay de feedback visual (oval, status, debug info).
+ */
+export declare function drawOverlay(canvas: HTMLCanvasElement, debugMode: boolean, status: ValidationStatus, faceData?: DetectedFaceData, handData?: DetectedHandData[]): void;

package/dist/types/core.d.ts

@@ -0,0 +1,7 @@
+import { FaceValidator } from './FaceValidator';
+import { ValidationStatus, type FaceValidatorOptions, type DetectedFaceData, type DetectedHandData, type SupportedLocale, type BoundingBox } from './types';
+import { getValidationMessages, getMessage, getLoadingModelsMessage } from './i18n';
+export { FaceValidator };
+export { ValidationStatus, FaceValidatorOptions, DetectedFaceData, DetectedHandData, BoundingBox, SupportedLocale, };
+export { getValidationMessages, getMessage, getLoadingModelsMessage };
+export default FaceValidator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "face-validator-sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Real-time selfie validation SDK with face detection, i18n (pt-BR, en, es). Built on MediaPipe.",
   "main": "dist/face-validator-sdk.cjs.js",
   "module": "dist/face-validator-sdk.esm.js",
@@ -19,13 +19,25 @@
       "browser": "./dist/face-validator-sdk.umd.js",
       "default": "./dist/face-validator-sdk.cjs.js"
     },
+    "./core": {
+      "import": {
+        "types": "./dist/types/core/core.d.ts",
+        "default": "./dist/face-validator-sdk-core.esm.js"
+      },
+      "require": {
+        "types": "./dist/types/core/core.d.ts",
+        "default": "./dist/face-validator-sdk-core.cjs.js"
+      },
+      "browser": "./dist/face-validator-sdk-core.umd.js",
+      "default": "./dist/face-validator-sdk-core.cjs.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
     "start": "webpack serve --config webpack.demo.js --mode development",
     "demo": "webpack serve --config webpack.demo.js --mode development",
     "dev": "webpack serve --config webpack.demo.js --mode development",
-    "build": "rimraf dist && webpack --mode production && tsc --emitDeclarationOnly --outDir dist/types",
+    "build": "rimraf dist && webpack --mode production && tsc --emitDeclarationOnly --outDir dist/types && tsc --project tsconfig.core.json --emitDeclarationOnly",
     "build:demo": "rimraf demo/dist && webpack --config webpack.demo-prod.js --mode production && cp demo/public/index.html demo/dist/index.html",
     "build:watch": "webpack --watch --mode development",
     "lint": "eslint . --ext .ts --report-unused-disable-directives --max-warnings 0",
@@ -48,6 +60,8 @@
   ],
   "files": [
     "dist",
+    "core.js",
+    "core.d.ts",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
@@ -59,6 +73,14 @@
     "react": ">=17.0.0",
     "react-dom": ">=17.0.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/jest": "^29.5.12",
     "@typescript-eslint/eslint-plugin": "^7.10.0",