Node.js Migration Guide

Replace isDeviceCompatible() with checkDeviceReadiness(). The check returns DeviceReadinessResult with verdict and reason; remove the separate getDeviceCompatibilityResult() call. See Device Readiness for usage and results.

When the frame rate stays too low to measure reliably during a measurement, the session still ends, but the 'error' event now receives SmartSpectraErrorCode.kSustainedLowFrameRate (14) instead of SmartSpectraErrorCode.kProcessingFailed. The message is "SmartSpectra stopped because the frame rate stayed too low to measure reliably." A frame submitted as the session ends is rejected with the same code. retryable is false when the SDK plays a video file, because the same file stops the same way; it is true for cameras and custom input: the host may offer a user-initiated fresh start; do not restart automatically. To check whether a device can sustain measurement before starting, call checkDeviceReadiness().

MetricType.BREATHING_AMPLITUDE, MetricType.APNEA, MetricType.RESPIRATORY_LINE_LENGTH, MetricType.BASELINE, and MetricType.INHALE_EXHALE_RATIO are Unavailable: the SDK does not produce them. They are no longer part of the default request or breathingMetrics, which now contain MetricType.CHEST_BREATHING, MetricType.ABDOMEN_BREATHING, and MetricType.BREATHING_RATE.

Requesting any Unavailable metric makes start() fail with SmartSpectraErrorCode.kConfigurationFailed. The measurement does not begin, and the SDK log names the rejected metrics. checkDeviceReadiness() resolves to a result with verdict 'blocked' for the same configuration.

Apps that use the default request or breathingMetrics need no change and receive the same breathing data as before.

To migrate, remove the Unavailable metrics from requestedMetrics.

The existing useCamera() and useCamera({ deviceIndex: ... }) calls remain available, with deprecation warnings in TypeScript. They retain index-based capture and the previous lifecycle behavior. Opt in to the new API by passing an explicit selection and separate capture options. Camera IDs are opaque and local to the native platform; do not convert old integer indices to strings or reuse browser device IDs.

import { CameraSelection, SmartSpectraSDK } from '@smartspectra/node-sdk';

// Discovery requires no SDK instance, authentication, capture, or permission prompt.
const cameras = SmartSpectraSDK.availableCameras();
const sdk = new SmartSpectraSDK({ apiKey: 'YOUR_API_KEY' });

sdk.useCamera(CameraSelection.default);
sdk.useCamera(CameraSelection.front);
sdk.useCamera(CameraSelection.back);
if (cameras.length > 0) {
  sdk.useCamera(CameraSelection.byId(cameras[0].id), {
    width: 1280, height: 720, fps: 30,
  });
}
sdk.start();

Discovery returns CameraInfo records containing id, nullable name, lensType, and facing ('front', 'back', or 'unknown'). External webcams may report unknown facing. Visibility depends on platform permissions; a snapshot does not reserve a camera or guarantee that later capture will succeed.

lensType is 'wideAngle', 'ultraWide', 'telephoto', or 'unknown'. Classification is best effort; missing metadata and cameras combining multiple lenses report 'unknown'. It does not describe digital zoom or change selection. Use it for picker labels and continue selecting by id.

Native discovery and typed selection are supported on macOS, Linux, and Windows. Default selection follows each platform's native discovery order. Linux uses compatible V4L2 capture nodes in numeric device order. Windows uses the first enumerated camera. Explicit front/back/ID requests never fall back; an unavailable selection fails startup with kInputUnavailable.

Linux populates facing only when the camera driver provides orientation metadata. Windows currently reports unknown facing and lens type, so .front and .back fail with kInputUnavailable; use .byId(id) for a specific Windows camera. Empty IDs, NUL-containing IDs, invalid selectors, and invalid capture options fail selection with kConfigurationFailed.

The deprecated Node.js deviceIndex option and older index-based C ABI remain compatible. Do not pass deviceIndex in the new overload's capture options.

After opting in with useCamera(selection, options), useCamera, useFile, and useCustomInput reject changes during startup, processing, asynchronous stop, and shutdown with kInvalidState. Recover an error state with stop() or reset() before selecting again. A rejected request preserves the previously selected source. The SDK copies camera selection and capture settings, so mutating your original options afterward has no effect.

await sdk.stopAsync();
sdk.useCamera(CameraSelection.back);
sdk.start();

Configure a source before calling start(), as before. For legacy callers, reset() clears the source, so select one again before restarting. After opting in with useCamera(selection, options), stop() and reset() retain the selected source and its settings; call start() to use it again. Calling the deprecated useCamera(options) overload while stopped restores the legacy lifecycle.

After typed selection, reset() throws kInvalidState while a stopAsync() call is pending. Await that stop before resetting. Legacy callers retain the ability to request a reset while an asynchronous stop is pending.

The renderer API continues to use browser capture and useMediaStream(stream). These native selectors apply to the package root API, not the renderer entry point. Keep browser camera IDs and native camera IDs within their respective capture paths.

Usage entitlement checking continues throughout a measurement as before. In v3.4.0, terminal usage failures delivered through the error event use these specific codes:

• SmartSpectraErrorCode.kAuthenticationFailed for rejected credentials
• SmartSpectraErrorCode.kCreditExhausted for an explicit quota denial
• SmartSpectraErrorCode.kNetworkError when entitlement cannot be refreshed in time

The SDK also includes short measurements and the final partial interval before stop() in usage reporting. No public API changes are required.