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

package/README.md

@@ -106,7 +106,7 @@ the missing package.
 - Electron desktop app: use `@smartspectra/node-sdk/main`,
   `@smartspectra/node-sdk/preload`, and `@smartspectra/node-sdk/renderer`.
 - Headless Node process with a local camera: use `@smartspectra/node-sdk`
-  directly with `useCamera()`.
+  directly with `useCamera(CameraSelection.default)`.
 - 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)
@@ -118,7 +118,7 @@ the missing package.
 > wrap the `await` calls in an `async` function.
 
 ```ts
-import { SmartSpectraSDK, breathingMetrics, cardioMetrics, decodeMetrics } from '@smartspectra/node-sdk';
+import { SmartSpectraSDK, CameraSelection, breathingMetrics, cardioMetrics, decodeMetrics } from '@smartspectra/node-sdk';
 
 const sdk = new SmartSpectraSDK({
   apiKey: 'YOUR_API_KEY',
@@ -134,7 +134,7 @@ sdk.on('metrics', (buf, ts) => {
 sdk.on('error', (code, message, retryable) =>
   console.error('SmartSpectra error', code, message, 'retryable=', retryable));
 
-sdk.useCamera();
+sdk.useCamera(CameraSelection.default);
 sdk.start();
 
 console.log('Measuring from the default camera. Press Ctrl+C to stop.');
@@ -147,10 +147,28 @@ process.on('SIGINT', async () => {
 });
 ```
 
