@moveris/shared 3.8.1 → 3.9.0

package/README.md

@@ -56,6 +56,8 @@ const client = new LivenessClient(config: LivenessClientConfig);
 | `enableRetry`                 | `boolean`                     | `true`                      | Enable automatic retry with exponential backoff                                                  |
 | `customFetch`                 | `typeof fetch`                | `fetch`                     | Custom fetch implementation (for React Native)                                                   |
 | `deviceIntelligenceOverrides` | `DeviceIntelligenceOverrides` | -                           | Static overrides merged into every `device_intelligence` payload (e.g. `{ vpn_detected: true }`) |
+| `consumer`                    | `ConsumerContext`             | -                           | Consumer app context — traces which app and environment submitted each transaction               |
+| `trackClientTime`             | `boolean`                     | `false`                     | When true, fires a fire-and-forget PATCH after each verdict to record end-to-end client duration |
 
 #### Methods
 
@@ -152,6 +154,17 @@ const result = await client.hybrid50(frames, { fps: 30 });
 const result = await client.hybrid150(frames, { fps: 30 });
 ```
 
+##### `postClientTime(sessionId, clientTime)`
+
+Fire-and-forget PATCH to record end-to-end client duration for a completed verification session. No-op when `trackClientTime` is `false`. Swallows all errors silently.
+
+```typescript
+// Called automatically by useLiveness / CognitoCheckWidget after the verdict.
+// Approach B consumers can call it manually after onComplete resolves:
+const elapsed = Math.round(performance.now() - startTime);
+void client.postClientTime(result.sessionId, elapsed);
+```
+
 ##### `updateDeviceIntelligenceOverrides(overrides)`
 
 Merge additional fields into the cached device intelligence payload. Call this after construction to inject data only available at runtime (e.g. camera specs, VPN detection results). Merges shallowly — later calls are merged on top of earlier ones.
@@ -254,6 +267,27 @@ Deprecated models (v1 — sunset 2026-09-01):
 | `'mixed-150'` | 150    | —                |
 | `'mixed-250'` | 250    | —                |
 
+#### ConsumerContext
+
+Consumer app context attached to every verification request for transaction tracing.
+
+```typescript
+interface ConsumerContext {
+  url: string; // The consumer app's URL
+  env: 'development' | 'staging' | 'production'; // Consumer app environment
+}
+```
+
+Pass it at client construction — it is included in every subsequent request automatically:
+
+```typescript
+const client = new LivenessClient({
+  apiKey: 'mv_your_api_key',
+  consumer: { url: 'https://app.example.com', env: 'production' },
+  trackClientTime: true, // optional — fires postClientTime after each verdict
+});
+```
+
 #### FrameSource
 
 Source of the captured frames.
@@ -308,6 +342,7 @@ interface LivenessResult {
   processingMs: number; // Server processing time
   framesProcessed: number; // Number of frames analyzed
   deprecation?: DeprecationInfo; // Present when X-Moveris-Model-Resolved header is returned
+  clientTime?: number; // End-to-end client duration in ms (start() to verdict received)
 }
 ```
 
@@ -669,14 +704,13 @@ const inOval = isFaceInOval(faceBbox, ovalRegion);
 console.log(inOval.isInOval); // true/false
 console.log(inOval.alignmentScore); // 0-1
 
-// Calculate crop region for face (224x224, aligned with cognito-check constants)
+// Calculate crop region for face — frame-relative 20% margin on each side,
+// matches the API server-side crop and the model training pipeline.
 const cropRegion = calculateFaceCropRegion(faceBbox, frameWidth, frameHeight);
