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

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,30 @@ 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. Native Node.js supports camera discovery and typed
+selection on macOS, Linux, and Windows. Linux and Windows cameras may report
+unknown facing or lens type, so select those cameras by discovered ID. On
+Windows, `.front` and `.back` fail with `kInputUnavailable` because facing is
+not reported. 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/constants.js

@@ -3,9 +3,9 @@
 //
 // SPDX-License-Identifier: LicenseRef-Proprietary
 //
-// Pure-value exports — public enums and metric bundles. No Node-only
-// dependencies so this module can be bundled into a browser renderer
-// without dragging in koffi, fs, or path.
+// Public enums and metric bundles. No Node-only dependencies, so this module
+// can be bundled into a browser renderer without dragging in koffi, fs, or
+// path. MetricType is sourced from the generated protobuf module below.
 //
 // Integer values must match the SmartSpectra C++ headers and
 // metric_types.proto wire values; stable across SDK versions.
@@ -14,6 +14,8 @@
 
 'use strict';
 
+const generatedMetricType = require('./messages/generated').presage.smartspectra.MetricType;
+
 const ProcessingStatus = Object.freeze({
     kUninitialized: 0,
     kIdle:          1,
@@ -91,6 +93,12 @@ const FrameTransform = Object.freeze({
     kMirrorVertical:   5,
 });
 
+// protobufjs enums include reverse numeric keys. Keep the existing public
+// name-to-number-only shape while deriving every value from metric_types.proto.
+const MetricType = Object.freeze(Object.fromEntries(
+    Object.entries(generatedMetricType).filter(([name]) => Number.isNaN(Number(name))),
+));
+
 // MetricType integer codes grouped by measurement type. Spread into
 // `requestedMetrics`; omitting `requestedMetrics` is equivalent to passing
 // `breathingMetrics`.
@@ -138,6 +146,7 @@ module.exports = {
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,

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

@@ -90,6 +90,31 @@ export declare const FrameTransform: {
 };
 export type FrameTransformValue = typeof FrameTransform[keyof typeof FrameTransform];
 
+/** MetricType integer codes accepted by `requestedMetrics`. Runtime values are generated from protobuf. */
+export declare const MetricType: {
+    readonly CHEST_BREATHING:         0;
+    readonly ABDOMEN_BREATHING:       1;
+    readonly BREATHING_RATE:          2;
+    readonly BREATHING_AMPLITUDE:     3;
+    readonly APNEA:                   4;
+    readonly RESPIRATORY_LINE_LENGTH: 5;
+    readonly BASELINE:                6;
+    readonly INHALE_EXHALE_RATIO:     7;
+    readonly GLUTES_MICROMOTION:      8;
+    readonly KNEES_MICROMOTION:       9;
+    readonly EDA_TRACE:               10;
+    readonly FACE_LANDMARKS:          11;
+    readonly BLINKING:                12;
+    readonly TALKING:                 13;
+    readonly EXPRESSIONS:             14;
+    readonly PULSE_RATE:              15;
+    readonly ARTERIAL_PRESSURE_TRACE: 16;
+    readonly HRV:                     17;
+    readonly PULSE_RATE_STRICT:       18;
+    readonly BREATHING_RATE_STRICT:   19;
+};
+export type MetricTypeValue = typeof MetricType[keyof typeof MetricType];
+
 /** Options passed to the SmartSpectra constructor. */
 export interface SmartSpectraOptions {
     /** API key for server-validated auth. */
@@ -127,9 +152,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 +215,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 +269,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;
 
@@ -278,16 +345,6 @@ export declare class SmartSpectraSDK {
  * MetricType integer codes grouped by measurement type. Spread into
  * `requestedMetrics`; omitting it is equivalent to passing
  * `breathingMetrics`.
- *
- * @example
- * ```ts
- * import { SmartSpectra, breathingMetrics, cardioMetrics } from '@smartspectra/node-sdk';
- *
- * const ss = new SmartSpectra({
- *     apiKey: 'YOUR_KEY',
- *     requestedMetrics: [...breathingMetrics, ...cardioMetrics],
- * });
- * ```
  */
 export declare const breathingMetrics:        readonly number[];
 export declare const cardioMetrics:           readonly number[];

package/js/index.js

@@ -7,12 +7,14 @@
 
 const {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,
@@ -45,12 +47,14 @@ function decodeMetrics(buf) {
 
 module.exports = {
     SmartSpectraSDK,
+    CameraSelection,
     SmartSpectraLogLevel,
     ProcessingStatus,
     PixelFormat,
     ValidationCode,
     SmartSpectraErrorCode,
     FrameTransform,
+    MetricType,
     breathingMetrics,
     cardioMetrics,
     faceMetrics,