@nuralogix.ai/web-measurement-embedded-app 0.1.0-beta.8 → 1.0.0

package/README.md

@@ -47,9 +47,9 @@ Need deeper integration details? Check the full docs at [docs.deepaffex.ai/wmea]
         const token = await fetch(`${apiUrl}/token`);
         const tokenResponse = await token.json();
         if (studyIdResponse.status === '200' && tokenResponse.status === '200') {
-          measurementApp.on.results = (results) => {
+          measurementApp.on.results = async (results) => {
             console.log('Results received', results);
-            measurementApp.destroy();
+            const isDestroyed = await measurementApp.destroy();
           };
           measurementApp.on.error = (error) => {
             console.log('error received', error);
@@ -66,11 +66,16 @@ Need deeper integration details? Check the full docs at [docs.deepaffex.ai/wmea]
                 token: tokenResponse.token,
                 refreshToken: tokenResponse.refreshToken,
                 studyId: studyIdResponse.studyId,
+                // Optional measurement options
+                // measurementOptions: {
+                //   partnerId: 'your-partner-id',
+                //   userProfileId: 'your-user-profile-id',
+                // },
               },
               profile: {
                 age: 40,
-                height: 180,
-                weight: 60,
+                heightCm: 180,
+                weightKg: 60,
                 sex: SEX_ASSIGNED_MALE_AT_BIRTH,
                 smoking: SMOKER_FALSE,
                 bloodPressureMedication: BLOOD_PRESSURE_MEDICATION_FALSE,
@@ -84,6 +89,8 @@ Need deeper integration details? Check the full docs at [docs.deepaffex.ai/wmea]
                 cameraAutoStart: false,
                 measurementAutoStart: false,
                 cancelWhenLowSNR: true,
+                debugMode: false,
+                downloadPayloads: false,
               },
               // Optional language/api overrides
               // language: 'fr'
@@ -106,6 +113,13 @@ Need deeper integration details? Check the full docs at [docs.deepaffex.ai/wmea]
 - Set `appPath` to `'.'` when you bundle the assets yourself.
 - Profile handling: when `bypassProfile` remains `true` (default) we skip demographic submission and emit an `ERROR` event with `PROFILE_INFO_NOT_SET`; set it to `false` once you supply real profile data.
 - Style the container you pass to `init` (e.g., position, top, width).
+- Settings options:
+  - `token` (required) – authentication token from DeepAffex API.
+  - `refreshToken` (required) – refresh token for token renewal.
+  - `studyId` (required) – study identifier for the measurement.
+  - `measurementOptions` (optional) – additional options passed to the SDK when starting a measurement:
+    - `partnerId` – partner identifier for tracking.
+    - `userProfileId` – user profile identifier for tracking. Must be a valid UUID.
 - Optional `apiUrl` enables region-specific processing; omitted values follow the backend token's region automatically. When set explicitly, frontend calls your URL (processing where that endpoint runs) while results continue to store in the token's region—verify the combination suits your deployment.
 - Config options:
   - `checkConstraints` (default: `true`) – enables constraint validation pre-measurement
@@ -113,6 +127,8 @@ Need deeper integration details? Check the full docs at [docs.deepaffex.ai/wmea]
   - `cameraAutoStart` (default: `false`) – automatically starts the camera once permission is granted.
   - `measurementAutoStart` (default: `false`) – automatically starts the measurement once constraints are satisfied.
   - `cancelWhenLowSNR` (default: `true`) – cancels the measurement if signal-to-noise ratio falls below threshold.
+  - `debugMode` (default: `false`) – enables verbose logging to the console for debugging purposes.
+  - `downloadPayloads` (default: `false`) – when enabled, saves payload and metadata binary files for each chunk sent to DeepAffex Cloud so you can send them to NuraLogix for debugging. A 30-second measurement emits 6 chunks (every 5 seconds), generating 2 files per chunk. Ensure your browser allows multiple file downloads and does not block popups.
 - Language support: `en`, `ja`, `zh`, `es`, `pt`, `pt-BR`, `it`, `fr`, `de`.
   - Unsupported browser locales fall back to base language (e.g., `zh-TW` → `zh`), then to English.
 
@@ -154,14 +170,15 @@ event: ((appEvent: AppEvent) => void) | null;
 - `APP_LOADED` – the embedded app finished its startup sequence.
 - `MEASUREMENT_PREPARED` - Measurement has been prepared
 - `ASSETS_DOWNLOADED` - Assets have been downloaded
+- `FACE_TRACKER_LOADED` - Face tracker is loaded. Payload: `{ version }` with SDK version info (`webSDK`, `extractionLib`, `faceTracker`).
 - `CAMERA_PERMISSION_GRANTED` – the user granted camera access.
 - `CAMERA_STARTED` – a camera stream opened successfully.
-- `MEASUREMENT_STARTED` – a measurement run begins.
+- `MEASUREMENT_STARTED` – a measurement run begins. Payload: `{ measurementId, measurementOptions }` with the measurement ID and measurement options (empty object `{}` if none provided).
 - `MEASUREMENT_COMPLETED` – the measurement finished and results are stable.
-- `INTERMEDIATE_RESULTS` – partial results are available during an active run.
+- `INTERMEDIATE_RESULTS` – partial results are available during an active run. Payload: `{ points }` with intermediate values.
 - `RESULTS_RECEIVED` – the final measurement results are available.
 - `MEASUREMENT_CANCELED` – the user canceled the active measurement.
-- `CONSTRAINT_VIOLATION` – a constraint (e.g., face distance) failed.
+- `CONSTRAINT_VIOLATION` – a constraint (e.g., face distance) failed. Payload: `{ code }` with one of: `TOO_CLOSE`, `TOO_FAR`, `TURN_LEFT`, `TURN_RIGHT`, `LOOK_UP`, `LOOK_DOWN`, `TILT_LEFT`, `TILT_RIGHT`, `NOT_CENTERED`, `HOLD_STILL`.
 - `PAGE_VISIBILITY_CHANGE` – the page changed visibility (e.g., tab switch or minimize).
 - `PAGE_UNLOADED` – the page is unloading.
 
@@ -176,15 +193,20 @@ measurementApp.setLanguage('es');
 
 **Error codes emitted through `measurementApp.on.error`:**
 
-| Code                         | Meaning                                                           |
-| ---------------------------- | ----------------------------------------------------------------- |
-| `CAMERA_PERMISSION_DENIED`   | Camera access prompt was rejected.                                |
-| `CAMERA_START_FAILED`        | Camera hardware failed to start after permission.                 |
-| `NO_DEVICES_FOUND`           | No video input devices detected during enumeration.               |
-| `PAGE_NOT_VISIBLE`           | Measurement was running while the tab or window became hidden.    |
-| `MEASUREMENT_LOW_SNR`        | Signal-to-noise ratio dropped below the acceptable threshold.     |
-| `WORKER_ERROR`               | SDK worker encountered a fatal processing error.                  |
-| `PROFILE_INFO_NOT_SET`       | Profile bypass stayed enabled, so demographics were not provided. |
-| `COLLECTOR`                  | Frame collection reported an error                                |
-| `WEBSOCKET_DISCONNECTED`     | Realtime WebSocket connection closed or dropped.                  |
-| `MEASUREMENT_PREPARE_FAILED` | Measurement preparation failed - invalid or missing credentials   |
+| Code                          | Meaning                                                               |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `CAMERA_PERMISSION_DENIED`    | Camera access prompt was rejected.                                    |
+| `CAMERA_START_FAILED`         | Camera hardware failed to start after permission.                     |
+| `NO_DEVICES_FOUND`            | No video input devices detected during enumeration.                   |
+| `PAGE_NOT_VISIBLE`            | Measurement was running while the tab or window became hidden.        |
+| `MEASUREMENT_LOW_SNR`         | Signal-to-noise ratio dropped below the acceptable threshold.         |
+| `WORKER_ERROR`                | SDK worker encountered a fatal processing error.                      |
+| `PROFILE_INFO_NOT_SET`        | Profile bypass stayed enabled, so demographics were not provided.     |
+| `INVALID_PROFILE`             | Profile is invalid                                                    |
+| `COLLECTOR`                   | Frame collection reported an error                                    |
+| `FACE_NONE`                   | Face not detected during measurement (after threshold frames).        |
+| `WEBSOCKET_DISCONNECTED`      | Realtime WebSocket connection closed or dropped.                      |
+| `MEASUREMENT_PREPARE_FAILED`  | Measurement preparation failed - invalid or missing credentials       |
+| `INVALID_MEASUREMENT_OPTIONS` | Invalid measurement options (e.g., userProfileId is not a valid UUID) |
+| `ASSET_DOWNLOAD_FAILED`       | Failed to download assets and initialize the SDK                      |
+