-// { x, y, size } — square crop region in pixel coordinates
-
-// Calculate adaptive crop multiplier based on face size
-import { calculateAdaptiveCropMultiplier } from '@moveris/shared';
-const multiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
-// Returns 2.5–4.0x (matched to cognito-check for ~33% face coverage in 224×224 crop)
+// { x, y, width, height } — possibly non-square rectangle in source pixel
+// coordinates. Callers must resize the cropped pixels to 224×224 with
+// bilinear interpolation; non-square crops are squashed (intentional, matches
+// cv2.resize behaviour applied server-side).
 
 // Detect face roll (device tilt) — prefer matrix when available (more accurate under glasses/occlusion)
 if (facialTransformationMatrix) {
@@ -700,17 +734,21 @@ const drResult = analyzeDynamicRange(rgbaPixels);
 // Soft warning — do not use as a hard capture gate
 ```
 
-#### Crop Constants (aligned with cognito-check)
+#### Crop Constants (aligned with the model contract)
+
+These constants control how face crops are generated for the `fast-check-crops` endpoint. They match the algorithm applied server-side in `m-ai-check-api` and during model training:
 
-These constants control how face crops are generated for the `fast-check-crops` endpoint:
+1. Detect the face. Get the bounding box in source pixel coordinates.
+2. Expand the bbox by `FACE_CROP_FRAME_MARGIN × frameWidth/Height` on each side.
+3. Clamp the resulting rectangle to `[0, frameWidth] × [0, frameHeight]`. The crop is **not necessarily square**.
+4. Resize the cropped pixels to exactly `FACE_CROP_OUTPUT_SIZE × FACE_CROP_OUTPUT_SIZE` with bilinear interpolation. Non-square crops are squashed (matches `cv2.resize` server-side).
 
-| Constant                         | Value | Description                                      |
-| -------------------------------- | ----- | ------------------------------------------------ |
-| `IDEAL_CROP_MULTIPLIER`          | 2.0   | Default crop region = 2x face size               |
-| `MIN_CROP_MULTIPLIER`            | 1.8   | Minimum crop (face very close)                   |
-| `MAX_CROP_MULTIPLIER`            | 2.5   | Maximum crop (face very far)                     |
-| `FACE_CENTER_VERTICAL_OFFSET`    | 0.05  | Slight upward shift to include forehead for rPPG |
-| `TARGET_FACE_PERCENTAGE_IN_CROP` | 0.5   | Face should occupy ~50% of 224x224 crop          |
+| Constant                         | Value  | Description                                                           |
+| -------------------------------- | ------ | --------------------------------------------------------------------- |
+| `FACE_CROP_FRAME_MARGIN`         | `0.2`  | Margin around the face bbox, as a fraction of frame W/H, on each side |
+| `FACE_CROP_OUTPUT_SIZE`          | `224`  | Required output size for the cropped face image (px)                  |
+| `MAX_FACE_PERCENTAGE_IN_CROP`    | `0.45` | UX guard — nudge users back when the face dominates the crop          |
+| `TARGET_FACE_PERCENTAGE_IN_CROP` | `0.33` | UX-only target framing; not a model contract                          |
 
 ---
 
@@ -853,6 +891,7 @@ import type {
   Verdict,
   CapturedFrame,
   CropData,
+  ConsumerContext,
   LivenessClientConfig,
   DetectionResult,
   DetectionSummary,

package/dist/index.d.mts

@@ -26,6 +26,10 @@ type DeviceIntelligenceOverrides = {
 };
 
 type Verdict = 'live' | 'fake' | 'inconclusive';
+interface ConsumerContext {
+    url: string;
+    env: 'development' | 'staging' | 'production';
+}
 interface ModelEntry {
     id: string;
     label: string;
@@ -68,6 +72,9 @@ interface FastCheckRequest {
     frame_count?: number;
     warnings?: string[];
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface FastCheckCropsRequest {
     session_id: string;
@@ -76,6 +83,9 @@ interface FastCheckCropsRequest {
     crops: CropData[];
     frame_count?: number;
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface VerifyRequest {
     session_id: string;
@@ -108,6 +118,9 @@ interface FastCheckStreamRequest {
     frame_count?: number;
     warnings?: string[];
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface FastCheckResponse {
     verdict: Verdict | null;
@@ -208,6 +221,7 @@ interface LivenessResult {
     framesProcessed: number;
     warnings?: string[];
     deprecation?: DeprecationInfo;
+    clientTime?: number;
 }
 type LivenessState = 'idle' | 'capturing' | 'uploading' | 'processing' | 'complete' | 'error';
 interface LivenessConfig {
@@ -362,10 +376,7 @@ declare const MIN_FACE_SIDE_MARGIN = 0.05;
 declare const MIN_CAPTURE_ALIGNMENT = 0.6;
 declare const HIGH_ALIGNMENT = 0.85;
 declare const GOOD_ALIGNMENT = 0.5;
-declare const IDEAL_CROP_MULTIPLIER = 3;
-declare const MIN_CROP_MULTIPLIER = 2.5;
-declare const MAX_CROP_MULTIPLIER = 4;
-declare const FACE_CENTER_VERTICAL_OFFSET = 0.05;
+declare const FACE_CROP_FRAME_MARGIN = 0.2;
 declare const MIN_IDEAL_FACE_RATIO = 0.05;
 declare const MAX_IDEAL_FACE_RATIO = 0.2;
 declare const MIN_FACE_RATIO = 0.036;
@@ -392,12 +403,12 @@ declare const OVAL_REGION_MOBILE: OvalRegion;
 declare const DEFAULT_OVAL_REGION: OvalRegion;
 declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
 declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
-declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
 declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
 declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
     x: number;
     y: number;
-    size: number;
+    width: number;
+    height: number;
 };
 declare function checkFrameQuality(options: {
     faceBox?: FaceBoundingBox;
@@ -570,6 +581,8 @@ interface LivenessClientConfig {
     enableRetry?: boolean;
     customFetch?: typeof fetch;
     deviceIntelligenceOverrides?: DeviceIntelligenceOverrides;
+    consumer?: ConsumerContext;
+    trackClientTime?: boolean;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -590,6 +603,8 @@ declare class LivenessClient {
     private readonly timeout;
     private readonly enableRetry;
     private readonly fetchFn;
+    private readonly consumer;
+    private readonly trackClientTime;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -610,6 +625,7 @@ declare class LivenessClient {
     health(): Promise<HealthResponse>;
     getModels(): Promise<ModelEntry[]>;
     queueStats(): Promise<QueueStatsResponse>;
+    postClientTime(sessionId: string, clientTime: number): Promise<void>;
     fastCheck(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
@@ -731,6 +747,7 @@ declare const API_PATHS: {
     readonly hybrid150: "/api/v1/hybrid-150";
     readonly jobResult: "/api/v1/result";
     readonly queueStats: "/api/v1/queue/stats";
+    readonly sessions: "/api/v1/sessions";
 };
 declare const RETRY_CONFIG: {
     readonly maxAttempts: 3;
@@ -945,4 +962,4 @@ declare function collectDeviceIntelligence(opts?: {
     platformVersion?: string;
 }): Promise<DeviceIntelligence | null>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -26,6 +26,10 @@ type DeviceIntelligenceOverrides = {
 };
 
 type Verdict = 'live' | 'fake' | 'inconclusive';
+interface ConsumerContext {
+    url: string;
+    env: 'development' | 'staging' | 'production';
+}
 interface ModelEntry {
     id: string;
     label: string;
@@ -68,6 +72,9 @@ interface FastCheckRequest {
     frame_count?: number;
     warnings?: string[];
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface FastCheckCropsRequest {
     session_id: string;
@@ -76,6 +83,9 @@ interface FastCheckCropsRequest {
     crops: CropData[];
     frame_count?: number;
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface VerifyRequest {
     session_id: string;
@@ -108,6 +118,9 @@ interface FastCheckStreamRequest {
     frame_count?: number;
     warnings?: string[];
     device_intelligence?: DeviceIntelligence;
+    metadata?: {
+        consumer?: ConsumerContext;
+    } | null;
 }
 interface FastCheckResponse {
     verdict: Verdict | null;
@@ -208,6 +221,7 @@ interface LivenessResult {
     framesProcessed: number;
     warnings?: string[];
     deprecation?: DeprecationInfo;
+    clientTime?: number;
 }
 type LivenessState = 'idle' | 'capturing' | 'uploading' | 'processing' | 'complete' | 'error';
 interface LivenessConfig {
@@ -362,10 +376,7 @@ declare const MIN_FACE_SIDE_MARGIN = 0.05;
 declare const MIN_CAPTURE_ALIGNMENT = 0.6;
 declare const HIGH_ALIGNMENT = 0.85;
 declare const GOOD_ALIGNMENT = 0.5;
-declare const IDEAL_CROP_MULTIPLIER = 3;
-declare const MIN_CROP_MULTIPLIER = 2.5;
-declare const MAX_CROP_MULTIPLIER = 4;
-declare const FACE_CENTER_VERTICAL_OFFSET = 0.05;
+declare const FACE_CROP_FRAME_MARGIN = 0.2;
 declare const MIN_IDEAL_FACE_RATIO = 0.05;
 declare const MAX_IDEAL_FACE_RATIO = 0.2;
 declare const MIN_FACE_RATIO = 0.036;
@@ -392,12 +403,12 @@ declare const OVAL_REGION_MOBILE: OvalRegion;
 declare const DEFAULT_OVAL_REGION: OvalRegion;
 declare function isFaceInOval(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number, oval?: OvalRegion, tolerance?: number): FaceInOvalResult;
 declare function calculateFaceAlignment(boundingBox: FaceBoundingBox, frameWidth: number, frameHeight: number): FaceAlignmentResult;
-declare function calculateAdaptiveCropMultiplier(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): number;
 declare function isFaceCropFullyInFrame(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): boolean;
 declare function calculateFaceCropRegion(faceBox: FaceBoundingBox, frameWidth: number, frameHeight: number): {
     x: number;
     y: number;
-    size: number;
+    width: number;
+    height: number;
 };
 declare function checkFrameQuality(options: {
     faceBox?: FaceBoundingBox;
@@ -570,6 +581,8 @@ interface LivenessClientConfig {
     enableRetry?: boolean;
     customFetch?: typeof fetch;
     deviceIntelligenceOverrides?: DeviceIntelligenceOverrides;
+    consumer?: ConsumerContext;
+    trackClientTime?: boolean;
 }
 declare class LivenessApiError extends Error {
     readonly code: string;
@@ -590,6 +603,8 @@ declare class LivenessClient {
     private readonly timeout;
     private readonly enableRetry;
     private readonly fetchFn;
+    private readonly consumer;
+    private readonly trackClientTime;
     private diCollected;
     private diCollecting;
     private diOverrides;
@@ -610,6 +625,7 @@ declare class LivenessClient {
     health(): Promise<HealthResponse>;
     getModels(): Promise<ModelEntry[]>;
     queueStats(): Promise<QueueStatsResponse>;
+    postClientTime(sessionId: string, clientTime: number): Promise<void>;
     fastCheck(frames: CapturedFrame[], options?: {
         sessionId?: string;
         model?: FastCheckModel;
@@ -731,6 +747,7 @@ declare const API_PATHS: {
     readonly hybrid150: "/api/v1/hybrid-150";
     readonly jobResult: "/api/v1/result";
     readonly queueStats: "/api/v1/queue/stats";
+    readonly sessions: "/api/v1/sessions";
 };
 declare const RETRY_CONFIG: {
     readonly maxAttempts: 3;
@@ -945,4 +962,4 @@ declare function collectDeviceIntelligence(opts?: {
     platformVersion?: string;
 }): Promise<DeviceIntelligence | null>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, type CameraCapabilities, type CameraRequirements, type CameraValidationResult, type CaptureQualityState, type CapturedFrame, type ConsumerContext, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_CAMERA_REQUIREMENTS, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DeviceIntelligence, type DeviceIntelligenceCamera, type DeviceIntelligenceGeo, type DeviceIntelligenceOverrides, type DynamicRangeAnalysis, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CROP_FRAME_MARGIN, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceRollResult, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, SHARED_SDK_PLATFORM, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, collectDeviceIntelligence, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -50,7 +50,7 @@ __export(index_exports, {
   ES_LOCALE: () => ES_LOCALE,
   EYE_LANDMARK_INDICES: () => EYE_LANDMARK_INDICES,
   EYE_QUALITY_THRESHOLDS: () => EYE_QUALITY_THRESHOLDS,
-  FACE_CENTER_VERTICAL_OFFSET: () => FACE_CENTER_VERTICAL_OFFSET,
+  FACE_CROP_FRAME_MARGIN: () => FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE: () => FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES: () => FEEDBACK_MESSAGES,
   FRAME_BUFFER_CONFIG: () => FRAME_BUFFER_CONFIG,
@@ -60,20 +60,17 @@ __export(index_exports, {
   GOOD_ALIGNMENT: () => GOOD_ALIGNMENT,
   HIGH_ALIGNMENT: () => HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS: () => HYBRID_MODEL_CONFIGS,
-  IDEAL_CROP_MULTIPLIER: () => IDEAL_CROP_MULTIPLIER,
   LANDMARK_INDEX: () => LANDMARK_INDEX,
   LANDMARK_MAX_BOUND: () => LANDMARK_MAX_BOUND,
   LANDMARK_MIN_BOUND: () => LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD: () => LOW_LIGHT_THRESHOLD,
   LivenessApiError: () => LivenessApiError,
   LivenessClient: () => LivenessClient,
-  MAX_CROP_MULTIPLIER: () => MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP: () => MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO: () => MAX_FACE_RATIO,
   MAX_FACE_ROLL_DEGREES: () => MAX_FACE_ROLL_DEGREES,
   MAX_IDEAL_FACE_RATIO: () => MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT: () => MIN_CAPTURE_ALIGNMENT,
-  MIN_CROP_MULTIPLIER: () => MIN_CROP_MULTIPLIER,
   MIN_FACE_AREA_RATIO: () => MIN_FACE_AREA_RATIO,
   MIN_FACE_BOTTOM_MARGIN: () => MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO: () => MIN_FACE_RATIO,
@@ -95,7 +92,6 @@ __export(index_exports, {
   analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
   analyzeLighting: () => analyzeLighting,
-  calculateAdaptiveCropMultiplier: () => calculateAdaptiveCropMultiplier,
   calculateBrightness: () => calculateBrightness,
   calculateFaceAlignment: () => calculateFaceAlignment,
   calculateFaceCropRegion: () => calculateFaceCropRegion,
@@ -162,7 +158,8 @@ var API_PATHS = {
   hybrid50: "/api/v1/hybrid-50",
   hybrid150: "/api/v1/hybrid-150",
   jobResult: "/api/v1/result",
-  queueStats: "/api/v1/queue/stats"
+  queueStats: "/api/v1/queue/stats",
+  sessions: "/api/v1/sessions"
 };
 var RETRY_CONFIG = {
   maxAttempts: 3,
@@ -242,7 +239,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.8.1";
+var version = "3.9.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -390,6 +387,8 @@ var LivenessClient = class _LivenessClient {
     this.enableRetry = config.enableRetry ?? true;
     this.fetchFn = config.customFetch ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
     this.diOverrides = { ...config.deviceIntelligenceOverrides };
+    this.consumer = config.consumer;
+    this.trackClientTime = config.trackClientTime ?? false;
   }
   /**
    * Merge additional device intelligence overrides into the existing set.
@@ -638,6 +637,25 @@ var LivenessClient = class _LivenessClient {
   async queueStats() {
     return this.request(API_PATHS.queueStats);
   }
+  /**
+   * Post end-to-end client duration for a completed verification session.
+   * Fire-and-forget — swallows all errors, no retry.
+   * No-op when `trackClientTime` is false (default).
+   */
+  async postClientTime(sessionId, clientTime) {
+    if (!this.trackClientTime) return;
+    try {
+      await this.fetchFn(`${this.baseUrl}${API_PATHS.sessions}/${sessionId}/client-time`, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          [AUTH_CONFIG.apiKeyHeader]: this.apiKey
+        },
+        body: JSON.stringify({ client_time: clientTime })
+      });
+    } catch {
+    }
+  }
   // ===========================================================================
   // Fast Check Endpoints
   // ===========================================================================
@@ -658,7 +676,8 @@ var LivenessClient = class _LivenessClient {
       frames: toFrameData(frames),
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     const { data: response, headers } = await this.requestWithRetryRaw(
       API_PATHS.fastCheck,
@@ -695,7 +714,8 @@ var LivenessClient = class _LivenessClient {
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
       ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     const { data: response, headers } = await this.requestWithRetryRaw(
       API_PATHS.fastCheckCrops,
@@ -759,7 +779,8 @@ var LivenessClient = class _LivenessClient {
       frame: frameData,
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -1786,10 +1807,7 @@ var MIN_FACE_SIDE_MARGIN = 0.05;
 var MIN_CAPTURE_ALIGNMENT = 0.6;
 var HIGH_ALIGNMENT = 0.85;
 var GOOD_ALIGNMENT = 0.5;
-var IDEAL_CROP_MULTIPLIER = 3;
-var MIN_CROP_MULTIPLIER = 2.5;
-var MAX_CROP_MULTIPLIER = 4;
-var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+var FACE_CROP_FRAME_MARGIN = 0.2;
 var MIN_IDEAL_FACE_RATIO = 0.05;
 var MAX_IDEAL_FACE_RATIO = 0.2;
 var MIN_FACE_RATIO = 0.036;
@@ -1983,40 +2001,21 @@ function calculateFaceAlignment(boundingBox, frameWidth, frameHeight) {
     tooFar: faceRatio < MIN_FACE_RATIO
   };
 }
-function calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight) {
-  const faceSize = Math.max(faceBox.width, faceBox.height);
-  const idealCropSize = faceSize * IDEAL_CROP_MULTIPLIER;
-  const maxCropSize = Math.min(frameWidth, frameHeight);
-  if (idealCropSize <= maxCropSize) {
-    return IDEAL_CROP_MULTIPLIER;
-  }
-  const adaptiveMultiplier = maxCropSize / faceSize;
-  return Math.max(MIN_CROP_MULTIPLIER, Math.min(MAX_CROP_MULTIPLIER, adaptiveMultiplier));
-}
 function isFaceCropFullyInFrame(faceBox, frameWidth, frameHeight) {
-  const marginMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
-  const marginX = faceBox.width * (marginMultiplier - 1) / 2;
-  const marginY = faceBox.height * (marginMultiplier - 1) / 2;
-  const faceLeft = faceBox.originX - marginX;
-  const faceTop = faceBox.originY - marginY;
-  const faceRight = faceBox.originX + faceBox.width + marginX;
-  const faceBottom = faceBox.originY + faceBox.height + marginY;
+  const faceLeft = faceBox.originX;
+  const faceTop = faceBox.originY;
+  const faceRight = faceBox.originX + faceBox.width;
+  const faceBottom = faceBox.originY + faceBox.height;
   return faceLeft >= 0 && faceTop >= 0 && faceRight <= frameWidth && faceBottom <= frameHeight;
 }
 function calculateFaceCropRegion(faceBox, frameWidth, frameHeight) {
-  const cropMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
-  const expandedWidth = faceBox.width * cropMultiplier;
-  const expandedHeight = faceBox.height * cropMultiplier;
-  const cropSize = Math.max(expandedWidth, expandedHeight);
-  const centerX = faceBox.originX + faceBox.width / 2;
-  const verticalShift = faceBox.height * FACE_CENTER_VERTICAL_OFFSET;
-  const centerY = faceBox.originY + faceBox.height / 2 + verticalShift;
-  let cropX = centerX - cropSize / 2;
-  let cropY = centerY - cropSize / 2;
-  cropX = Math.max(0, Math.min(frameWidth - cropSize, cropX));
-  cropY = Math.max(0, Math.min(frameHeight - cropSize, cropY));
-  const finalSize = Math.min(cropSize, frameWidth - cropX, frameHeight - cropY);
-  return { x: cropX, y: cropY, size: finalSize };
+  const marginX = FACE_CROP_FRAME_MARGIN * frameWidth;
+  const marginY = FACE_CROP_FRAME_MARGIN * frameHeight;
+  const x1 = Math.max(0, faceBox.originX - marginX);
+  const y1 = Math.max(0, faceBox.originY - marginY);
+  const x2 = Math.min(frameWidth, faceBox.originX + faceBox.width + marginX);
+  const y2 = Math.min(frameHeight, faceBox.originY + faceBox.height + marginY);
+  return { x: x1, y: y1, width: x2 - x1, height: y2 - y1 };
 }
 function checkFrameQuality(options) {
   const {
@@ -2380,7 +2379,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   ES_LOCALE,
   EYE_LANDMARK_INDICES,
   EYE_QUALITY_THRESHOLDS,
-  FACE_CENTER_VERTICAL_OFFSET,
+  FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
   FRAME_BUFFER_CONFIG,
@@ -2390,20 +2389,17 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   GOOD_ALIGNMENT,
   HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS,
-  IDEAL_CROP_MULTIPLIER,
   LANDMARK_INDEX,
   LANDMARK_MAX_BOUND,
   LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD,
   LivenessApiError,
   LivenessClient,
-  MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO,
   MAX_FACE_ROLL_DEGREES,
   MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT,
-  MIN_CROP_MULTIPLIER,
   MIN_FACE_AREA_RATIO,
   MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO,
@@ -2425,7 +2421,6 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
-  calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,

package/dist/index.mjs

@@ -16,7 +16,8 @@ var API_PATHS = {
   hybrid50: "/api/v1/hybrid-50",
   hybrid150: "/api/v1/hybrid-150",
   jobResult: "/api/v1/result",
-  queueStats: "/api/v1/queue/stats"
+  queueStats: "/api/v1/queue/stats",
+  sessions: "/api/v1/sessions"
 };
 var RETRY_CONFIG = {
   maxAttempts: 3,
@@ -96,7 +97,7 @@ async function sleep(ms) {
 }
 
 // package.json
-var version = "3.8.1";
+var version = "3.9.0";
 
 // src/utils/deviceIntelligence.ts
 var IPINFO_URL = "https://ipinfo.io/json";
@@ -244,6 +245,8 @@ var LivenessClient = class _LivenessClient {
     this.enableRetry = config.enableRetry ?? true;
     this.fetchFn = config.customFetch ?? (typeof window !== "undefined" ? fetch.bind(window) : fetch);
     this.diOverrides = { ...config.deviceIntelligenceOverrides };
+    this.consumer = config.consumer;
+    this.trackClientTime = config.trackClientTime ?? false;
   }
   /**
    * Merge additional device intelligence overrides into the existing set.
@@ -492,6 +495,25 @@ var LivenessClient = class _LivenessClient {
   async queueStats() {
     return this.request(API_PATHS.queueStats);
   }
+  /**
+   * Post end-to-end client duration for a completed verification session.
+   * Fire-and-forget — swallows all errors, no retry.
+   * No-op when `trackClientTime` is false (default).
+   */
+  async postClientTime(sessionId, clientTime) {
+    if (!this.trackClientTime) return;
+    try {
+      await this.fetchFn(`${this.baseUrl}${API_PATHS.sessions}/${sessionId}/client-time`, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          [AUTH_CONFIG.apiKeyHeader]: this.apiKey
+        },
+        body: JSON.stringify({ client_time: clientTime })
+      });
+    } catch {
+    }
+  }
   // ===========================================================================
   // Fast Check Endpoints
   // ===========================================================================
@@ -512,7 +534,8 @@ var LivenessClient = class _LivenessClient {
       frames: toFrameData(frames),
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     const { data: response, headers } = await this.requestWithRetryRaw(
       API_PATHS.fastCheck,
@@ -549,7 +572,8 @@ var LivenessClient = class _LivenessClient {
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
       ...options.bgSegmentation !== void 0 ? { bg_segmentation: options.bgSegmentation } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     const { data: response, headers } = await this.requestWithRetryRaw(
       API_PATHS.fastCheckCrops,
@@ -613,7 +637,8 @@ var LivenessClient = class _LivenessClient {
       frame: frameData,
       ...options.frameCount != null ? { frame_count: options.frameCount } : {},
       ...options.warnings?.length ? { warnings: options.warnings } : {},
-      ...di ? { device_intelligence: di } : {}
+      ...di ? { device_intelligence: di } : {},
+      ...this.consumer ? { metadata: { consumer: this.consumer } } : {}
     };
     return this.requestWithRetry(API_PATHS.fastCheckStream, {
       method: "POST",
@@ -1640,10 +1665,7 @@ var MIN_FACE_SIDE_MARGIN = 0.05;
 var MIN_CAPTURE_ALIGNMENT = 0.6;
 var HIGH_ALIGNMENT = 0.85;
 var GOOD_ALIGNMENT = 0.5;
-var IDEAL_CROP_MULTIPLIER = 3;
-var MIN_CROP_MULTIPLIER = 2.5;
-var MAX_CROP_MULTIPLIER = 4;
-var FACE_CENTER_VERTICAL_OFFSET = 0.05;
+var FACE_CROP_FRAME_MARGIN = 0.2;
 var MIN_IDEAL_FACE_RATIO = 0.05;
 var MAX_IDEAL_FACE_RATIO = 0.2;
 var MIN_FACE_RATIO = 0.036;
@@ -1837,40 +1859,21 @@ function calculateFaceAlignment(boundingBox, frameWidth, frameHeight) {
     tooFar: faceRatio < MIN_FACE_RATIO
   };
 }
-function calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight) {
-  const faceSize = Math.max(faceBox.width, faceBox.height);
-  const idealCropSize = faceSize * IDEAL_CROP_MULTIPLIER;
-  const maxCropSize = Math.min(frameWidth, frameHeight);
-  if (idealCropSize <= maxCropSize) {
-    return IDEAL_CROP_MULTIPLIER;
-  }
-  const adaptiveMultiplier = maxCropSize / faceSize;
-  return Math.max(MIN_CROP_MULTIPLIER, Math.min(MAX_CROP_MULTIPLIER, adaptiveMultiplier));
-}
 function isFaceCropFullyInFrame(faceBox, frameWidth, frameHeight) {
-  const marginMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
-  const marginX = faceBox.width * (marginMultiplier - 1) / 2;
-  const marginY = faceBox.height * (marginMultiplier - 1) / 2;
-  const faceLeft = faceBox.originX - marginX;
-  const faceTop = faceBox.originY - marginY;
-  const faceRight = faceBox.originX + faceBox.width + marginX;
-  const faceBottom = faceBox.originY + faceBox.height + marginY;
+  const faceLeft = faceBox.originX;
+  const faceTop = faceBox.originY;
+  const faceRight = faceBox.originX + faceBox.width;
+  const faceBottom = faceBox.originY + faceBox.height;
   return faceLeft >= 0 && faceTop >= 0 && faceRight <= frameWidth && faceBottom <= frameHeight;
 }
 function calculateFaceCropRegion(faceBox, frameWidth, frameHeight) {
-  const cropMultiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
-  const expandedWidth = faceBox.width * cropMultiplier;
-  const expandedHeight = faceBox.height * cropMultiplier;
-  const cropSize = Math.max(expandedWidth, expandedHeight);
-  const centerX = faceBox.originX + faceBox.width / 2;
-  const verticalShift = faceBox.height * FACE_CENTER_VERTICAL_OFFSET;
-  const centerY = faceBox.originY + faceBox.height / 2 + verticalShift;
-  let cropX = centerX - cropSize / 2;
-  let cropY = centerY - cropSize / 2;
-  cropX = Math.max(0, Math.min(frameWidth - cropSize, cropX));
-  cropY = Math.max(0, Math.min(frameHeight - cropSize, cropY));
-  const finalSize = Math.min(cropSize, frameWidth - cropX, frameHeight - cropY);
-  return { x: cropX, y: cropY, size: finalSize };
+  const marginX = FACE_CROP_FRAME_MARGIN * frameWidth;
+  const marginY = FACE_CROP_FRAME_MARGIN * frameHeight;
+  const x1 = Math.max(0, faceBox.originX - marginX);
+  const y1 = Math.max(0, faceBox.originY - marginY);
+  const x2 = Math.min(frameWidth, faceBox.originX + faceBox.width + marginX);
+  const y2 = Math.min(frameHeight, faceBox.originY + faceBox.height + marginY);
+  return { x: x1, y: y1, width: x2 - x1, height: y2 - y1 };
 }
 function checkFrameQuality(options) {
   const {
@@ -2233,7 +2236,7 @@ export {
   ES_LOCALE,
   EYE_LANDMARK_INDICES,
   EYE_QUALITY_THRESHOLDS,
-  FACE_CENTER_VERTICAL_OFFSET,
+  FACE_CROP_FRAME_MARGIN,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
   FRAME_BUFFER_CONFIG,
@@ -2243,20 +2246,17 @@ export {
   GOOD_ALIGNMENT,
   HIGH_ALIGNMENT,
   HYBRID_MODEL_CONFIGS,
-  IDEAL_CROP_MULTIPLIER,
   LANDMARK_INDEX,
   LANDMARK_MAX_BOUND,
   LANDMARK_MIN_BOUND,
   LOW_LIGHT_THRESHOLD,
   LivenessApiError,
   LivenessClient,
-  MAX_CROP_MULTIPLIER,
   MAX_FACE_PERCENTAGE_IN_CROP,
   MAX_FACE_RATIO,
   MAX_FACE_ROLL_DEGREES,
   MAX_IDEAL_FACE_RATIO,
   MIN_CAPTURE_ALIGNMENT,
-  MIN_CROP_MULTIPLIER,
   MIN_FACE_AREA_RATIO,
   MIN_FACE_BOTTOM_MARGIN,
   MIN_FACE_RATIO,
@@ -2278,7 +2278,6 @@ export {
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
-  calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "description": "Core business logic for Moveris Live SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",