@smartspectra/node-sdk 3.2.0-rc.6

package/js/index.d.ts

@@ -0,0 +1,282 @@
+// index.d.ts
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+
+/** Processing lifecycle status. Integer values are stable across SDK versions. */
+export declare const ProcessingStatus: {
+    readonly kUninitialized: 0;
+    readonly kIdle: 1;
+    readonly kStarting: 2;
+    readonly kRunning: 3;
+    readonly kStopping: 4;
+    readonly kError: 5;
+};
+export type ProcessingStatusValue = typeof ProcessingStatus[keyof typeof ProcessingStatus];
+
+/** Pixel format of a raw frame buffer passed to sendFrame(). */
+export declare const PixelFormat: {
+    readonly kRGB:  0;
+    readonly kBGR:  1;
+    readonly kRGBA: 2;
+    readonly kBGRA: 3;
+    readonly kNV12: 4;
+    readonly kNV21: 5;
+    readonly kYUYV: 6;
+};
+export type PixelFormatValue = typeof PixelFormat[keyof typeof PixelFormat];
+
+/** Measurement-readiness codes delivered via the 'validationStatus' event. */
+export declare const ValidationCode: {
+    readonly kOk:                 0;
+    readonly kNoFaceFound:        1;
+    readonly kMultipleFacesFound: 2;
+    readonly kFaceNotCentered:    3;
+    readonly kFaceSizeOutOfRange: 4;
+    readonly kTooDark:            5;
+    readonly kTooBright:          6;
+    readonly kChestNotVisible:    7;
+    readonly kCameraTuning:       10;
+    readonly kFrameRateTooLow:    11;
+};
+export type ValidationCodeValue = typeof ValidationCode[keyof typeof ValidationCode];
+
+/** Error codes on errors thrown by lifecycle methods and delivered via the 'error' event. */
+export declare const SmartSpectraErrorCode: {
+    readonly kOk:                    0;
+    readonly kInvalidState:          1;
+    readonly kAuthenticationFailed:  2;
+    readonly kConfigurationFailed:   3;
+    readonly kCreditExhausted:       4;
+    readonly kNetworkError:          5;
+    readonly kServerError:           6;
+    readonly kInputUnavailable:      7;
+    readonly kProcessingFailed:      8;
+    readonly kFrameConversionFailed: 9;
+    readonly kNonMonotonicTimestamp: 10;
+    readonly kTimestampGap:          11;
+};
+export type SmartSpectraErrorCodeValue = typeof SmartSpectraErrorCode[keyof typeof SmartSpectraErrorCode];
+
+/** Frame transform applied by the SDK to every pushed frame. */
+export declare const FrameTransform: {
+    readonly kNone:             0;
+    readonly kRotate90CW:       1;
+    readonly kRotate90CCW:      2;
+    readonly kRotate180:        3;
+    readonly kMirrorHorizontal: 4;
+    readonly kMirrorVertical:   5;
+};
+export type FrameTransformValue = typeof FrameTransform[keyof typeof FrameTransform];
+
+/** Options passed to the SmartSpectra constructor. */
+export interface SmartSpectraOptions {
+    /** API key for server-validated auth. */
+    apiKey?: string;
+
+    /**
+     * MetricType integer codes. Defaults to `breathingMetrics` when omitted.
+     */
+    requestedMetrics?: number[];
+
+    /** Also emit an accumulated metrics packet at the end of each session. */
+    enableAccumulatedOutput?: boolean;
+}
+
+/** Playback options for useFile(). */
+export interface VideoFileOptions {
+    /** Path to a per-frame timestamps file (one timestamp per line). */
+    timestampsPath?: string | null;
+    /** Throttle between frames in ms; omit/0 = as fast as possible. */
+    interframeDelayMs?: number;
+    /** Seek this far into the file before playback (ms); omit/0 = start. */
+    startOffsetMs?: number;
+    /** Stop after this much content (ms); omit/0 = no limit. */
+    maxDurationMs?: number;
+    /** Spatial transform applied to every frame. */
+    frameTransform?: FrameTransformValue;
+}
+
+/** Camera capture options for useCamera(). */
+export interface CameraOptions {
+    /** Camera device index; omit/0 = default device. */
+    deviceIndex?: number;
+    /** Capture width in px; omit/0 = SDK default. */
+    width?: number;
+    /** Capture height in px; omit/0 = SDK default. */
+    height?: number;
+    /** Capture frame rate; omit/0 = SDK default. */
+    fps?: number;
+    /** Spatial transform applied to every frame. */
+    frameTransform?: FrameTransformValue;
+}
+
+/**
+ * Vitals measurement entry point. Owns one processing pipeline and surfaces
+ * lifecycle events via `on()`. Lifecycle methods throw a JS `Error` on
+ * failure with numeric `code` (a `SmartSpectraErrorCode` value), `message`,
+ * and boolean `retryable` properties.
+ *
+ * @example
+ * ```ts
+ * import { SmartSpectraSDK, PixelFormat, decodeMetrics } from '@smartspectra/node-sdk';
+ *
+ * const sdk = new SmartSpectraSDK({ apiKey: 'YOUR_KEY' });
+ * sdk.on('metrics', (buf, ts) => console.log(decodeMetrics(buf)));
+ * sdk.useCustomInput();
+ * sdk.start();
+ * sdk.sendFrame(rgbBuf, width, height, stride, PixelFormat.kRGB, timestampUs);
+ * await sdk.destroy();
+ * ```
+ */
+export declare class SmartSpectraSDK {
+    /** SDK package version. */
+    static readonly version: string;
+
+    constructor(options?: SmartSpectraOptions);
+
+    /** Initialize and begin a custom-input session. */
+    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(). */
+    reset(): void;
+    /**
+     * 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. Use after
+     * `useFile()` + `start()` to block until end-of-file.
+     */
+    waitUntilComplete(timeoutMs?: number): boolean;
+    /**
+     * Tear down the session. Idempotent. Await before constructing a
+     * replacement session when teardown ordering matters, since native SDK
+     * state is process-global.
+     */
+    destroy(): Promise<void>;
+
+    /**
+     * Dispatch an on-demand insight prompt; returns the request id. The
+     * matching Insight response arrives asynchronously through the
+     * `'insight'` event with the same id.
+     */
+    requestInsight(text: string): number;
+
+    /** Current ProcessingStatus integer value. */
+    readonly processingStatus: ProcessingStatusValue;
+
+    /**
+     * Select the custom frame-push input source (push frames via
+     * `sendFrame()` after `start()`). Returns `this` for chaining; call
+     * before `start()`.
+     *
+     * @param frameTransform Defaults to `FrameTransform.kNone`.
+     */
+    useCustomInput(frameTransform?: FrameTransformValue): 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. Captures in THIS process — for Electron, prefer
+     * the renderer SDK's `useMediaStream()`.
+     */
+    useCamera(options?: CameraOptions): this;
+
+    /**
+     * Select a pre-recorded video file as the input source. `start()` begins
+     * playback (non-blocking, on SDK worker threads); use
+     * `waitUntilComplete()` or watch `'processingStatus'` for the idle
+     * transition to detect
+     * end-of-file. Returns `this` for chaining.
+     */
+    useFile(videoPath: string, options?: VideoFileOptions): this;
+
+    /**
+     * Submits a raw video frame. Requires `useCustomInput()` + `start()`
+     * first.
+     *
+     * @param buffer      Raw pixel data (Uint8Array or Buffer).
+     * @param width       Frame width in pixels.
+     * @param height      Frame height in pixels.
+     * @param stride      Row stride in bytes.
+     * @param pixelFormat One of the PixelFormat constants.
+     * @param timestampUs Capture time in microseconds; must be strictly increasing.
+     * @returns true if the frame was accepted.
+     */
+    sendFrame(
+        buffer: Uint8Array | Buffer,
+        width: number,
+        height: number,
+        stride: number,
+        pixelFormat: PixelFormatValue,
+        timestampUs: number,
+    ): boolean;
+
+    /**
+     * Register a callback for a named event. Replaces any previously
+     * registered callback for the same event. Returns `this` for chaining.
+     *
+     * | Event                  | Callback signature                                                                 |
+     * |------------------------|------------------------------------------------------------------------------------|
+     * | `'processingStatus'`   | `(status: ProcessingStatusValue) => void`                                          |
+     * | `'validationStatus'`   | `(code: ValidationCodeValue, timestampUs: number, hint: string) => void`           |
+     * | `'metrics'`            | `(buf: Buffer, timestampUs: number) => void`                                       |
+     * | `'accumulatedMetrics'` | `(buf: Buffer, timestampUs: number) => void`                                       |
+     * | `'insight'`            | `(buf: Buffer, requestId: number) => void`                                         |
+     * | `'error'`              | `(code: SmartSpectraErrorCodeValue, message: string, retryable: boolean) => void`  |
+     * | `'frameSentThrough'`   | `(sent: boolean, timestampUs: number) => void`                                     |
+     * | `'videoOutput'`        | `(buf: Buffer, width: number, height: number, stride: number, pixelFormat: PixelFormatValue, timestampUs: number) => void` |
+     *
+     * `'videoOutput'` delivers a processed frame for the caller to render in
+     * its own UI. `buf` is borrowed for the callback only — it is copied before
+     * delivery, so retaining it is safe. Mainly useful for the custom-input /
+     * headless path.
+     */
+    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: Buffer, timestampUs: number) => void): this;
+    on(event: 'accumulatedMetrics', callback: (buf: Buffer, timestampUs: number) => void): this;
+    on(event: 'insight',            callback: (buf: Buffer, requestId: number) => void): this;
+    on(event: 'error',              callback: (code: SmartSpectraErrorCodeValue, message: string, retryable: boolean) => void): this;
+    on(event: 'frameSentThrough',   callback: (sent: boolean, timestampUs: number) => void): this;
+    on(event: 'videoOutput',        callback: (buf: Buffer, width: number, height: number, stride: number, pixelFormat: PixelFormatValue, timestampUs: number) => void): this;
+}
+
+/**
+ * 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[];
+export declare const faceMetrics:             readonly number[];
+export declare const micromotionMetrics:      readonly number[];
+export declare const edaMetrics:              readonly number[];
+/** Default metric bundle used when `requestedMetrics` is omitted. */
+export declare const defaultSupportedMetrics: readonly number[];
+
+/**
+ * Register a protobuf Metrics class exposing `deserializeBinary(buf)`
+ * (google-protobuf) or `decode(buf)` (protobufjs). `decodeMetrics()` will
+ * use it; otherwise the raw Buffer is returned.
+ */
+export declare function setMetricsClass(cls: unknown): void;
+
+/**
+ * Deserialize a protobuf Metrics buffer from the 'metrics' or
+ * 'accumulatedMetrics' events. Returns the decoded message if a class has
+ * been registered via `setMetricsClass`, otherwise the raw Buffer.
+ */
+export declare function decodeMetrics(buf: Buffer): unknown;

