@smartspectra/node-sdk 3.2.0-rc.6

package/js/messages/index.d.ts

@@ -0,0 +1,27 @@
+// js/messages/index.d.ts
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// TypeScript declarations for `@smartspectra/node-sdk/messages`. The
+// generated namespace tree (with every nested type — Breathing, Cardio,
+// Face, Measurement, etc.) lives in `./generated.d.ts`, emitted by pbts
+// alongside `generated.js`. This file is the hand-written facade that
+// names the public exports.
+
+import { presage as generatedPresage } from './generated';
+
+/** The full `presage.*` namespace as generated by pbjs / pbts. */
+export const presage: typeof generatedPresage;
+
+/** Convenience alias for `presage.smartspectra.Metrics`. */
+export const Metrics: typeof generatedPresage.smartspectra.Metrics;
+
+/**
+ * Decode a Metrics protobuf buffer emitted by the SDK's `metrics` or
+ * `accumulatedMetrics` events. Accepts Node's `Buffer`, browser-side
+ * `Uint8Array`, or raw `ArrayBuffer`.
+ */
+export function decodeMetrics(
+    buf: Uint8Array | ArrayBuffer,
+): generatedPresage.smartspectra.Metrics;

package/js/messages/index.js

@@ -0,0 +1,67 @@
+// js/messages/index.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Public protobuf surface for `@smartspectra/node-sdk`. Ships the
+// generated message classes so host apps don't have to compile their
+// own protobuf module against the SDK's `.proto` files.
+//
+// Usage:
+//   const { Metrics, decodeMetrics, presage } = require('@smartspectra/node-sdk/messages');
+//   const m = decodeMetrics(buf);            // buf: Buffer | Uint8Array | ArrayBuffer
+//   console.log(m.cardio?.pulseRate);
+//   // Nested types are reachable via the namespace too:
+//   const breathing = presage.smartspectra.Breathing;
+//
+// This module purposely avoids `require('../smartspectra')` /
+// `require('../ffi')` so it stays pulled-in cleanly by browser-side
+// bundlers (e.g. esbuild for an Electron renderer). The koffi loader and
+// the C ABI shim live under the package's main entry only.
+
+'use strict';
+
+const $root = require('./generated');
+
+// pbjs --wrap commonjs emits `module.exports = $root`, where `$root` is
+// the populated `protobuf.roots["default"]` namespace. Pull the `presage`
+// branch off it so we can re-export the full tree without forcing callers
+// to traverse `$root.presage.smartspectra…`.
+const { presage } = $root;
+const Metrics = presage.smartspectra.Metrics;
+
+/**
+ * Coerce a buffer-shaped value into the `Uint8Array` that
+ * `Metrics.decode()` expects. Accepts the three shapes consumers
+ * realistically hand us: a Node.js `Buffer` (main process), a plain
+ * `Uint8Array` (renderer, from the IPC bridge's `ArrayBuffer` payload),
+ * or a bare `ArrayBuffer` (raw transferable, no view).
+ *
+ * Buffers are already Uint8Array subclasses so they pass through
+ * untouched; the Uint8Array branch also no-ops; the ArrayBuffer branch
+ * wraps without copying.
+ */
+function toUint8(buf) {
+    if (buf instanceof Uint8Array) return buf;
+    if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
+    throw new TypeError(
+        '@smartspectra/node-sdk/messages: decodeMetrics expected ' +
+        'Buffer | Uint8Array | ArrayBuffer, got ' + Object.prototype.toString.call(buf));
+}
+
+/**
+ * Decode a Metrics protobuf buffer emitted by the SDK's `metrics` or
+ * `accumulatedMetrics` events. Returns the decoded message object with
+ * the full namespace shape (e.g. `out.cardio.pulseRate[i].timestamp`).
+ *
+ * Throws on malformed input (re-raised from protobufjs).
+ */
+function decodeMetrics(buf) {
+    return Metrics.decode(toUint8(buf));
+}
+
+module.exports = {
+    Metrics,
+    decodeMetrics,
+    presage,
+};

package/js/preload/index.js

