@smartspectra/node-sdk 3.3.0-rc.3 → 3.3.0-rc.6

package/js/constants.js

@@ -48,6 +48,7 @@ const ValidationCode = Object.freeze({
     kNoFaceFound:        1,
     kMultipleFacesFound: 2,
     kFaceNotCentered:    3,
+    /** @deprecated Use kFaceTooClose / kFaceTooFar instead. */
     kFaceSizeOutOfRange: 4,
     kTooDark:            5,
     kTooBright:          6,
@@ -55,6 +56,10 @@ const ValidationCode = Object.freeze({
     kCameraTuning:       10,
     kFrameRateTooLow:    11,
     kExcessiveMotion:    12,
+    kFaceTooClose:       13,
+    kFaceTooFar:         14,
+    kFaceTooHigh:        15,
+    kFaceTooLow:         16,
 });
 
 const SmartSpectraErrorCode = Object.freeze({

package/js/ffi.js

@@ -13,6 +13,9 @@
 
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const koffi = require('koffi');
 const { resolveNativeLibrary } = require('./resolve-native');
 
@@ -444,21 +447,38 @@ class Session {
                 () => this._teardownNative(),
                 () => this._teardownNative());
         } else {
-            this._teardownNative();
-            this._teardownPromise = Promise.resolve();
+            this._teardownPromise = this._teardownNative();
         }
         return this._teardownPromise;
     }
 
+    // Returns a promise that resolves once native teardown (including any
+    // worker-thread joins inside session_destroy) has completed.
     _teardownNative() {
-        if (this._sess === null) return;
-        // stop → wait → destroy → unregister. session_destroy joins worker
-        // threads, so no SDK thread can call our trampolines after it returns.
+        if (this._sess === null) return Promise.resolve();
+        // stop → wait → destroy → unregister. session_destroy joins every
+        // worker thread SpawnWorker ever started for this session — including
+        // one that's mid-flight relaying an onError/onStatus callback to JS
+        // (e.g. an async graph failure). That relay can only complete once
+        // the JS event loop is free to service it, so running session_destroy
+        // synchronously here would deadlock: this call IS the JS thread, and
+        // it would be blocked joining a thread that's blocked waiting on this
+        // same thread's event loop. Run it on a koffi worker thread instead —
+        // the same reason stopAsync() runs session_stop off-thread above —
+        // so the event loop stays free no matter what a worker is mid-relay
+        // of. _releaseThunks() only runs after the callback fires, matching
+        // the original synchronous ordering (unregister only after the joins
+        // that guarantee no SDK thread can still call our trampolines).
         sessionStop(this._sess);
         sessionWait(this._sess, 0);
-        sessionDestroy(this._sess);
+        const sess = this._sess;
         this._sess = null;
-        this._releaseThunks();
+        return new Promise((resolve) => {
+            sessionDestroy.async(sess, () => {
+                this._releaseThunks();
+                resolve();
+            });
+        });
     }
 
     // ---------- internal ----------------------------------------------------
@@ -490,9 +510,11 @@ function makeFfiError(err) {
     return e;
 }
 
-// Internal one-time SDK initialization. Called by the Electron main-process
-// glue in `@smartspectra/node-sdk/main`. Not part of the package's public
-// exports map — host apps don't reach for it.
+// Internal one-time SDK initialization. Called directly by the Electron
+// main-process glue in `@smartspectra/node-sdk/main` (which namespaces its
+// own cache directory under app.getPath('cache')). Not part of the package's
+// public exports map — host apps don't reach for it; use ensurePreconfigured()
+// below for the plain-Node default instead.
 function preconfigure(sdkDirectory, deviceId) {
     if (typeof sdkDirectory !== 'string' || sdkDirectory.length === 0) {
         throw new TypeError('preconfigure: directory must be a non-empty string');
@@ -502,7 +524,48 @@ function preconfigure(sdkDirectory, deviceId) {
     if (rc !== 0) throw makeFfiError(err);
 }
 
+// Per-OS writable cache directory, used as the default when nothing else
+// (e.g. Electron's app.getPath('cache')) has already resolved one.
+function defaultSdkDirectory() {
+    const base = process.platform === 'darwin'
+        ? path.join(os.homedir(), 'Library', 'Caches')
+        : process.platform === 'win32'
+            ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'))
+            : (process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'));
+    return path.join(base, 'SmartSpectraSDK');
+}
+
+let autoPreconfigureAttempted = false;
+
+// Idempotent, best-effort preconfigure for hosts that never call preconfigure()
+// themselves. ARTERIAL_PRESSURE_TRACE, EDA_TRACE, and micromotion metrics need
+// the device-key cache directory Preconfigure() sets up (smartspectra.h); without
+// it their encrypted-model load fails downstream and Session.start*() throws —
+// only Electron's main-process glue (js/main/index.js) called this previously,
+// so a plain Node host requesting one of those metrics had no way to succeed.
+// Runs once per process; failures are logged, not thrown, so metrics that don't
+// need EMD still work. Called from SmartSpectraSDK._ensureSession() so every
+// entry point — plain Node or Electron — gets it before a session can start;
+// Preconfigure() itself only resolves the directory/device-identity once, so a
+// prior, more specific call (e.g. Electron's app-namespaced one) always wins.
+function ensurePreconfigured() {
+    if (autoPreconfigureAttempted) return;
+    autoPreconfigureAttempted = true;
+    const sdkDirectory = defaultSdkDirectory();
+    try {
+        // nosemgrep: detect-non-literal-fs-filename - safe: derived from OS-standard cache path env vars / os.homedir(), not untrusted input.
+        fs.mkdirSync(sdkDirectory, { recursive: true, mode: 0o700 });
+        preconfigure(sdkDirectory);
+    } catch (err) {
+        console.error(
+            `SmartSpectra: automatic preconfigure failed (${err.message || err}). ` +
+            'Arterial pressure, EDA, and micromotion metrics will not be available ' +
+            `until preconfigure() succeeds for ${sdkDirectory}; other metrics still work.`);
+    }
+}
+
 module.exports = {
     Session,
     preconfigure,
+    ensurePreconfigured,
 };

package/js/index.d.ts

@@ -46,6 +46,7 @@ export declare const ValidationCode: {
     readonly kNoFaceFound:        1;
     readonly kMultipleFacesFound: 2;
     readonly kFaceNotCentered:    3;
+    /** @deprecated Use kFaceTooClose / kFaceTooFar instead. */
     readonly kFaceSizeOutOfRange: 4;
     readonly kTooDark:            5;
     readonly kTooBright:          6;
@@ -53,6 +54,10 @@ export declare const ValidationCode: {
     readonly kCameraTuning:       10;
     readonly kFrameRateTooLow:    11;
     readonly kExcessiveMotion:    12;
+    readonly kFaceTooClose:       13;
+    readonly kFaceTooFar:         14;
+    readonly kFaceTooHigh:        15;
+    readonly kFaceTooLow:         16;
 };
 export type ValidationCodeValue = typeof ValidationCode[keyof typeof ValidationCode];
 

package/js/messages/generated.d.ts

@@ -596,6 +596,9 @@ export namespace presage {
 
             /** Confidence score for the HRV measurement, expressed as a percentage in the range [0.0, 100.0] */
             confidence?: (number|null);
+
+            /** Whether the HRV measurement is considered stable/reliable */
+            stable?: (boolean|null);
         }
 
         /** Represents a single HRV measurement computed over some period of pulse data. */
@@ -625,6 +628,9 @@ export namespace presage {
             /** Confidence score for the HRV measurement, expressed as a percentage in the range [0.0, 100.0] */
             public confidence: number;
 
+            /** Whether the HRV measurement is considered stable/reliable */
+            public stable: boolean;
+
             /**
              * Creates a new Hrv instance using the specified properties.
              * @param [properties] Properties to set