@smartspectra/node-sdk 3.2.0-rc.6

package/js/resolve-native.js

@@ -0,0 +1,113 @@
+// resolve-native.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Picks the right libsmartspectra_capi.{dll,dylib,so} for the current
+// platform+arch and returns a path that koffi.load() can consume.
+//
+// The native runtime closure (shim + libsmartspectra + OpenCV + Vulkan +
+// graph data) ships in per-platform packages — `@smartspectra/node-sdk-<plat>-<arch>`
+// — declared as regular (HARD) dependencies of the main package. There is no
+// postinstall download and no install script in the published tarball.
+//
+// Why hard deps and not optionalDependencies gated by os/cpu: GitLab's npm
+// registry strips optionalDependencies/os/cpu from the packument, so optional
+// gating never resolves. As hard deps every platform installs on every host,
+// and this resolver picks the one matching process.platform/process.arch. See
+// .session-logs/nodejs-bundle-all-platforms.md and package.json#_nativeRuntime_doc.
+//
+// Resolution order:
+//   1. SMARTSPECTRA_CAPI_PATH env var — full path to the shared library.
+//      The sole dev/override escape hatch (e.g. running against a local
+//      source build, or a custom-bundled closure). In a source checkout the
+//      platform packages are NOT installed, so dev uses this override.
+//   2. The host platform package's root, located via require.resolve. The shim
+//      sits at the package root; the rest of the closure sits beside it with
+//      install_names / RPATHs pre-rewritten so it loads with zero env vars.
+//
+// If neither resolves, we throw a single clear error naming the missing
+// platform package and the SMARTSPECTRA_CAPI_PATH override.
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const LIB_BASENAME = {
+    darwin: 'libsmartspectra_capi.dylib',
+    linux:  'libsmartspectra_capi.so',
+    win32:  'smartspectra_capi.dll',
+};
+
+// `<platform>-<arch>` — matches process.platform / process.arch and the
+// per-platform package suffix.
+function platformArch() {
+    return `${process.platform}-${process.arch}`;
+}
+
+function platformPackageName() {
+    return `@smartspectra/node-sdk-${platformArch()}`;
+}
+
+function resolveNativeLibrary() {
+    const libName = LIB_BASENAME[process.platform];
+    if (!libName) {
+        throw new Error(
+            `@smartspectra/node-sdk: unsupported platform ${process.platform}. ` +
+            `Supported: darwin (macOS), linux, win32 (Windows).`);
+    }
+
+    const override = process.env.SMARTSPECTRA_CAPI_PATH;
+    if (override) {
+        if (!fs.existsSync(override)) {
+            throw new Error(
+                `@smartspectra/node-sdk: SMARTSPECTRA_CAPI_PATH=${override} ` +
+                `points at a file that does not exist.`);
+        }
+        return override;
+    }
+
+    const platformPkg = platformPackageName();
+    let pkgRoot;
+    try {
+        // Resolve the package's own package.json, then take its directory —
+        // require.resolve(pkgName) would need a "main"/"exports" entry the
+        // binary-only package intentionally lacks.
+        pkgRoot = path.dirname(require.resolve(`${platformPkg}/package.json`));
+    } catch (e) {
+        // A corrupt install (broken symlink, permissions) surfaces as something
+        // other than a missing module — don't bury its real cause under the
+        // "not installed" guidance, which would send the user down the wrong path.
+        if (e && e.code !== 'MODULE_NOT_FOUND') {
+            throw new Error(
+                `@smartspectra/node-sdk: failed to resolve the native runtime package ` +
+                `"${platformPkg}" (${e.code || 'unknown error'}): ${e.message}`);
+        }
+        throw new Error(
+            `@smartspectra/node-sdk: the native runtime package "${platformPkg}" is not installed.\n` +
+            `It is a regular dependency of @smartspectra/node-sdk, so this usually means your ` +
+            `platform (${platformArch()}) is unsupported, or the install was incomplete ` +
+            `(e.g. \`npm install --omit=optional\` does NOT skip it, but a partial/offline ` +
+            `install might).\n` +
+            `Supported platforms: darwin-arm64, linux-x64, linux-arm64, win32-x64 ` +
+            `(glibc only — musl/Alpine Linux is not supported).\n` +
+            `To point at a custom build, set SMARTSPECTRA_CAPI_PATH to the shared library path.`);
+    }
+
+    const libPath = path.join(pkgRoot, libName);
+    if (!fs.existsSync(libPath)) {
+        throw new Error(
+            `@smartspectra/node-sdk: "${platformPkg}" is installed but ${libName} is missing from it ` +
+            `(${libPath}). The package may be corrupt — try reinstalling.`);
+    }
+    return libPath;
+}
+
+module.exports = {
+    resolveNativeLibrary,
+    // Exposed for diagnostics and tests.
+    LIB_BASENAME,
+    platformArch,
+    platformPackageName,
+};