@@ -0,0 +1,116 @@
+// js/preload/index.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Preload bridge for `@smartspectra/node-sdk/renderer`. Run inside the
+// preload script of any BrowserWindow that hosts a renderer using the SDK.
+//
+// Apps that already have a preload script can require this file from there;
+// apps without a preload script can point `webPreferences.preload` directly
+// at this file via `require.resolve('@smartspectra/node-sdk/preload')`.
+//
+// The bridge owns the MessagePort in the preload context and exposes
+// `attach()` / `postMessage()` / `onMessage()` / `close()` to the renderer.
+// Keeping the port out of the renderer's main world avoids edge cases in
+// cross-context MessagePort proxying through contextBridge.
+
+'use strict';
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+const ATTACH_CHANNEL = 'smartspectra:attach';
+
+// Preload-context state. One port per preload instance is enough — the
+// renderer-side SmartSpectraSDK is a singleton-per-BrowserWindow in
+// practice.
+let port = null;
+let messageListener = null;
+
+// Diagnostic logging — opt-in via the same env var the main-process glue
+// uses. Logs go to the renderer DevTools console (preload shares the
+// renderer's console). Frame messages are logged only on first send and
+// every 60 sends after that, to avoid swamping the console.
+const DIAGNOSTICS = process.env.SMARTSPECTRA_DIAGNOSTICS === '1';
+let postsByKind = Object.create(null);
+function diagLogSend(kind) {
+    if (!DIAGNOSTICS) return;
+    postsByKind[kind] = (postsByKind[kind] || 0) + 1;
+    const count = postsByKind[kind];
+    if (kind === 'frame') {
+        if (count === 1 || count % 60 === 0) {
+            console.log(`[smartspectra/preload] -> frame #${count}`);
+        }
+    } else {
+        console.log(`[smartspectra/preload] -> ${kind}`);
+    }
+}
+
+const onPortMessage = (event) => {
+    if (DIAGNOSTICS) {
+        const kind = event.data && event.data.kind;
+        console.log(`[smartspectra/preload] <- ${kind || '?'}`);
+    }
+    if (messageListener) messageListener(event.data);
+};
+
+contextBridge.exposeInMainWorld('__smartspectraBridge', {
+    /**
+     * Mirror of SMARTSPECTRA_DIAGNOSTICS for the renderer module, which is
+     * context-isolated and cannot read process.env itself.
+     */
+    diagnostics: DIAGNOSTICS,
+
+    /**
+     * Open the IPC channel to the main process. Creates a MessageChannel
+     * (port pair) in the preload context, ships port2 to main via
+     * ipcRenderer.postMessage (which natively transfers MessagePorts), and
+     * retains port1 here.
+     */
+    attach() {
+        if (port) return;  // idempotent — second attach() is a no-op
+        const channel = new MessageChannel();
+        port = channel.port1;
+        port.onmessage = onPortMessage;
+        ipcRenderer.postMessage(ATTACH_CHANNEL, null, [channel.port2]);
+        port.start();
+    },
+
+    /**
+     * Forward a message to the main process via structured clone. Electron's
+     * MessagePortMain silently drops messages whose transfer list contains an
+     * ArrayBuffer — `port.postMessage(msg, [ab])` succeeds on the renderer
+     * side but never fires `port.on('message')` on the main side — so we
+     * always clone. The clone costs one ~3.6 MB copy per 720p frame, which is
+     * negligible at 30 fps.
+     */
+    postMessage(message) {
+        if (!port) throw new Error('@smartspectra/node-sdk/preload: postMessage before attach()');
+        try {
+            port.postMessage(message);
+        } catch (err) {
+            // Surface the failure to DevTools so it doesn't disappear into
+            // contextBridge's promise wrapper.
+            console.error(
+                `[smartspectra/preload] port.postMessage failed for ${message && message.kind}:`,
+                err);
+            throw err;
+        }
+        diagLogSend(message && message.kind);
+    },
+
+    /**
+     * Register the callback that receives main-process messages. Replacing
+     * an existing callback is supported (only the most recent registration
+     * is invoked).
+     */
+    onMessage(callback) {
+        messageListener = typeof callback === 'function' ? callback : null;
+    },
+
+    /** Close the port and clear the listener. Idempotent. */
+    close() {
+        if (port) { try { port.close(); } catch { /* already closed */ } port = null; }
+        messageListener = null;
+    },
+});

package/js/renderer/index.d.ts

