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

package/README.md

@@ -60,6 +60,11 @@ thread-safe trampolines.
 | Node.js | >= 20 (Node 24 LTS recommended) |
 | Electron (optional) | >= 28 |
 
+You also need an API key from
+[physiology.presagetech.com](https://physiology.presagetech.com/auth/login). An AI assistant
+connected to the [SmartSpectra MCP Server](../docs/mcp-server.md) can fetch it from your account
+for you.
+
 The native runtime ships in per-platform npm packages pulled in automatically
 as dependencies — no install script and no system libraries to install.
 

package/js/constants.js

@@ -60,6 +60,7 @@ const ValidationCode = Object.freeze({
     kFaceTooFar:         14,
     kFaceTooHigh:        15,
     kFaceTooLow:         16,
+    kFaceNotForward:       17,
 });
 
 const SmartSpectraErrorCode = Object.freeze({

package/js/ffi.js

@@ -262,6 +262,17 @@ class Session {
         }
 
         this._registeredThunks = [];
+        // Held from a successful start*() until native teardown completes
+        // (_teardownNative(), the destroy() path) — NOT released by
+        // stop()/stopAsync()/reset(). Those calls can return while a worker
+        // thread is still mid-relay of a trailing callback (e.g. the idle
+        // status transition after stop()); only session_destroy's joins
+        // guarantee no SDK thread can still call our trampolines. koffi's
+        // registered thunks do NOT ref the libuv loop, so without this a host
+        // whose only pending work is awaiting an SDK-callback-resolved
+        // promise drains its loop, Node disposes the isolate, and the next
+        // relayed callback segfaults the process (exit 139).
+        this._keepAlive = null;
         this._destroyed = false;
         // In-flight stopAsync() promise, if any. session_stop runs on a koffi
         // worker thread; destroy() must wait for it to settle before deleting
@@ -329,6 +340,7 @@ class Session {
         } : null;
         const rc = sessionStartFile(this._sess, videoPath, timestampsPath, opts, err);
         if (rc !== 0) throw makeFfiError(err);
+        this._takeKeepAlive();
     }
 
     // options (optional): { deviceIndex, width, height, fps, frameTransform }
@@ -344,6 +356,7 @@ class Session {
         } : null;
         const rc = sessionStartCamera(this._sess, opts, err);
         if (rc !== 0) throw makeFfiError(err);
+        this._takeKeepAlive();
     }
 
     startCustom(frameTransform = 0) {
@@ -351,6 +364,7 @@ class Session {
         const err = {};
         const rc = sessionStartCustom(this._sess, frameTransform | 0, err);
         if (rc !== 0) throw makeFfiError(err);
+        this._takeKeepAlive();
     }
 
     sendFrame(buffer, width, height, strideBytes, pixelFormat, timestampUs) {
@@ -455,27 +469,21 @@ class Session {
     // Returns a promise that resolves once native teardown (including any
     // worker-thread joins inside session_destroy) has completed.
     _teardownNative() {
-        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);
+        if (this._sess === null) {
+            this._releaseKeepAlive();
+            return Promise.resolve();
+        }
+        // session_destroy performs the required best-effort stop and worker
+        // joins. Run that entire drain off the JS thread: an SDK worker may be
+        // blocked relaying a callback onto this event loop, so synchronously
+        // stopping or waiting here would deadlock both threads. Unregister the
+        // thunks only after destroy has joined every possible caller.
         const sess = this._sess;
         this._sess = null;
         return new Promise((resolve) => {
             sessionDestroy.async(sess, () => {
                 this._releaseThunks();
+                this._releaseKeepAlive();
                 resolve();
             });
         });
@@ -498,6 +506,19 @@ class Session {
         for (const t of this._registeredThunks) koffi.unregister(t);
         this._registeredThunks = [];
     }
+
+    _takeKeepAlive() {
+        if (this._keepAlive !== null) return;
+        // Max-int32 ms (~24.8 days): the timer exists only to hold a loop
+        // reference; it never meaningfully fires.
+        this._keepAlive = setInterval(() => {}, 2 ** 31 - 1);
+    }
+
+    _releaseKeepAlive() {
+        if (this._keepAlive === null) return;
+        clearInterval(this._keepAlive);
+        this._keepAlive = null;
+    }
 }
 
 // Wrap a populated smartspectra_error_t into a JS Error with numeric `code`

package/js/index.d.ts

@@ -58,6 +58,7 @@ export declare const ValidationCode: {
     readonly kFaceTooFar:         14;
     readonly kFaceTooHigh:        15;
     readonly kFaceTooLow:         16;
+    readonly kFaceNotForward:       17;
 };
 export type ValidationCodeValue = typeof ValidationCode[keyof typeof ValidationCode];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.3.0-rc.6",
+  "version": "3.3.0",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -40,7 +40,7 @@
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "node test/log-level-pin.js && node test/renderer-timestamp.js && node test/smoke.js",
+    "test": "node --test test/log-level-pin.js test/renderer-timestamp.js test/smoke.js",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -69,18 +69,18 @@
   "_nativeRuntime_doc": "Per-platform native packages (@smartspectra/node-sdk-<plat>-<arch>) are injected into dependencies at publish time (absent here so source installs don't fetch them). Why hard deps, not optionalDependencies: see js/resolve-native.js.",
   "dependencies": {
     "koffi": "^2.10.0",
-    "protobufjs": "^7.5.0",
-    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.6",
-    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.6",
-    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.6",
-    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.6"
+    "protobufjs": "^7.6.5",
+    "@smartspectra/node-sdk-linux-x64": "3.3.0",
+    "@smartspectra/node-sdk-linux-arm64": "3.3.0",
+    "@smartspectra/node-sdk-darwin-arm64": "3.3.0",
+    "@smartspectra/node-sdk-win32-x64": "3.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "protobufjs-cli": "^1.1.3"
   },
-  "_overrides_doc": "tmp is pulled in transitively (protobufjs-cli → tmp) as a build-only devDependency; it is never a runtime dependency and is not shipped to consumers (the published tarball ships js/ + prebuilds only, no node_modules). Pinned to an exact version (not a >= range) to clear GHSA-ph9p-34f9-6g65 (path traversal, affects tmp <0.2.6) AND to keep installs deterministic — an open range would let a future install pull a brand-new, not-yet-vetted release. Bump deliberately. Drop this once protobufjs-cli ships a release whose tmp range is already >=0.2.6.",
+  "_overrides_doc": "tmp is pulled in transitively (protobufjs-cli → tmp) as a build-only devDependency; it is never a runtime dependency and is not shipped to consumers (the published tarball ships js/ + prebuilds only, no node_modules). Pinned to an exact version (not a >= range) to clear GHSA-ph9p-34f9-6g65 (path traversal, affects tmp <0.2.6) and GHSA-7c78-jf6q-g5cm (type-confusion bypass of the 0.2.6 _assertPath guard, affects tmp >=0.2.6) AND to keep installs deterministic — an open range would let a future install pull a brand-new, not-yet-vetted release. Bump deliberately. Drop this once protobufjs-cli ships a release whose tmp range is already >=0.2.7.",
   "overrides": {
-    "tmp": "0.2.6"
+    "tmp": "0.2.7"
   }
 }