@smartspectra/node-sdk 3.4.0-rc.5 → 3.4.0-rc.7

package/js/renderer/index.d.ts

@@ -18,6 +18,7 @@ export {
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,
@@ -31,6 +32,7 @@ export type {
     ValidationCodeValue,
     SmartSpectraErrorCodeValue,
     FrameTransformValue,
+    MetricTypeValue,
     SmartSpectraOptions,
 } from '../../js/index';
 

package/js/smartspectra.js

@@ -5,7 +5,8 @@
 
 'use strict';
 
-const { Session, ensurePreconfigured } = require('./ffi');
+const { Session, ensurePreconfigured, availableCameras } = require('./ffi');
+const { CameraSelection, normalizeCameraSelection, normalizeCameraOptions } = require('./camera-selection');
 const {
     ProcessingStatus,
     SmartSpectraLogLevel,
@@ -13,6 +14,7 @@ const {
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,
@@ -41,6 +43,9 @@ class SmartSpectraSDK {
     /** SDK package version (matches `package.json#version`). */
     static get version() { return PACKAGE_VERSION; }
 
+    /** Discover cameras without a session, authentication, or capture. */
+    static availableCameras() { return availableCameras(); }
+
     /**
      * @param {Object} [options]
      * @param {string} [options.apiKey]
@@ -64,7 +69,9 @@ class SmartSpectraSDK {
         // consumed by start(). Shape: { kind: 'custom'|'camera'|'file', ... }.
         // The last use* call wins.
         this._source = null;
+        this._explicitCameraSelection = false;
         this._session = null;  // lazy: created on start()
+        this._destroyPromise = null;
     }
 
     // ---------- public API --------------------------------------------------
@@ -92,6 +99,7 @@ class SmartSpectraSDK {
      *   Spatial transform applied to every pushed frame.
      */
     useCustomInput(frameTransform = DEFAULT_FRAME_TRANSFORM) {
+        if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         this._source = { kind: 'custom', frameTransform: frameTransform | 0 };
         return this;
     }
@@ -101,14 +109,28 @@ class SmartSpectraSDK {
      * pumps frames internally on start() — no sendFrame() needed. Returns
      * `this` for chaining.
      *
-     * @param {Object} [options] { deviceIndex?, width?, height?, fps?, frameTransform? }
+     * Selection is stopped-only and resolved at startup. Explicit requests never
+     * fall back. Stop/start/reset retain the selection. Capture options are separate.
+     * The deprecated useCamera(options) overload retains index-based capture
+     * and the legacy source lifecycle; omit options for camera index zero.
      *
      * Captures from a camera in THIS process (headless / Node use). In an
      * Electron app the camera is normally owned by the renderer via
      * getUserMedia — use the renderer SDK's useMediaStream() there instead.
      */
-    useCamera(options = null) {
-        this._source = { kind: 'camera', options };
+    useCamera(selection = null, options = {}) {
+        const isSelection = selection !== null && typeof selection === 'object' && 'kind' in selection;
+        if (!isSelection && arguments.length < 2) {
+            if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
+            this._source = { kind: 'camera', options: selection };
+            this._explicitCameraSelection = false;
+            return this;
+        }
+        this._requireSourceSelectionAllowed();
+        const request = normalizeCameraSelection(selection);
+        const capture = normalizeCameraOptions(options);
+        this._source = { kind: 'camera', selection: request, options: capture };
+        this._explicitCameraSelection = true;
         return this;
     }
 
@@ -123,6 +145,7 @@ class SmartSpectraSDK {
      *   { timestampsPath?, interframeDelayMs?, startOffsetMs?, maxDurationMs?, frameTransform? }
      */
     useFile(videoPath, options = null) {
+        if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         if (typeof videoPath !== 'string' || !videoPath) {
             throw new TypeError('useFile: videoPath must be a non-empty string');
         }
@@ -134,9 +157,10 @@ class SmartSpectraSDK {
      * Initialize the session and start the configured input source. Returns
      * once running — for custom input the graph is armed for sendFrame(); for
      * camera/file the SDK pumps frames itself. Configure a source with
-     * useCustomInput() / useCamera() / useFile() first.
+     * useCustomInput(), useCamera(), or useFile() first.
      */
     start() {
+        if (this._explicitCameraSelection) this._requireSourceSelectionAllowed();
         const source = this._source;
         if (!source) {
             throw new Error(
@@ -149,7 +173,8 @@ class SmartSpectraSDK {
                 this._session.startCustom(source.frameTransform);
                 break;
             case 'camera':
-                this._session.startCamera(source.options);
+                if (source.selection) this._session.startCamera(source.selection, source.options);
+                else this._session.startLegacyCamera(source.options);
                 break;
             case 'file':
                 this._session.startFile(
@@ -177,14 +202,14 @@ class SmartSpectraSDK {
     }
 
     /**
-     * Recover from a kError state. Rebuilds the internal graph. The input
-     * source is discarded — call useCustomInput() / useCamera() / useFile()
-     * AND start() again to drive new input.
+     * Recover from a kError state. Clears the input source for legacy callers.
+     * After useCamera(selection, options), retains the selected input.
+     * Typed selection requires any pending stopAsync() to settle before reset.
      */
     reset() {
         if (!this._session) return;
-        this._session.reset();
-        this._source = null;
+        this._session.reset(this._explicitCameraSelection);
+        if (!this._explicitCameraSelection) this._source = null;
     }
 
     /**
@@ -239,15 +264,26 @@ class SmartSpectraSDK {
      * replacement session, since SDK state is process-global.
      */
     destroy() {
+        if (this._destroyPromise) return this._destroyPromise;
         if (!this._session) return Promise.resolve();
         const teardown = this._session.destroy();
         this._session = null;
         this._source = null;
-        return teardown;
+        this._destroyPromise = Promise.resolve(teardown).finally(() => { this._destroyPromise = null; });
+        return this._destroyPromise;
     }
 
     // ---------- internal ----------------------------------------------------
 
+    _requireSourceSelectionAllowed() {
+        if (this._destroyPromise) {
+            throw Object.assign(new Error('SmartSpectra is shutting down'), {
+                code: SmartSpectraErrorCode.kInvalidState, retryable: false,
+            });
+        }
+        this._session?.assertSourceSelectionAllowed();
+    }
+
     _ensureSession() {
         if (this._session) return;
         // ARTERIAL_PRESSURE_TRACE, EDA_TRACE, and micromotion metrics need the
@@ -289,12 +325,14 @@ class SmartSpectraSDK {
 
 module.exports = {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.4.0-rc.5",
+  "version": "3.4.0-rc.7",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -40,7 +40,8 @@
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "node --test test/log-level-pin.js test/renderer-timestamp.js test/smoke.js",
+    "test": "npm run test:types && node --test test/log-level-pin.js test/renderer-timestamp.js test/camera-selection.js test/reset-lifecycle.js test/smoke.js",
+    "test:types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext test/camera-selection-types.ts",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -70,14 +71,15 @@
   "dependencies": {
     "koffi": "^2.10.0",
     "protobufjs": "^7.6.5",
-    "@smartspectra/node-sdk-linux-x64": "3.4.0-rc.5",
-    "@smartspectra/node-sdk-linux-arm64": "3.4.0-rc.5",
-    "@smartspectra/node-sdk-darwin-arm64": "3.4.0-rc.5",
-    "@smartspectra/node-sdk-win32-x64": "3.4.0-rc.5"
+    "@smartspectra/node-sdk-linux-x64": "3.4.0-rc.7",
+    "@smartspectra/node-sdk-linux-arm64": "3.4.0-rc.7",
+    "@smartspectra/node-sdk-darwin-arm64": "3.4.0-rc.7",
+    "@smartspectra/node-sdk-win32-x64": "3.4.0-rc.7"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "protobufjs-cli": "^1.1.3"
+    "protobufjs-cli": "^1.1.3",
+    "typescript": "^6.0.2"
   },
   "_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": {