@@ -0,0 +1,154 @@
+// js/renderer/index.d.ts
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+
+import type {
+    ProcessingStatusValue,
+    ValidationCodeValue,
+    SmartSpectraErrorCodeValue,
+    SmartSpectraOptions,
+} from '../../js/index';
+
+// Re-export the public value constants and matching type aliases so the
+// renderer-side consumer can import everything from one entry point.
+export {
+    ProcessingStatus,
+    PixelFormat,
+    ValidationCode,
+    SmartSpectraErrorCode,
+    FrameTransform,
+    breathingMetrics,
+    cardioMetrics,
+    faceMetrics,
+    micromotionMetrics,
+    edaMetrics,
+    defaultSupportedMetrics,
+} from '../../js/index';
+export type {
+    ProcessingStatusValue,
+    PixelFormatValue,
+    ValidationCodeValue,
+    SmartSpectraErrorCodeValue,
+    FrameTransformValue,
+    SmartSpectraOptions,
+} from '../../js/index';
+
+/**
+ * Renderer constructor options: the shared SDK options plus a renderer-only
+ * IPC ack timeout. (`sendTimeoutMs` has no meaning for the main-process SDK,
+ * which doesn't go through the preload bridge.)
+ */
+export interface RendererSmartSpectraOptions extends SmartSpectraOptions {
+    /**
+     * Per-call timeout (ms) for renderer→main IPC roundtrips
+     * (start/stop/reset/requestInsight/configure). If the main process
+     * crashes or stalls, the pending call rejects with an `Error` whose
+     * `code` is `'SMARTSPECTRA_IPC_TIMEOUT'` instead of hanging the UI
+     * forever. Defaults to 30000; set to 0 to disable.
+     */
+    sendTimeoutMs?: number;
+}
+
+/**
+ * Renderer-side `SmartSpectraSDK` for Electron applications. By default
+ * the SDK acquires the host's front-facing camera at 1280x720 / 30 fps,
+ * locks AE/AWB/focus once the signal pipeline reports Running, and emits
+ * the active `MediaStream` through `'streamAvailable'` so the host can
+ * show a live preview. Host apps that need finer control (custom
+ * resolution, virtual cameras, `<canvas>.captureStream()`, etc.) call
+ * `useMediaStream()` before `start()` to override the default.
+ *
+ * Requires the preload script to expose the bridge — set
+ * `webPreferences.preload = require.resolve('@smartspectra/node-sdk/preload')`
+ * on the BrowserWindow, and call
+ * `bindSmartSpectraIpc(window)` from the main process.
+ *
+ * @example
+ * ```ts
+ * import { SmartSpectraSDK } from '@smartspectra/node-sdk/renderer';
+ * import { breathingMetrics, cardioMetrics } from '@smartspectra/node-sdk';
+ *
+ * const sdk = new SmartSpectraSDK({
+ *     apiKey: 'YOUR_KEY',
+ *     requestedMetrics: [...breathingMetrics, ...cardioMetrics],
+ * });
+ *
+ * sdk.on('streamAvailable', (stream) => {
+ *     document.querySelector('video').srcObject = stream;
+ * });
+ * sdk.on('metrics', (buf, ts) => { ... });
+ *
+ * await sdk.start();  // SDK acquires the camera + emits 'streamAvailable'
+ * ```
+ */
+export declare class SmartSpectraSDK {
+    /** SDK package version. */
+    static readonly version: string;
+
+    constructor(options?: RendererSmartSpectraOptions);
+
+    /** Current ProcessingStatus integer value (read-only). */
+    readonly processingStatus: ProcessingStatusValue;
+
+    /**
+     * Override the default camera with a host-supplied `MediaStream` from
+     * `navigator.mediaDevices.getUserMedia`, `desktopCapturer`, a
+     * `<canvas>.captureStream()`, etc. Optional — if not called, `start()`
+     * acquires its own MediaStream with sensible defaults and emits it via
+     * the `'streamAvailable'` event. When the host supplies the stream
+     * the host also owns its lifecycle; the SDK never stops the original
+     * tracks.
+     */
+    useMediaStream(stream: MediaStream): this;
+
+    /**
+     * Begin processing. If no stream was provided via `useMediaStream()`,
+     * the SDK acquires the default front-facing camera (1280x720 / 30 fps)
+     * and emits it through `'streamAvailable'` so the host can attach a
+     * preview. Resolves once the main-process SDK is running.
+     */
+    start(): Promise<void>;
+
+    /**
+     * Stop processing. Resolves once the main-process SDK reports idle.
+     * Releases any SDK-acquired camera; host-supplied streams are left
+     * untouched.
+     */
+    stop(): Promise<void>;
+
+    /**
+     * Rebuild the processing pipeline after a kError state. Releases any
+     * SDK-acquired camera so the next `start()` re-acquires from scratch.
+     */
+    reset(): Promise<void>;
+
+    /**
+     * Dispatch an on-demand insight prompt. Resolves with the request id
+     * assigned to it; the matching response arrives via the `'insight'`
+     * event with the same id.
+     */
+    requestInsight(text: string): Promise<number>;
+
+    /**
+     * Tear down renderer-side resources and instruct the main process to
+     * destroy its SDK instance. Idempotent.
+     */
+    destroy(): void;
+
+    on(event: 'processingStatus',   callback: (status: ProcessingStatusValue) => void): this;
+    on(event: 'validationStatus',   callback: (code: ValidationCodeValue, timestampUs: number, hint: string) => void): this;
+    on(event: 'metrics',            callback: (buf: Uint8Array, timestampUs: number) => void): this;
+    on(event: 'accumulatedMetrics', callback: (buf: Uint8Array, timestampUs: number) => void): this;
+    on(event: 'insight',            callback: (buf: Uint8Array, requestId: number) => void): this;
+    on(event: 'frameSentThrough',   callback: (sent: boolean, timestampUs: number) => void): this;
+    on(event: 'error',              callback: (code: SmartSpectraErrorCodeValue, message: string, retryable: boolean) => void): this;
+    /**
+     * Fires once the SDK has acquired (or re-acquired, after a Stop) the
+     * default `MediaStream`. Host apps attach this stream to their
+     * preview `<video>` element. Not fired when the host supplies its
+     * own stream via `useMediaStream()` — the host already owns that
+     * reference.
+     */
+    on(event: 'streamAvailable',    callback: (stream: MediaStream) => void): this;
+}