package/js/smartspectra.js

@@ -0,0 +1,293 @@
+// smartspectra.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+
+'use strict';
+
+const { Session } = require('./ffi');
+const {
+    ProcessingStatus,
+    PixelFormat,
+    ValidationCode,
+    SmartSpectraErrorCode,
+    FrameTransform,
+    breathingMetrics,
+    cardioMetrics,
+    faceMetrics,
+    micromotionMetrics,
+    edaMetrics,
+    defaultSupportedMetrics,
+} = require('./constants');
+const { version: PACKAGE_VERSION } = require('../package.json');
+
+const SUPPORTED_EVENTS = new Set([
+    'processingStatus',
+    'validationStatus',
+    'metrics',
+    'accumulatedMetrics',
+    'insight',
+    'error',
+    'frameSentThrough',
+    'videoOutput',
+]);
+
+// FrameTransform.kNone — kept here so the constructor doesn't depend on the
+// FrameTransform object declared later.
+const DEFAULT_FRAME_TRANSFORM = 0;
+
+class SmartSpectraSDK {
+    /** SDK package version (matches `package.json#version`). */
+    static get version() { return PACKAGE_VERSION; }
+
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.apiKey]
+     * @param {number[]} [options.requestedMetrics]
+     *   MetricType integer codes. Defaults to `breathingMetrics`.
+     * @param {boolean} [options.enableAccumulatedOutput=false]
+     */
+    constructor(options = {}) {
+        this._options = {
+            apiKey:                  options.apiKey ?? '',
+            requestedMetrics:        options.requestedMetrics,
+            enableAccumulatedOutput: !!options.enableAccumulatedOutput,
+        };
+        this._listeners = new Map();
+        // Pending input source set by useCustomInput()/useCamera()/useFile() and
+        // consumed by start(). Shape: { kind: 'custom'|'camera'|'file', ... }.
+        // The last use* call wins.
+        this._source = null;
+        this._session = null;  // lazy: created on start()
+    }
+
+    // ---------- public API --------------------------------------------------
+
+    /**
+     * Register a callback for a named event. Returns `this` for chaining.
+     * One listener per event; re-registration replaces.
+     */
+    on(event, callback) {
+        if (typeof event !== 'string' || typeof callback !== 'function') {
+            throw new TypeError('on(event: string, callback: Function)');
+        }
+        if (!SUPPORTED_EVENTS.has(event)) {
+            throw new RangeError(`on(): unsupported event ${event}`);
+        }
+        this._listeners.set(event, callback);
+        return this;
+    }
+
+    /**
+     * Select the custom frame-push input source (you push frames via
+     * sendFrame() after start()). Returns `this` for chaining.
+     *
+     * @param {number} [frameTransform=FrameTransform.kNone]
+     *   Spatial transform applied to every pushed frame.
+     */
+    useCustomInput(frameTransform = DEFAULT_FRAME_TRANSFORM) {
+        this._source = { kind: 'custom', frameTransform: frameTransform | 0 };
+        return this;
+    }
+
+    /**
+     * Select a live camera as the input source. The SDK opens the camera and
+     * pumps frames internally on start() — no sendFrame() needed. Returns
+     * `this` for chaining.
+     *
+     * @param {Object} [options] { deviceIndex?, width?, height?, fps?, frameTransform? }
+     *
+     * 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 };
+        return this;
+    }
+
+    /**
+     * Select a pre-recorded video file as the input source. start() begins
+     * playback (non-blocking — it runs on SDK worker threads); use
+     * waitUntilComplete() or watch the `'processingStatus'` event for the idle
+     * transition to detect end-of-file. Returns `this` for chaining.
+     *
+     * @param {string} videoPath
+     * @param {Object} [options]
+     *   { timestampsPath?, interframeDelayMs?, startOffsetMs?, maxDurationMs?, frameTransform? }
+     */
+    useFile(videoPath, options = null) {
+        if (typeof videoPath !== 'string' || !videoPath) {
+            throw new TypeError('useFile: videoPath must be a non-empty string');
+        }
+        this._source = { kind: 'file', videoPath, options };
+        return this;
+    }
+
+    /**
+     * 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.
+     */
+    start() {
+        const source = this._source;
+        if (!source) {
+            throw new Error(
+                'start(): no input source configured. Call useCustomInput(), ' +
+                'useCamera(), or useFile() first.');
+        }
+        this._ensureSession();
+        switch (source.kind) {
+            case 'custom':
+                this._session.startCustom(source.frameTransform);
+                break;
+            case 'camera':
+                this._session.startCamera(source.options);
+                break;
+            case 'file':
+                this._session.startFile(
+                    source.videoPath,
+                    (source.options && source.options.timestampsPath) || null,
+                    source.options);
+                break;
+        }
+    }
+
+    stop() {
+        if (!this._session) return;
+        this._session.stop();
+    }
+
+    /**
+     * Async variant of `stop()`. The underlying C++ stop blocks until the
+     * processing pipeline drains — can take multiple seconds. Prefer this in
+     * event-loop-sensitive contexts (e.g. the Electron main process serving
+     * IPC) so the runtime stays responsive.
+     */
+    stopAsync() {
+        if (!this._session) return Promise.resolve();
+        return this._session.stopAsync();
+    }
+
+    /**
+     * 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.
+     */
+    reset() {
+        if (!this._session) return;
+        this._session.reset();
+        this._source = null;
+    }
+
+    /**
+     * Block until the session reaches a terminal state (idle or error), or the
+     * timeout elapses. Returns true if the session settled, false on timeout.
+     * `timeoutMs <= 0` (the default) waits indefinitely. With no active session
+     * there is nothing to wait for, so it returns true immediately.
+     *
+     * Useful after useFile() + start() to block until end-of-file.
+     */
+    waitUntilComplete(timeoutMs = 0) {
+        if (!this._session) return true;
+        return this._session.wait(timeoutMs);
+    }
+
+    /**
+     * Dispatch an on-demand insight prompt against the running session.
+     * Returns the request id; the matching Insight response is delivered
+     * asynchronously through the `'insight'` event with the same id.
+     */
+    requestInsight(text) {
+        if (typeof text !== 'string') {
+            throw new TypeError('requestInsight: text must be a string');
+        }
+        this._ensureSession();
+        return this._session.requestInsight(text);
+    }
+
+    /** Current ProcessingStatus integer value (kUninitialized=0..kError=5). */
+    get processingStatus() {
+        return this._session ? this._session.getStatus() : 0;
+    }
+
+    /**
+     * Push a raw video frame. Requires useCustomInput() + start() first.
+     * Returns true on success; throws on input-validation or SDK-level
+     * failure.
+     */
+    sendFrame(buffer, width, height, strideBytes, pixelFormat, timestampUs) {
+        if (!this._session || !this._source || this._source.kind !== 'custom') {
+            throw new Error('sendFrame(): call useCustomInput() + start() first');
+        }
+        return this._session.sendFrame(
+            buffer, width, height, strideBytes, pixelFormat, timestampUs);
+    }
+
+    /**
+     * Tear down the session. Idempotent. Always call on shutdown so the SDK
+     * worker threads join cleanly before the koffi trampolines are released.
+     * Returns a promise that resolves once native teardown completes (a
+     * stopAsync() in flight defers it); await it before standing up a
+     * replacement session, since SDK state is process-global.
+     */
+    destroy() {
+        if (!this._session) return Promise.resolve();
+        const teardown = this._session.destroy();
+        this._session = null;
+        this._source = null;
+        return teardown;
+    }
+
+    // ---------- internal ----------------------------------------------------
+
+    _ensureSession() {
+        if (this._session) return;
+        // Listeners may be added/replaced after start(), so the lookup
+        // happens at emit time rather than capture time.
+        this._session = new Session(this._options, {
+            onStatus: (status) => this._emit('processingStatus', status),
+            onValidation: (code, hint, ts) =>
+                this._emit('validationStatus', code, Number(ts), hint),
+            onMetrics: (buf, ts) => this._emit('metrics', buf, Number(ts)),
+            onError: (code, message, retryable) =>
+                this._emit('error', code, message, retryable),
+            onFrame: (sent, ts) =>
+                this._emit('frameSentThrough', sent, Number(ts)),
+            onAccumulatedMetrics: (buf, ts) =>
+                this._emit('accumulatedMetrics', buf, Number(ts)),
+            onInsight: (buf, requestId) =>
+                this._emit('insight', buf, requestId),
+            onVideoOutput: (buf, width, height, stride, pixelFormat, ts) =>
+                this._emit('videoOutput', buf, width, height, stride, pixelFormat, Number(ts)),
+        });
+    }
+
+    _emit(event, ...args) {
+        const cb = this._listeners.get(event);
+        if (!cb) return;
+        try {
+            cb(...args);
+        } catch (e) {
+            // Isolate listener exceptions so a user-code throw on a
+            // worker-thread callback doesn't tear down the SDK.
+            console.error(`SmartSpectraSDK: listener for '${event}' threw:`, e);
+        }
+    }
+}
+
+module.exports = {
+    SmartSpectraSDK,
+    ProcessingStatus,
+    PixelFormat,
+    ValidationCode,
+    SmartSpectraErrorCode,
+    FrameTransform,
+    breathingMetrics,
+    cardioMetrics,
+    faceMetrics,
+    micromotionMetrics,
+    edaMetrics,
+    defaultSupportedMetrics,
+};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@smartspectra/node-sdk",
+  "version": "3.2.0-rc.6",
+  "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
+  "author": "Presage Technologies, Inc.",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "js/index.js",
+  "types": "js/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./js/index.d.ts",
+      "default": "./js/index.js"
+    },
+    "./main": {
+      "types": "./js/main/index.d.ts",
+      "default": "./js/main/index.js"
+    },
+    "./preload": "./js/preload/index.js",
+    "./renderer": {
+      "types": "./js/renderer/index.d.ts",
+      "default": "./js/renderer/index.js"
+    },
+    "./messages": {
+      "types": "./js/messages/index.d.ts",
+      "default": "./js/messages/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "js/**/*.js",
+    "js/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepare": "node scripts/gen-proto.cjs",
+    "build:proto": "node scripts/gen-proto.cjs",
+    "test": "node test/smoke.js",
+    "test:models-allowlist": "node test/models-allowlist.js"
+  },
+  "keywords": [
+    "smartspectra",
+    "vitals",
+    "physiology",
+    "electron",
+    "nodejs",
+    "ffi",
+    "koffi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Presage-Security/SmartSpectra.git"
+  },
+  "homepage": "https://smartspectra.presagetech.com/",
+  "bugs": {
+    "url": "https://github.com/Presage-Security/SmartSpectra/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "_nativeRuntime_doc": "Per-platform native packages (@smartspectra/node-sdk-<plat>-<arch>) are injected into dependencies at publish time (absent here so source installs don't fetch them). Why hard deps, not optionalDependencies: see js/resolve-native.js.",
+  "dependencies": {
+    "koffi": "^2.10.0",
+    "protobufjs": "^7.5.0",
+    "@smartspectra/node-sdk-linux-x64": "3.2.0-rc.6",
+    "@smartspectra/node-sdk-linux-arm64": "3.2.0-rc.6",
+    "@smartspectra/node-sdk-darwin-arm64": "3.2.0-rc.6",
+    "@smartspectra/node-sdk-win32-x64": "3.2.0-rc.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "protobufjs-cli": "^1.1.3"
+  },
+  "_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 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.6.",
+  "overrides": {
+    "tmp": "0.2.6"
+  }
+}