@moveris/shared 2.1.0 → 2.1.1

package/README.md

@@ -80,11 +80,33 @@ const result = await client.fastCheck(frames, {
 
 ##### `fastCheckCrops(crops, options)`
 
-Perform fast liveness check with pre-cropped 224x224 face images. Use this when you handle face detection client-side.
+Perform fast liveness check with pre-cropped 224x224 face images. Use this when you handle face detection client-side. Expects `CropData[]` (no timestamps — only `index` and `pixels`).
 
 ```typescript
+import type { CropData } from '@moveris/shared';
+
+const crops: CropData[] = capturedFrames.map((f) => ({
+  index: f.index,
+  pixels: f.pixels, // base64 224x224 PNG
+}));
+
 const result = await client.fastCheckCrops(crops, {
-  model: '50',
+  model: '10',
+  source: 'live',
+});
+```
+
+##### `streamFrame(frame, options)`
+
+Send a single frame to the streaming endpoint. Returns the API response which may include a partial or final result. Used internally by `useLiveness` for sequential streaming.
+
+```typescript
+const response = await client.streamFrame(frame, {
+  sessionId: 'uuid',
+  model: '10',
+  source: 'live',
+  frameIndex: 0,
+  totalFrames: 10,
 });
 ```
 
@@ -160,14 +182,23 @@ const job = await client.waitForJobResult('job-uuid', 30);
 Model selection for liveness detection speed/accuracy trade-off.
 
 ```typescript
-type FastCheckModel = '10' | '50' | '250';
+type FastCheckModel =
+  | '10'
+  | '50'
+  | '250' // Standard models
+  | 'hybrid-v2-10'
+  | 'hybrid-v2-50' // Hybrid V2 (physiological features)
+  | 'mixed-10'; // Mixed (visual + physiological scoring)
 ```
 
-| Value   | Frames | Description                       |
-| ------- | ------ | --------------------------------- |
-| `'10'`  | 10     | Fast verification, lowest latency |
-| `'50'`  | 50     | Balanced speed and accuracy       |
-| `'250'` | 250    | Highest accuracy, slower          |
+| Value            | Frames | Category  | Description                               |
+| ---------------- | ------ | --------- | ----------------------------------------- |
+| `'10'`           | 10     | Standard  | Fast verification, lowest latency         |
+| `'50'`           | 50     | Standard  | Balanced speed and accuracy               |
+| `'250'`          | 250    | Standard  | Highest accuracy, slower                  |
+| `'hybrid-v2-10'` | 10     | Hybrid V2 | Visual + physiological feature extraction |
+| `'hybrid-v2-50'` | 50     | Hybrid V2 | Higher accuracy physiological features    |
+| `'mixed-10'`     | 10     | Mixed     | Combined visual + physiological scoring   |
 
 #### FrameSource
 
@@ -236,6 +267,17 @@ interface CapturedFrame {
 }
 ```
 
+#### CropData
+
+Pre-cropped face image for the `fast-check-crops` endpoint. Omits `timestampMs` since timing is not needed for cropped submissions.
+
+```typescript
+interface CropData {
+  index: number; // Frame sequence number (0-based)
+  pixels: string; // Base64-encoded 224x224 PNG image
+}
+```
+
 ---
 
 ### Utilities
@@ -424,10 +466,28 @@ const inOval = isFaceInOval(faceBbox, ovalRegion);
 console.log(inOval.isInOval); // true/false
 console.log(inOval.alignmentScore); // 0-1
 
-// Calculate crop region for face
+// Calculate crop region for face (224x224, aligned with cognito-check constants)
 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(faceSize, videoSize);
+// Returns 1.8–2.5x (matched to cognito-check for ~50% face coverage)
 ```
 
+#### Crop Constants (aligned with cognito-check)
+
+These constants control how face crops are generated for the `fast-check-crops` endpoint:
+
+| 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          |
+
 ---
 
 ## Configuration Constants
@@ -456,7 +516,14 @@ import type {
   FrameSource,
   Verdict,
   CapturedFrame,
+  CropData,
   LivenessClientConfig,
+  DetectionResult,
+  DetectionSummary,
+  FaceBoundingBox,
+  HeadPose,
+  FaceLandmarkPoint,
+  LandmarkValidationResult,
 } from '@moveris/shared';
 ```
 

package/package.json

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