@smartspectra/node-sdk 3.2.0-rc.6

package/js/ffi.js

@@ -0,0 +1,494 @@
+// ffi.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Pure-FFI bindings for smartspectra/capi. Type declarations mirror
+// smartspectra/capi/smartspectra_capi.h one-to-one — field order,
+// append-only struct evolution, and callback signatures are load-bearing.
+// The header's `_Static_assert` layout locks are the source of truth.
+//
+// Exposes a low-level `Session` class. The public, event-oriented
+// `SmartSpectraSDK` lives in smartspectra.js and wraps Session.
+
+'use strict';
+
+const koffi = require('koffi');
+const { resolveNativeLibrary } = require('./resolve-native');
+
+const lib = koffi.load(resolveNativeLibrary());
+
+// ---------------------------------------------------------------------------
+// Type declarations — mirror smartspectra_capi.h
+// ---------------------------------------------------------------------------
+
+// Opaque session token. C side: `struct smartspectra_session_s*`.
+koffi.opaque('smartspectra_session_t');
+
+// smartspectra_error_t — keep field order identical to the C struct; koffi
+// computes offsets by declaration order.
+koffi.struct('smartspectra_error_t', {
+    code:      'int',
+    message:   koffi.array('char', 512, 'String'),  // NUL-terminated, decoded to JS string
+    retryable: 'int',
+});
+
+// smartspectra_config_t — append-only ABI.
+koffi.struct('smartspectra_config_t', {
+    api_key:                   'const char *',
+    requested_metrics:         'const int32_t *',
+    requested_metrics_len:     'int',
+    enable_accumulated_output: 'int',
+});
+
+// Callback prototypes. koffi.register() returns thread-safe thunks: a call
+// originating on an SDK worker thread is marshalled to the V8 event loop
+// via libuv before invoking the JS function.
+koffi.proto('void smartspectra_on_status(uintptr_t handle, int status)');
+koffi.proto('void smartspectra_on_validation(uintptr_t handle, int code, ' +
+            'const char *hint, int64_t timestamp_us)');
+koffi.proto('void smartspectra_on_metrics(uintptr_t handle, ' +
+            'const uint8_t *proto_bytes, int proto_len, int64_t timestamp_us)');
+koffi.proto('void smartspectra_on_error(uintptr_t handle, int code, ' +
+            'const char *message, int retryable)');
+koffi.proto('void smartspectra_on_frame(uintptr_t handle, int sent, int64_t timestamp_us)');
+koffi.proto('void smartspectra_on_accumulated_metrics(uintptr_t handle, ' +
+            'const uint8_t *proto_bytes, int proto_len, int64_t timestamp_us)');
+koffi.proto('void smartspectra_on_insight(uintptr_t handle, ' +
+            'const uint8_t *proto_bytes, int proto_len, int32_t request_id)');
+koffi.proto('void smartspectra_on_video_output(uintptr_t handle, ' +
+            'const uint8_t *data, int width, int height, int stride_bytes, ' +
+            'int pixel_format, int64_t timestamp_us)');
+
+// smartspectra_callbacks_t — slots are append-only.
+koffi.struct('smartspectra_callbacks_t', {
+    on_status:              'smartspectra_on_status *',
+    on_validation:          'smartspectra_on_validation *',
+    on_metrics:             'smartspectra_on_metrics *',
+    on_error:               'smartspectra_on_error *',
+    on_frame:               'smartspectra_on_frame *',
+    on_accumulated_metrics: 'smartspectra_on_accumulated_metrics *',
+    on_insight:             'smartspectra_on_insight *',
+    on_video_output:        'smartspectra_on_video_output *',
+});
+
+// ---------------------------------------------------------------------------
+// Entry-point bindings. `_Out_` marks pure-output struct args so koffi
+// allocates the backing storage and decodes the result back into the
+// caller-supplied JS object.
+// ---------------------------------------------------------------------------
+const preconfigureFn = lib.func(
+    'int smartspectra_preconfigure(const char *directory, ' +
+    'const char *device_id, _Out_ smartspectra_error_t *out_err)');
+
+const sessionCreate = lib.func(
+    'smartspectra_session_t *smartspectra_session_create(' +
+    'const smartspectra_config_t *cfg, uintptr_t handle, ' +
+    'const smartspectra_callbacks_t *callbacks, ' +
+    '_Out_ smartspectra_error_t *out_err)');
+
+// Source option structs — field order matches smartspectra_capi.h (locked by
+// its layout asserts).
+koffi.struct('smartspectra_file_options_t', {
+    interframe_delay_ms: 'int',
+    start_offset_ms:     'int',
+    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.
+const sessionStartFile = lib.func(
+    'int smartspectra_session_start_file(smartspectra_session_t *sess, ' +
+    'const char *video_path, const char *timestamps_path, ' +
+    'const smartspectra_file_options_t *opts, _Out_ smartspectra_error_t *out_err)');
+
+const sessionStartCamera = lib.func(
+    'int smartspectra_session_start_camera(smartspectra_session_t *sess, ' +
+    'const smartspectra_camera_options_t *opts, _Out_ smartspectra_error_t *out_err)');
+
+const sessionStartCustom = lib.func(
+    'int smartspectra_session_start_custom(smartspectra_session_t *sess, ' +
+    'int frame_transform, _Out_ smartspectra_error_t *out_err)');
+
+const sessionSendFrame = lib.func(
+    'int smartspectra_session_send_frame(smartspectra_session_t *sess, ' +
+    'const uint8_t *data, size_t data_len, int width, int height, ' +
+    'int stride_bytes, int pixel_format, int64_t timestamp_us, ' +
+    '_Out_ smartspectra_error_t *out_err)');
+
+const sessionStop      = lib.func('void smartspectra_session_stop(smartspectra_session_t *sess)');
+const sessionWait      = lib.func('int  smartspectra_session_wait(smartspectra_session_t *sess, int timeout_ms)');
+const sessionGetStatus = lib.func('int  smartspectra_session_get_status(smartspectra_session_t *sess)');
+const sessionReset     = lib.func(
+    'int smartspectra_session_reset(smartspectra_session_t *sess, ' +
+    '_Out_ smartspectra_error_t *out_err)');
+const sessionRequestInsight = lib.func(
+    'int smartspectra_session_request_insight(smartspectra_session_t *sess, ' +
+    'const char *text, _Out_ int32_t *out_request_id, ' +
+    '_Out_ smartspectra_error_t *out_err)');
+const sessionDestroy   = lib.func('void smartspectra_session_destroy(smartspectra_session_t *sess)');
+
+// ---------------------------------------------------------------------------
+// Trampoline adapters. `const char *` args are auto-decoded by koffi to JS
+// strings (don't call koffi.decode — throws "expected external or
+// TypedArray"). `const uint8_t *` is NOT auto-decoded (no length); we
+// explicitly decode + copy into a fresh Buffer so the user can retain the
+// data past callback return (the C-side pointer is borrowed for the call
+// only).
+//
+// Plain functions, not class methods, so a future edit can't introduce a
+// hidden `this` dependency.
+// ---------------------------------------------------------------------------
+
+function wrapStatus(jsFn) {
+    return (_handle, status) => jsFn(status);
+}
+
+function wrapValidation(jsFn) {
+    return (_handle, code, hint, timestampUs) => jsFn(code, hint ?? '', timestampUs);
+}
+
+function wrapMetrics(jsFn) {
+    return (_handle, bytesPtr, length, timestampUs) => {
+        const len = length | 0;
+        const buf = len > 0
+            ? Buffer.from(koffi.decode(bytesPtr, koffi.array('uint8_t', len)))
+            : Buffer.alloc(0);
+        jsFn(buf, timestampUs);
+    };
+}
+
+function wrapError(jsFn) {
+    return (_handle, code, message, retryable) =>
+        jsFn(code, message ?? '', retryable !== 0);
+}
+
+function wrapFrame(jsFn) {
+    return (_handle, sent, timestampUs) => jsFn(sent !== 0, timestampUs);
+}
+
+function wrapInsight(jsFn) {
+    return (_handle, bytesPtr, length, requestId) => {
+        const len = length | 0;
+        const buf = len > 0
+            ? Buffer.from(koffi.decode(bytesPtr, koffi.array('uint8_t', len)))
+            : Buffer.alloc(0);
+        jsFn(buf, requestId | 0);
+    };
+}
+
+// Bytes occupied by a frame buffer, mirroring smartspectra_session_send_frame's
+// size rule: packed formats span stride_bytes * height; planar YUV (NV12=4,
+// NV21=5) adds a half-height chroma plane at the same stride.
+function frameByteLength(height, strideBytes, pixelFormat) {
+    if (pixelFormat === 4 || pixelFormat === 5) {
+        return strideBytes * height + strideBytes * Math.ceil(height / 2);
+    }
+    return strideBytes * height;
+}
+
+function wrapVideoOutput(jsFn) {
+    return (_handle, dataPtr, width, height, strideBytes, pixelFormat, timestampUs) => {
+        const w = width | 0, h = height | 0, stride = strideBytes | 0, fmt = pixelFormat | 0;
+        const len = frameByteLength(h, stride, fmt);
+        // Copy the borrowed pixel buffer so the consumer can retain it past
+        // callback return (same contract as wrapMetrics).
+        const buf = len > 0
+            ? Buffer.from(koffi.decode(dataPtr, koffi.array('uint8_t', len)))
+            : Buffer.alloc(0);
+        jsFn(buf, w, h, stride, fmt, timestampUs);
+    };
+}
+
+// Coerce a sendFrame() timestamp into a BigInt int64. Throws up front for
+// non-finite/non-numeric input so the caller sees an actionable message
+// instead of an opaque BigInt() RangeError from inside the FFI call.
+function toMicroseconds(timestampUs) {
+    if (typeof timestampUs === 'bigint') return timestampUs;
+    if (typeof timestampUs !== 'number' || !Number.isFinite(timestampUs)) {
+        throw new TypeError(
+            'sendFrame: timestampUs must be a finite number or bigint (microseconds)');
+    }
+    return BigInt(Math.trunc(timestampUs));
+}
+
+// ---------------------------------------------------------------------------
+// Session — thin wrapper over the C ABI. Owns the opaque C session pointer
+// and the set of koffi-registered callback thunks.
+//
+// Cleanup ordering (load-bearing):
+//   stop() → wait() → destroy() → unregister(thunks)
+// destroy() joins SDK worker threads before returning, so unregistering
+// after destroy() is safe. Doing it before would invalidate trampolines
+// while threads are still tearing down.
+// ---------------------------------------------------------------------------
+
+class Session {
+    /**
+     * @param {Object} cfg
+     * @param {string} cfg.apiKey
+     * @param {number[]} [cfg.requestedMetrics]
+     * @param {boolean} [cfg.enableAccumulatedOutput=false]
+     * @param {Object} callbacks
+     * @param {(status: number) => void} [callbacks.onStatus]
+     * @param {(code: number, hint: string, timestampUs: bigint) => void} [callbacks.onValidation]
+     * @param {(bytes: Buffer, timestampUs: bigint) => void} callbacks.onMetrics (required)
+     * @param {(code: number, message: string, retryable: boolean) => void} [callbacks.onError]
+     * @param {(sent: boolean, timestampUs: bigint) => void} [callbacks.onFrame]
+     * @param {(bytes: Buffer, timestampUs: bigint) => void} [callbacks.onAccumulatedMetrics]
+     * @param {(bytes: Buffer, requestId: number) => void} [callbacks.onInsight]
+     * @param {(bytes: Buffer, width: number, height: number, stride: number, pixelFormat: number, timestampUs: bigint) => void} [callbacks.onVideoOutput]
+     */
+    constructor(cfg, callbacks) {
+        if (!callbacks || typeof callbacks.onMetrics !== 'function') {
+            throw new TypeError('Session: callbacks.onMetrics is required');
+        }
+
+        this._registeredThunks = [];
+        this._destroyed = false;
+        // In-flight stopAsync() promise, if any. session_stop runs on a koffi
+        // worker thread; destroy() must wait for it to settle before deleting
+        // the session (see stopAsync / destroy below).
+        this._stopAsyncPromise = null;
+        // Resolves once native teardown has actually completed, so callers can
+        // serialize a replacement session against this one's wind-down.
+        this._teardownPromise = null;
+
+        // Null slots in the C struct mean the shim won't attempt to dispatch.
+        const cbs = {
+            on_status:              this._registerThunk(callbacks.onStatus,              'smartspectra_on_status *',              wrapStatus),
+            on_validation:          this._registerThunk(callbacks.onValidation,          'smartspectra_on_validation *',          wrapValidation),
+            on_metrics:             this._registerThunk(callbacks.onMetrics,             'smartspectra_on_metrics *',             wrapMetrics),
+            on_error:               this._registerThunk(callbacks.onError,               'smartspectra_on_error *',               wrapError),
+            on_frame:               this._registerThunk(callbacks.onFrame,               'smartspectra_on_frame *',               wrapFrame),
+            on_accumulated_metrics: this._registerThunk(callbacks.onAccumulatedMetrics,  'smartspectra_on_accumulated_metrics *', wrapMetrics),
+            on_insight:             this._registerThunk(callbacks.onInsight,             'smartspectra_on_insight *',             wrapInsight),
+            on_video_output:        this._registerThunk(callbacks.onVideoOutput,         'smartspectra_on_video_output *',        wrapVideoOutput),
+        };
+
+        // Keep the Int32Array on `this` until session_create returns so the
+        // GC can't recycle the buffer mid-call.
+        const requested = cfg.requestedMetrics ?? [];
+        this._requestedMetricsBuf = requested.length > 0
+            ? new Int32Array(requested)
+            : null;
+
+        const cConfig = {
+            api_key:                   cfg.apiKey ?? '',
+            requested_metrics:         this._requestedMetricsBuf,
+            requested_metrics_len:     requested.length,
+            enable_accumulated_output: cfg.enableAccumulatedOutput ? 1 : 0,
+        };
+
+        const err = {};
+        // `handle` is an opaque cookie threaded back into callbacks. Each
+        // Session captures `this` via the trampoline closures, so 0 is fine.
+        const sess = sessionCreate(cConfig, 0n, cbs, err);
+        if (sess === null) {
+            this._releaseThunks();
+            throw makeFfiError(err);
+        }
+        this._sess = sess;
+    }
+
+    // Non-blocking file source. timestampsPath + options (optional):
+    // { interframeDelayMs, startOffsetMs, maxDurationMs, frameTransform }.
+    startFile(videoPath, timestampsPath = null, options = null) {
+        this._assertAlive();
+        const err = {};
+        const opts = options ? {
+            interframe_delay_ms: options.interframeDelayMs | 0,
+            start_offset_ms:     options.startOffsetMs | 0,
+            max_duration_ms:     options.maxDurationMs | 0,
+            frame_transform:     options.frameTransform | 0,
+        } : null;
+        const rc = sessionStartFile(this._sess, videoPath, timestampsPath, opts, err);
+        if (rc !== 0) throw makeFfiError(err);
+    }
+
+    // options (optional): { deviceIndex, width, height, fps, frameTransform }
+    startCamera(options = null) {
+        this._assertAlive();
+        const err = {};
+        const opts = options ? {
+            device_index:    options.deviceIndex | 0,
+            width:           options.width | 0,
+            height:          options.height | 0,
+            fps:             options.fps | 0,
+            frame_transform: options.frameTransform | 0,
+        } : null;
+        const rc = sessionStartCamera(this._sess, opts, err);
+        if (rc !== 0) throw makeFfiError(err);
+    }
+
+    startCustom(frameTransform = 0) {
+        this._assertAlive();
+        const err = {};
+        const rc = sessionStartCustom(this._sess, frameTransform | 0, err);
+        if (rc !== 0) throw makeFfiError(err);
+    }
+
+    sendFrame(buffer, width, height, strideBytes, pixelFormat, timestampUs) {
+        this._assertAlive();
+        const err = {};
+        const rc = sessionSendFrame(
+            this._sess, buffer, buffer.byteLength,
+            width | 0, height | 0, strideBytes | 0, pixelFormat | 0,
+            toMicroseconds(timestampUs), err);
+        if (rc !== 0) throw makeFfiError(err);
+        return true;
+    }
+
+    stop() {
+        if (this._destroyed) return;
+        sessionStop(this._sess);
+    }
+
+    /**
+     * Async variant of `stop()`. `SmartSpectra::Stop()` blocks until the
+     * processing pipeline drains — can take multiple seconds with inference
+     * in flight. Run on a koffi worker thread so the JS event loop stays
+     * responsive during the drain.
+     */
+    stopAsync() {
+        if (this._destroyed) return Promise.resolve();
+        // Dedupe: a second stopAsync() while one is still draining returns the
+        // same promise rather than launching a second session_stop.
+        if (this._stopAsyncPromise) return this._stopAsyncPromise;
+        const p = new Promise((resolve, reject) => {
+            sessionStop.async(this._sess, (err) => {
+                if (err) reject(err);
+                else     resolve();
+            });
+        });
+        this._stopAsyncPromise = p;
+        const clear = () => { if (this._stopAsyncPromise === p) this._stopAsyncPromise = null; };
+        p.then(clear, clear);
+        return p;
+    }
+
+    wait(timeoutMs = 0) {
+        if (this._destroyed) return true;
+        return sessionWait(this._sess, timeoutMs | 0) !== 0;
+    }
+
+    getStatus() {
+        if (this._destroyed) return 0;  // kUninitialized
+        return sessionGetStatus(this._sess);
+    }
+
+    reset() {
+        this._assertAlive();
+        const err = {};
+        const rc = sessionReset(this._sess, err);
+        if (rc !== 0) throw makeFfiError(err);
+    }
+
+    /**
+     * Dispatch an on-demand insight prompt; returns the request id. The
+     * matching Insight response is delivered asynchronously through the
+     * `onInsight` callback supplied at construction time.
+     */
+    requestInsight(text) {
+        this._assertAlive();
+        if (typeof text !== 'string') {
+            throw new TypeError('requestInsight: text must be a string');
+        }
+        const err = {};
+        // koffi marshals the typed-array view as a writable pointer to the
+        // first element and writes the int32_t result into slot 0.
+        const out = new Int32Array(1);
+        const rc = sessionRequestInsight(this._sess, text, out, err);
+        if (rc !== 0) throw makeFfiError(err);
+        return out[0];
+    }
+
+    /**
+     * Tear down the native session. Returns a promise that resolves once the
+     * native teardown has completed — callers serializing a replacement
+     * session must await it, because SDK state is process-global and two
+     * sessions must not overlap. Idempotent.
+     */
+    destroy() {
+        if (this._destroyed) return this._teardownPromise || Promise.resolve();
+        this._destroyed = true;
+        // A stopAsync() may still be draining the graph on a koffi worker
+        // thread. Deleting the session (and unregistering its trampolines)
+        // while that thread is inside session_stop is a use-after-free, so
+        // defer the native teardown until the in-flight stop settles. The
+        // _destroyed guard already blocks any new stop from starting.
+        if (this._stopAsyncPromise) {
+            this._teardownPromise = this._stopAsyncPromise.then(
+                () => this._teardownNative(),
+                () => this._teardownNative());
+        } else {
+            this._teardownNative();
+            this._teardownPromise = Promise.resolve();
+        }
+        return this._teardownPromise;
+    }
+
+    _teardownNative() {
+        if (this._sess === null) return;
+        // stop → wait → destroy → unregister. session_destroy joins worker
+        // threads, so no SDK thread can call our trampolines after it returns.
+        sessionStop(this._sess);
+        sessionWait(this._sess, 0);
+        sessionDestroy(this._sess);
+        this._sess = null;
+        this._releaseThunks();
+    }
+
+    // ---------- internal ----------------------------------------------------
+
+    _assertAlive() {
+        if (this._destroyed) throw new Error('Session has been destroyed');
+    }
+
+    _registerThunk(jsFn, protoTypeName, makeAdapter) {
+        if (typeof jsFn !== 'function') return null;
+        const thunk = koffi.register(makeAdapter(jsFn), protoTypeName);
+        this._registeredThunks.push(thunk);
+        return thunk;
+    }
+
+    _releaseThunks() {
+        for (const t of this._registeredThunks) koffi.unregister(t);
+        this._registeredThunks = [];
+    }
+}
+
+// Wrap a populated smartspectra_error_t into a JS Error with numeric `code`
+// and boolean `retryable`.
+function makeFfiError(err) {
+    const msg = err.message || `SmartSpectra error code ${err.code}`;
+    const e = new Error(msg);
+    e.code = err.code;
+    e.retryable = err.retryable !== 0;
+    return e;
+}
+
+// Internal one-time SDK initialization. Called by the Electron main-process
+// glue in `@smartspectra/node-sdk/main`. Not part of the package's public
+// exports map — host apps don't reach for it.
+function preconfigure(sdkDirectory, deviceId) {
+    if (typeof sdkDirectory !== 'string' || sdkDirectory.length === 0) {
+        throw new TypeError('preconfigure: directory must be a non-empty string');
+    }
+    const err = {};
+    const rc = preconfigureFn(sdkDirectory, deviceId || null, err);
+    if (rc !== 0) throw makeFfiError(err);
+}
+
+module.exports = {
+    Session,
+    preconfigure,
+};