package/js/index.js

@@ -0,0 +1,60 @@
+// index.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+
+'use strict';
+
+const {
+    SmartSpectraSDK,
+    ProcessingStatus,
+    PixelFormat,
+    ValidationCode,
+    SmartSpectraErrorCode,
+    FrameTransform,
+    breathingMetrics,
+    cardioMetrics,
+    faceMetrics,
+    micromotionMetrics,
+    edaMetrics,
+    defaultSupportedMetrics,
+} = require('./smartspectra');
+
+// Eagerly register the bundled Metrics class so `decodeMetrics(buf)` works
+// without setup. Renderer-side consumers must require
+// `@smartspectra/node-sdk/messages` directly — this package root pulls in
+// koffi, which can't be bundled into a browser context.
+const { Metrics: DefaultMetricsClass } = require('./messages');
+
+let MetricsClass = DefaultMetricsClass;
+
+function setMetricsClass(cls) {
+    MetricsClass = cls;
+}
+
+function decodeMetrics(buf) {
+    if (MetricsClass && typeof MetricsClass.deserializeBinary === 'function') {
+        return MetricsClass.deserializeBinary(buf);
+    }
+    if (MetricsClass && typeof MetricsClass.decode === 'function') {
+        return MetricsClass.decode(buf);  // protobufjs-style
+    }
+    return buf;
+}
+
+module.exports = {
+    SmartSpectraSDK,
+    ProcessingStatus,
+    PixelFormat,
+    ValidationCode,
+    SmartSpectraErrorCode,
+    FrameTransform,
+    breathingMetrics,
+    cardioMetrics,
+    faceMetrics,
+    micromotionMetrics,
+    edaMetrics,
+    defaultSupportedMetrics,
+    decodeMetrics,
+    setMetricsClass,
+};

package/js/main/index.d.ts

@@ -0,0 +1,32 @@
+// js/main/index.d.ts
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+
+import type { BrowserWindow } from 'electron';
+
+export { SmartSpectraSDK, ProcessingStatus } from '../../js/index';
+
+/** Options for `bindSmartSpectraIpc`. */
+export interface BindSmartSpectraIpcOptions {
+    /**
+     * Optional logger for diagnostic messages from the IPC bridge.
+     * Defaults to `console`.
+     */
+    logger?: (level: 'info' | 'warn' | 'error', msg: string) => void;
+}
+
+/**
+ * Wires the per-window IPC channel that backs `@smartspectra/node-sdk/renderer`.
+ *
+ * Call once per `BrowserWindow` that hosts a renderer using the helper. The
+ * binding tracks the window via `'closed'` and releases its SDK + port when
+ * the window goes away, so apps don't need explicit teardown.
+ *
+ * One-time SDK initialization runs on the first call. Host apps don't manage
+ * it.
+ */
+export declare function bindSmartSpectraIpc(
+    window: BrowserWindow,
+    options?: BindSmartSpectraIpcOptions,
+): void;