-`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.
+`useCamera(CameraSelection.default)` selects the default camera while stopped; capture begins at
+`start()`. You can discover cameras without creating an SDK instance:
+
+```ts
+import { CameraSelection, SmartSpectraSDK } from '@smartspectra/node-sdk';
+
+const cameras = SmartSpectraSDK.availableCameras();
+if (cameras.length > 0) {
+  sdk.useCamera(CameraSelection.byId(cameras[0].id), { width: 1280, height: 720 });
+}
+```
+
+`CameraSelection.default`, `.front`, `.back`, and `.byId(id)` share the camera
+selection contract across SDKs. Explicit requests never fall back. Stop/start/reset
+retain the chosen input. Only macOS currently supports discovery and explicit
+selectors in native Node.js; Linux/Windows report `kConfigurationFailed` for those
+operations and continue to support default capture. See the
+[migration guide](docs/migration-guide.md) and [API reference](docs/api-reference.md#cameraoptions).
+
+Electron renderer capture uses browser-owned streams and `useMediaStream()`;
+browser device IDs cannot be used for native camera selection. Use the
+custom-input path below when your app already owns frame capture.
 
 ## Custom Input Quickstart
 

package/js/camera-selection.js

@@ -0,0 +1,57 @@
+// Copyright (C) 2026 Presage Technologies, Inc.
+// SPDX-License-Identifier: LicenseRef-Proprietary
+'use strict';
+
+const { SmartSpectraErrorCode } = require('./constants');
+
+const CameraSelection = Object.freeze({
+    default: Object.freeze({ kind: 'default' }),
+    front: Object.freeze({ kind: 'front' }),
+    back: Object.freeze({ kind: 'back' }),
+    byId: (id) => Object.freeze({ kind: 'byId', id }),
+});
+
+function configurationError(message) {
+    return Object.assign(new Error(message), {
+        code: SmartSpectraErrorCode.kConfigurationFailed, retryable: false,
+    });
+}
+
+function normalizeCameraSelection(selection) {
+    if (!selection || typeof selection !== 'object') {
+        throw configurationError('useCamera: expected a CameraSelection');
+    }
+    switch (selection.kind) {
+        case 'default': case 'front': case 'back':
+            if (selection.id !== undefined) throw configurationError('Camera ID requires byId selection');
+            return Object.freeze({ kind: selection.kind });
+        case 'byId':
+            if (typeof selection.id !== 'string' || !selection.id || selection.id.includes('\0')) {
+                throw configurationError('Camera ID must be a non-empty string without NUL characters');
+            }
+            return CameraSelection.byId(selection.id);
+        default: throw configurationError('Unknown camera selection kind');
+    }
+}
+
+function normalizeCameraOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw configurationError('useCamera: expected capture options');
+    }
+    if ('deviceIndex' in options) throw configurationError('Use CameraSelection.byId(id) instead of deviceIndex');
+    const copy = {};
+    for (const field of ['width', 'height', 'fps', 'frameTransform']) {
+        const value = options[field] ?? 0;
+        const max = field === 'frameTransform' ? 5 : 2147483647;
+        if (!Number.isInteger(value) || value < 0 || value > max) {
+            throw configurationError(`Invalid camera ${field}`);
+        }
+        copy[field] = value;
+    }
+    if (Boolean(copy.width) !== Boolean(copy.height)) {
+        throw configurationError('Camera width and height must be specified together');
+    }
+    return Object.freeze(copy);
+}
+
+module.exports = { CameraSelection, normalizeCameraSelection, normalizeCameraOptions };

package/js/ffi.js

@@ -27,6 +27,8 @@ const lib = koffi.load(resolveNativeLibrary());
 
 // Opaque session token. C side: `struct smartspectra_session_s*`.
 koffi.opaque('smartspectra_session_t');
+koffi.opaque('smartspectra_camera_list_t');
+koffi.struct('smartspectra_camera_info_t', { id: 'const char *', name: 'const char *', facing: 'int', lens_type: 'int' });
 
 // smartspectra_error_t — keep field order identical to the C struct; koffi
 // computes offsets by declaration order.
@@ -102,13 +104,6 @@ koffi.struct('smartspectra_file_options_t', {
     max_duration_ms:     'int',
     frame_transform:     'int',
 });
-koffi.struct('smartspectra_camera_options_t', {
-    device_index:    'int',
-    width:           'int',
-    height:          'int',
-    fps:             'int',
-    frame_transform: 'int',
-});
 
 // Non-blocking file source: configure + start, returns immediately. Caller
 // blocks via sessionWait when it wants end-of-file.
@@ -117,10 +112,48 @@ const sessionStartFile = lib.func(
     'const char *video_path, const char *timestamps_path, ' +
     'const smartspectra_file_options_t *opts, _Out_ smartspectra_error_t *out_err)');
 
-const sessionStartCamera = lib.func(
+koffi.struct('smartspectra_camera_options_t', {
+    device_index: 'int', width: 'int', height: 'int', fps: 'int', frame_transform: 'int',
+});
+const sessionStartLegacyCamera = lib.func(
     'int smartspectra_session_start_camera(smartspectra_session_t *sess, ' +
     'const smartspectra_camera_options_t *opts, _Out_ smartspectra_error_t *out_err)');
 
+koffi.struct('smartspectra_camera_capture_options_t', {
+    width: 'int', height: 'int', fps: 'int', frame_transform: 'int',
+});
+const sessionStartCamera = lib.func(
+    'int smartspectra_session_start_selected_camera(smartspectra_session_t *sess, ' +
+    'int selection_kind, const char *camera_id, const smartspectra_camera_capture_options_t *opts, ' +
+    '_Out_ smartspectra_error_t *out_err)');
+const discoverCameras = lib.func('int smartspectra_available_cameras(' +
+    '_Out_ smartspectra_camera_list_t **out_list, _Out_ smartspectra_error_t *out_err)');
+const cameraListSize = lib.func('size_t smartspectra_camera_list_size(const smartspectra_camera_list_t *list)');
+const cameraListGet = lib.func('const smartspectra_camera_info_t *smartspectra_camera_list_get(' +
+    'const smartspectra_camera_list_t *list, size_t index)');
+const cameraListFree = lib.func('void smartspectra_camera_list_free(smartspectra_camera_list_t *list)');
+
+function availableCameras() {
+    const out = [null];
+    const error = {};
+    if (discoverCameras(out, error) !== 0) throw makeFfiError(error);
+    const list = out[0];
+    try {
+        const cameras = [];
+        const count = Number(cameraListSize(list));
+        for (let index = 0; index < count; index++) {
+            const camera = koffi.decode(cameraListGet(list, index), 'smartspectra_camera_info_t');
+            cameras.push({ id: camera.id, name: camera.name,
+                facing: camera.facing === 1 ? 'front' : camera.facing === 2 ? 'back' : 'unknown',
+                lensType: camera.lens_type === 1 ? 'wideAngle' : camera.lens_type === 2 ? 'ultraWide' :
+                    camera.lens_type === 3 ? 'telephoto' : 'unknown' });
+        }
+        return cameras;
+    } finally {
+        cameraListFree(list);
+    }
+}
+
 const sessionStartCustom = lib.func(
     'int smartspectra_session_start_custom(smartspectra_session_t *sess, ' +
     'int frame_transform, _Out_ smartspectra_error_t *out_err)');
@@ -343,8 +376,7 @@ class Session {
         this._takeKeepAlive();
     }
 
-    // options (optional): { deviceIndex, width, height, fps, frameTransform }
-    startCamera(options = null) {
+    startLegacyCamera(options = null) {
         this._assertAlive();
         const err = {};
         const opts = options ? {
@@ -354,7 +386,23 @@ class Session {
             fps:             options.fps | 0,
             frame_transform: options.frameTransform | 0,
         } : null;
-        const rc = sessionStartCamera(this._sess, opts, err);
+        const rc = sessionStartLegacyCamera(this._sess, opts, err);
+        if (rc !== 0) throw makeFfiError(err);
+        this._takeKeepAlive();
+    }
+
+    // Selection and capture settings are separate, matching the C++ API.
+    startCamera(selection, options = null) {
+        this._assertAlive();
+        const err = {};
+        const opts = options ? {
+            width:           options.width | 0,
+            height:          options.height | 0,
+            fps:             options.fps | 0,
+            frame_transform: options.frameTransform | 0,
+        } : null;
+        const kind = { default: 0, front: 1, back: 2, byId: 3 }[selection.kind];
+        const rc = sessionStartCamera(this._sess, kind, selection.id ?? null, opts, err);
         if (rc !== 0) throw makeFfiError(err);
         this._takeKeepAlive();
     }
@@ -416,8 +464,18 @@ class Session {
         return sessionGetStatus(this._sess);
     }
 
-    reset() {
+    assertSourceSelectionAllowed() {
+        const status = this.getStatus();
+        if (this._destroyed || this._stopAsyncPromise || (status !== 0 && status !== 1)) {
+            throw Object.assign(new Error('Select an input while stopped'), { code: 1, retryable: false });
+        }
+    }
+
+    reset(requireStopSettled = false) {
         this._assertAlive();
+        if (requireStopSettled && this._stopAsyncPromise) {
+            throw Object.assign(new Error('Await stopAsync before reset'), { code: 1, retryable: false });
+        }
         const err = {};
         const rc = sessionReset(this._sess, err);
         if (rc !== 0) throw makeFfiError(err);
@@ -587,6 +645,7 @@ function ensurePreconfigured() {
 
 module.exports = {
     Session,
+    availableCameras,
     preconfigure,
     ensurePreconfigured,
 };

package/js/index.d.ts

@@ -127,9 +127,36 @@ export interface VideoFileOptions {
     frameTransform?: FrameTransformValue;
 }
 
-/** Camera capture options for useCamera(). */
+/** Camera request resolved at capture startup. Explicit requests never fall back. */
+export type CameraSelection =
+    | Readonly<{ kind: 'default' }>
+    | Readonly<{ kind: 'front' }>
+    | Readonly<{ kind: 'back' }>
+    | Readonly<{ kind: 'byId'; id: string }>;
+
+export declare const CameraSelection: {
+    readonly default: Readonly<{ kind: 'default' }>;
+    readonly front: Readonly<{ kind: 'front' }>;
+    readonly back: Readonly<{ kind: 'back' }>;
+    readonly byId: (id: string) => Readonly<{ kind: 'byId'; id: string }>;
+};
+
+export type CameraFacing = 'front' | 'back' | 'unknown';
+
+/** Best-effort classification. Missing metadata and multi-lens cameras are unknown; independent of digital zoom. */
+export type CameraLensType = 'unknown' | 'wideAngle' | 'ultraWide' | 'telephoto';
+
+/** Discovery snapshot. IDs are opaque and platform-local; rediscover before reuse. */
+export interface CameraInfo {
+    readonly id: string;
+    readonly name: string | null;
+    readonly facing: CameraFacing;
+    readonly lensType: CameraLensType;
+}
+
+/** Capture settings, separate from camera selection. */
 export interface CameraOptions {
-    /** Camera device index; omit/0 = default device. */
+    /** @deprecated Use useCamera(CameraSelection.byId(id), options) instead. */
     deviceIndex?: number;
     /** Capture width in px; omit/0 = SDK default. */
     width?: number;
@@ -163,15 +190,21 @@ export declare class SmartSpectraSDK {
     /** SDK package version. */
     static readonly version: string;
 
+    /** No SDK instance, authentication, or capture required. Throws when discovery is unsupported. */
+    static availableCameras(): CameraInfo[];
+
     constructor(options?: SmartSpectraOptions);
 
-    /** Initialize and begin a custom-input session. */
+    /** Initialize and begin the input configured with useCamera, useCustomInput, or useFile. */
     start(): void;
     /** Request the session to stop. Idempotent. */
     stop(): void;
     /** Async variant of stop() — the native stop blocks until the pipeline drains; prefer this in event-loop-sensitive contexts. */
     stopAsync(): Promise<void>;
-    /** Rebuild the processing pipeline after kError; source must be reconfigured before next start(). */
+    /**
+     * Rebuild after kError. Clears the source unless useCamera(selection, options) opted into retention.
+     * After typed selection, throws kInvalidState while stopAsync() is pending; await it before resetting.
+     */
     reset(): void;
     /**
      * Block until the session reaches a terminal state (idle or error), or the
@@ -211,6 +244,15 @@ export declare class SmartSpectraSDK {
      * pumps frames internally on `start()` — no `sendFrame()` needed. Returns
      * `this` for chaining. Captures in THIS process — for Electron, prefer
      * the renderer SDK's `useMediaStream()`.
+     * Select while stopped; explicit requests never fall back. Selection is
+     * resolved at startup and retained across stop/start/reset. Invalid or busy
+     * requests preserve the previous source. Pass CameraSelection.default for SDK selection.
+     */
+    useCamera(selection: CameraSelection, options?: Omit<CameraOptions, 'deviceIndex'>): this;
+
+    /**
+     * Select a camera by legacy index (default 0). Reset clears the source.
+     * @deprecated Pass an explicit CameraSelection and separate capture options instead.
      */
     useCamera(options?: CameraOptions): this;
 

package/js/index.js

@@ -7,6 +7,7 @@
 
 const {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,
@@ -45,6 +46,7 @@ function decodeMetrics(buf) {
 
 module.exports = {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,

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,
@@ -41,6 +42,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 +68,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 +98,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 +108,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 +144,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 +156,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 +172,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 +201,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 +263,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,6 +324,7 @@ class SmartSpectraSDK {
 
 module.exports = {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.4.0-rc.5",
+  "version": "3.4.0-rc.6",
   "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.6",
+    "@smartspectra/node-sdk-linux-arm64": "3.4.0-rc.6",
+    "@smartspectra/node-sdk-darwin-arm64": "3.4.0-rc.6",
+    "@smartspectra/node-sdk-win32-x64": "3.4.0-rc.6"
   },
   "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": {