@moveris/shared 1.0.0 → 1.0.1

package/README.md

@@ -1,25 +1,467 @@
 # @moveris/shared
 
-Core business logic for Moveris Live SDK. This package contains:
-
-- WebSocket client with reconnection logic
-- Frame buffer management
-- Authentication manager
-- Type definitions
-- Utility functions
+Core business logic for Moveris Live SDK. This package provides the HTTP client, types, utilities, and frame management for liveness detection.
 
 ## Installation
 
 ```bash
 pnpm add @moveris/shared
+# or
+npm install @moveris/shared
+# or
+yarn add @moveris/shared
+```
+
+## Quick Start
+
+```typescript
+import { LivenessClient, generateSessionId } from '@moveris/shared';
+
+// Create the client
+const client = new LivenessClient({
+  apiKey: 'mv_your_api_key',
+  baseUrl: 'https://api.moveris.io', // optional, uses default
+});
+
+// Perform a fast liveness check
+const result = await client.fastCheck(frames, {
+  model: '10',
+  source: 'live',
+});
+
+console.log(result.verdict); // 'live' or 'fake'
+console.log(result.confidence); // 0-1
+console.log(result.score); // 0-100
+```
+
+## API Reference
+
+### LivenessClient
+
+The main client for interacting with the Moveris Liveness API.
+
+#### Constructor
+
+```typescript
+const client = new LivenessClient(config: LivenessClientConfig);
+```
+
+| Option        | Type           | Default                    | Description                                     |
+| ------------- | -------------- | -------------------------- | ----------------------------------------------- |
+| `apiKey`      | `string`       | **required**               | Your Moveris API key                            |
+| `baseUrl`     | `string`       | `'https://api.moveris.io'` | API base URL                                    |
+| `timeout`     | `number`       | `30000`                    | Request timeout in milliseconds                 |
+| `enableRetry` | `boolean`      | `true`                     | Enable automatic retry with exponential backoff |
+| `customFetch` | `typeof fetch` | `fetch`                    | Custom fetch implementation (for React Native)  |
+
+#### Methods
+
+##### `fastCheck(frames, options)`
+
+Perform fast liveness check with server-side face detection. Ideal for quick verification with 10-250 frames.
+
+```typescript
+const result = await client.fastCheck(frames, {
+  sessionId: 'optional-uuid',
+  model: '10', // '10' | '50' | '250'
+  source: 'live', // 'live' | 'media'
+});
+```
+
+**Parameters:**
+
+| Option      | Type             | Default        | Description                                                             |
+| ----------- | ---------------- | -------------- | ----------------------------------------------------------------------- |
+| `sessionId` | `string`         | auto-generated | Unique session identifier (UUID)                                        |
+| `model`     | `FastCheckModel` | `'10'`         | Model to use: `'10'` (fast), `'50'` (balanced), `'250'` (high-accuracy) |
+| `source`    | `FrameSource`    | `'live'`       | Frame source: `'live'` (camera) or `'media'` (recorded video)           |
+
+**Returns:** `Promise<LivenessResult>`
+
+##### `fastCheckCrops(crops, options)`
+
+Perform fast liveness check with pre-cropped 224x224 face images. Use this when you handle face detection client-side.
+
+```typescript
+const result = await client.fastCheckCrops(crops, {
+  model: '50',
+});
+```
+
+##### `verify(frames, options)`
+
+Verify liveness using spatial feature-based detection. Requires minimum 50 frames.
+
+```typescript
+const result = await client.verify(frames, {
+  fps: 30,
+  frameWidth: 640,
+  frameHeight: 480,
+});
+```
+
+##### `hybridCheck(frames, options)`
+
+Perform hybrid liveness check combining CNN with physiological features. Requires minimum 50 frames.
+
+```typescript
+const result = await client.hybridCheck(frames, { fps: 30 });
+```
+
+##### `hybrid50(frames, options)`
+
+50-frame hybrid model with 93.8% balanced accuracy.
+
+```typescript
+const result = await client.hybrid50(frames, { fps: 30 });
+```
+
+##### `hybrid150(frames, options)`
+
+150-frame hybrid model with 96.2% balanced accuracy. Best for high-security scenarios.
+
+```typescript
+const result = await client.hybrid150(frames, { fps: 30 });
+```
+
+##### `health()`
+
+Check API health status.
+
+```typescript
+const health = await client.health();
+console.log(health.status); // 'ok'
+console.log(health.models_loaded); // ['10', '50', '250']
+```
+
+##### `getJobResult(jobId)`
+
+Get job status for async processing.
+
+```typescript
+const job = await client.getJobResult('job-uuid');
+console.log(job.status); // 'queued' | 'processing' | 'complete' | 'failed'
+```
+
+##### `waitForJobResult(jobId, timeout)`
+
+Long-poll for job completion (max 120 seconds).
+
+```typescript
+const job = await client.waitForJobResult('job-uuid', 30);
+```
+
+---
+
+### Types
+
+#### FastCheckModel
+
+Model selection for liveness detection speed/accuracy trade-off.
+
+```typescript
+type FastCheckModel = '10' | '50' | '250';
+```
+
+| Value   | Frames | Description                       |
+| ------- | ------ | --------------------------------- |
+| `'10'`  | 10     | Fast verification, lowest latency |
+| `'50'`  | 50     | Balanced speed and accuracy       |
+| `'250'` | 250    | Highest accuracy, slower          |
+
+#### FrameSource
+
+Source of the captured frames.
+
+```typescript
+type FrameSource = 'media' | 'live';
+```
+
+| Value     | Description             |
+| --------- | ----------------------- |
+| `'live'`  | Real-time camera feed   |
+| `'media'` | Pre-recorded video file |
+
+#### Verdict
+
+Liveness determination result.
+
+```typescript
+type Verdict = 'live' | 'fake';
+```
+
+| Value    | Description                                          |
+| -------- | ---------------------------------------------------- |
+| `'live'` | Real person detected                                 |
+| `'fake'` | Spoofing attempt detected (photo, video, mask, etc.) |
+
+#### LivenessState
+
+State machine for liveness detection flow.
+
+```typescript
+type LivenessState =
+  | 'idle' // Ready to start
+  | 'capturing' // Capturing frames from camera
+  | 'uploading' // Uploading frames to API
+  | 'processing' // API is processing frames
+  | 'complete' // Verification complete
+  | 'error'; // Error occurred
+```
+
+#### LivenessResult
+
+Result returned from liveness verification.
+
+```typescript
+interface LivenessResult {
+  verdict: Verdict; // 'live' or 'fake'
+  confidence: number; // Confidence score (0-1)
+  score: number; // Liveness score (0-100)
+  sessionId: string; // Session identifier
+  processingMs: number; // Server processing time
+  framesProcessed: number; // Number of frames analyzed
+}
+```
+
+#### CapturedFrame
+
+Individual frame captured from camera.
+
+```typescript
+interface CapturedFrame {
+  index: number; // Frame sequence number (0-based)
+  timestampMs: number; // Timestamp from capture start
+  pixels: string; // Base64-encoded image data
+}
+```
+
+---
+
+### Utilities
+
+#### `generateSessionId()`
+
+Generate a UUID v4 for session identification.
+
+```typescript
+import { generateSessionId } from '@moveris/shared';
+
+const sessionId = generateSessionId();
+// e.g., 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+```
+
+#### `toFrameData(frames)`
+
+Convert CapturedFrame array to API format.
+
+```typescript
+import { toFrameData } from '@moveris/shared';
+
+const apiFrames = toFrameData(capturedFrames);
 ```
 
