@smartspectra/node-sdk 3.3.0-rc.7 → 3.4.0-rc.2

package/NOTICE

@@ -17,7 +17,6 @@ The following Apache-licensed components are included in this shipped artifact:
   - Kompute
   - MediaPipe
   - ml_dtypes
-  - OpenCensus Proto
   - OpenCV
   - protoc-gen-validate
   - ruy

package/README.md

@@ -1,6 +1,7 @@
 ---
-title: Node.js SDK
-description: Build Node.js apps — including Electron desktop apps — with SmartSpectra via a packaged native runtime loaded through koffi.
+title: Node.js and Electron SDK
+sidebarTitle: Overview
+description: Build Node.js and Electron apps that measure pulse and breathing from a camera on Linux, macOS, and Windows, using a prebuilt native runtime from npm.
 ---
 
 # @smartspectra/node-sdk
@@ -104,26 +105,20 @@ the missing package.
 
 - Electron desktop app: use `@smartspectra/node-sdk/main`,
   `@smartspectra/node-sdk/preload`, and `@smartspectra/node-sdk/renderer`.
-- Headless or server-side Node process: use `@smartspectra/node-sdk`
-  directly and push frames with `useCustomInput()` / `sendFrame()`.
+- Headless Node process with a local camera: use `@smartspectra/node-sdk`
+  directly with `useCamera()`.
+- Headless or server-side Node process with host-provided frames: use
+  `useCustomInput()` / `sendFrame()`.
 - Runnable reference app: [electron-quickstart](https://github.com/Presage-Security/SmartSpectra/tree/main/nodejs/samples/electron-quickstart)
 
-## Headless Node Quickstart
+## Camera Quickstart
 
 > The snippets below are ES modules (`import` + top-level `await`) — save them as `.mjs`, or
 > set `"type": "module"` in your `package.json`. In a CommonJS project, use `require()` and
 > wrap the `await` calls in an `async` function.
 
 ```ts
-import {
-  SmartSpectraSDK, PixelFormat, FrameTransform, ProcessingStatus,
-  breathingMetrics, cardioMetrics,
-  decodeMetrics, setMetricsClass,
-} from '@smartspectra/node-sdk';
-
-// Optional: override the default Metrics decoder.
-// import { Metrics } from './generated/metrics_pb';
-// setMetricsClass(Metrics);
+import { SmartSpectraSDK, breathingMetrics, cardioMetrics, decodeMetrics } from '@smartspectra/node-sdk';
 
 const sdk = new SmartSpectraSDK({
   apiKey: 'YOUR_API_KEY',
@@ -134,20 +129,39 @@ sdk.on('processingStatus', (status) => console.log('Processing status:', status)
 sdk.on('validationStatus', (code, ts, hint) =>
   console.log('Validation:', code, hint, 'at', ts, 'µs'));
 sdk.on('metrics', (buf, ts) => {
-  const m = decodeMetrics(buf);
-  console.log('Metrics at', ts, 'µs');
+  console.log('Metrics at', ts, 'µs:', decodeMetrics(buf));
 });
 sdk.on('error', (code, message, retryable) =>
   console.error('SmartSpectra error', code, message, 'retryable=', retryable));
 
-sdk.useCustomInput(FrameTransform.kNone);
+sdk.useCamera();
 sdk.start();
 
-// In your capture loop:
-sdk.sendFrame(rgbBuf, width, height, width * 3, PixelFormat.kRGB, captureTsUs);
+console.log('Measuring from the default camera. Press Ctrl+C to stop.');
 
 // On shutdown:
-await sdk.destroy();
+process.on('SIGINT', async () => {
+  await sdk.stopAsync();
+  await sdk.destroy();
+  process.exit(0);
+});
+```
+
+`useCamera()` opens the default camera and sends frames after `start()`. Pass a
+device index or capture dimensions to select another camera; see the [API
+reference](docs/api-reference.md#cameraoptions). Use the custom-input path
+below only when your app already owns frame capture.
+
+## Custom Input Quickstart
+
+To supply frames from another source, replace the camera setup with:
+
+```ts
+import { FrameTransform, PixelFormat } from '@smartspectra/node-sdk';
+
+sdk.useCustomInput(FrameTransform.kNone);
+sdk.start();
+sdk.sendFrame(rgbBuf, width, height, width * 3, PixelFormat.kRGB, captureTsUs);
 ```
 
 ## API reference

package/THIRD_PARTY_NOTICES.txt

@@ -21,7 +21,6 @@ Apache-2.0
   - Kompute
   - MediaPipe
   - ml_dtypes
-  - OpenCensus Proto
   - OpenCV
   - protoc-gen-validate
   - ruy
@@ -295,7 +294,7 @@ Full license texts included in this file
    See the License for the specific language governing permissions and
    limitations under the License.
 
-Applies to: Abseil, CNCF xDS API, Envoy data-plane-api, FlatBuffers, gemmlowp, Google APIs, gRPC, HighwayHash, KleidiAI, Kompute, MediaPipe, ml_dtypes, OpenCensus Proto, OpenCV, protoc-gen-validate, ruy, TensorFlow (TensorFlow Lite)
+Applies to: Abseil, CNCF xDS API, Envoy data-plane-api, FlatBuffers, gemmlowp, Google APIs, gRPC, HighwayHash, KleidiAI, Kompute, MediaPipe, ml_dtypes, OpenCV, protoc-gen-validate, ruy, TensorFlow (TensorFlow Lite)
 
 ===== BSD-2-Clause =====
 Copyright (c) <year> <owner>. All rights reserved.

package/js/constants.js

@@ -9,6 +9,8 @@
 //
 // Integer values must match the SmartSpectra C++ headers and
 // metric_types.proto wire values; stable across SDK versions.
+// ValidationCode / SmartSpectraErrorCode are governed by
+// smartspectra/error_codes.yaml (checked by `task ci:error-codes:verify`).
 
 'use strict';
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.3.0-rc.7",
+  "version": "3.4.0-rc.2",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -70,10 +70,10 @@
   "dependencies": {
     "koffi": "^2.10.0",
     "protobufjs": "^7.6.5",
-    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.7",
-    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.7",
-    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.7",
-    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.7"
+    "@smartspectra/node-sdk-linux-x64": "3.4.0-rc.2",
+    "@smartspectra/node-sdk-linux-arm64": "3.4.0-rc.2",
+    "@smartspectra/node-sdk-darwin-arm64": "3.4.0-rc.2",
+    "@smartspectra/node-sdk-win32-x64": "3.4.0-rc.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",