-## Usage
+#### `toHybridFrameData(frames)`
+
+Convert frames to hybrid endpoint format.
 
 ```typescript
-import { WebSocketClient, FrameBuffer, AuthManager } from '@moveris/shared';
+import { toHybridFrameData } from '@moveris/shared';
+
+const hybridFrames = toHybridFrameData(capturedFrames);
 ```
 
-## API
+---
+
+### Frame Buffer Management
+
+#### FrameBuffer
+
+Manages a sliding window buffer of frames with automatic cleanup.
+
+```typescript
+import { FrameBuffer } from '@moveris/shared';
+
+const buffer = new FrameBuffer({
+  maxSize: 10, // Maximum frames to keep
+  maxMemoryBytes: 4 * 1024 * 1024, // 4MB limit
+});
+
+// Add frames
+buffer.add(frame);
+
+// Get all frames
+const frames = buffer.getAll();
+
+// Acknowledge processed frames
+buffer.acknowledge(5); // Remove frames up to index 5
+
+// Clear buffer
+buffer.clear();
+```
+
+#### FrameQueue
+
+FIFO queue for frame processing.
+
+```typescript
+import { FrameQueue } from '@moveris/shared';
+
+const queue = new FrameQueue({ maxSize: 50 });
+
+queue.enqueue(frame);
+const frame = queue.dequeue();
+const peeked = queue.peek();
+```
+
+---
+
+### Error Handling
+
+#### LivenessApiError
+
+Custom error class for API errors.
+
+```typescript
+import { LivenessApiError } from '@moveris/shared';
+
+try {
+  await client.fastCheck(frames);
+} catch (error) {
+  if (error instanceof LivenessApiError) {
+    console.log(error.code); // 'insufficient_frames'
+    console.log(error.message); // 'Not enough frames provided'
+    console.log(error.statusCode); // 400
+    console.log(error.required); // 10
+    console.log(error.received); // 5
+  }
+}
+```
+
+**Error Codes:**
+
+| Code                  | Description                |
+| --------------------- | -------------------------- |
+| `insufficient_frames` | Not enough frames provided |
+| `invalid_model`       | Invalid model specified    |
+| `invalid_key`         | Invalid API key            |
+| `missing_field`       | Required field missing     |
+| `timeout`             | Request timeout            |
+| `network_error`       | Network connectivity issue |
+
+---
+
+### Feedback Messages
+
+Localized user feedback for liveness detection UI.
+
+```typescript
+import { getFeedbackMessage, getStatusMessage, DEFAULT_LOCALE, ES_LOCALE } from '@moveris/shared';
+
+// Get localized feedback
+const message = getFeedbackMessage('face_not_centered', ES_LOCALE);
+// "Centra tu rostro en el óvalo"
+
+// Get status message
+const status = getStatusMessage('capturing', DEFAULT_LOCALE);
+// "Hold still..."
+```
+
+#### Feedback Keys
+
+| Key                 | English                        | Description                  |
+| ------------------- | ------------------------------ | ---------------------------- |
+| `no_face`           | "No face detected"             | Face detection failed        |
+| `face_not_centered` | "Center your face in the oval" | Face outside guide           |
+| `too_close`         | "Move back a little"           | Face too close to camera     |
+| `too_far`           | "Move closer"                  | Face too far from camera     |
+| `poor_lighting`     | "Improve lighting"             | Insufficient light           |
+| `hold_still`        | "Hold still"                   | Movement detected            |
+| `capturing`         | "Capturing..."                 | Frame capture in progress    |
+| `processing`        | "Processing..."                | API verification in progress |
+| `success`           | "Verification complete"        | Successful completion        |
+| `failed`            | "Verification failed"          | Failed verification          |
+
+---
+
+### Oval Guide States
+
+Visual feedback states for the face positioning guide.
+
+```typescript
+import { getOvalGuideState, OVAL_GUIDE_COLORS } from '@moveris/shared';
+
+const state = getOvalGuideState(alignmentScore);
+// Returns: 'no_face' | 'poor' | 'good' | 'perfect'
+
+const color = OVAL_GUIDE_COLORS[state];
+// 'red' | 'orange' | 'yellow' | 'green'
+```
+
+| State     | Color  | Alignment Score  |
+| --------- | ------ | ---------------- |
+| `no_face` | Red    | No face detected |
+| `poor`    | Orange | < 0.5            |
+| `good`    | Yellow | 0.5 - 0.8        |
+| `perfect` | Green  | > 0.8            |
+
+---
+
+### Frame Analysis Utilities
+
+Utilities for assessing frame quality before submission.
+
+```typescript
+import { isFaceFullyVisible, isFaceInOval, calculateFaceCropRegion } from '@moveris/shared';
+
+// Check if face is fully visible in frame
+const visibility = isFaceFullyVisible(faceBbox, frameWidth, frameHeight);
+console.log(visibility.isVisible); // true/false
+console.log(visibility.reason); // 'left_edge' | 'top_edge' | etc.
+
+// Check if face is within the oval guide
+const inOval = isFaceInOval(faceBbox, ovalRegion);
+console.log(inOval.isInOval); // true/false
+console.log(inOval.alignmentScore); // 0-1
+
+// Calculate crop region for face
+const cropRegion = calculateFaceCropRegion(faceBbox, frameWidth, frameHeight);
+```
+
+---
+
+## Configuration Constants
+
+```typescript
+import { DEFAULT_ENDPOINT, AUTH_CONFIG, RETRY_CONFIG, FRAME_CONFIG } from '@moveris/shared';
+
+console.log(DEFAULT_ENDPOINT); // 'https://api.moveris.io'
+console.log(AUTH_CONFIG.apiKeyHeader); // 'X-API-Key'
+console.log(RETRY_CONFIG.maxAttempts); // 3
+console.log(FRAME_CONFIG.maxBufferSize); // 10
+```
+
+---
+
+## TypeScript Support
+
+This package is written in TypeScript and provides full type definitions.
+
+```typescript
+import type {
+  LivenessResult,
+  LivenessState,
+  LivenessConfig,
+  FastCheckModel,
+  FrameSource,
+  Verdict,
+  CapturedFrame,
+  LivenessClientConfig,
+} from '@moveris/shared';
+```
+
+---
+
+## License
 
-See [API Documentation](../../docs/api-reference.md#shared-package) for complete API reference.
+MIT

package/package.json

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