@kymoscope/sdk 0.0.0-stage → 0.1.1

package/dist/types/lib/live/types.d.ts

@@ -0,0 +1,72 @@
+/** Live-stream types shared by the engine and charts. */
+import type { EncryptedEnvelope } from './crypto';
+import type { LiveColumnsBlock, LiveMessage } from './buffer';
+import type { LiveDataSource } from '../data/liveDataSource';
+import type { Dataset } from '../parseDataset';
+/** What a viewer needs to join an encrypted relay stream (from the stream registry). */
+export interface LiveStreamDescriptor {
+    id: string;
+    name: string;
+    /** PBKDF2 salt chosen by the publisher. */
+    salt: string;
+    /** Encrypted marker proving the password is right before any frame arrives. */
+    key_check: EncryptedEnvelope;
+    owner_name?: string;
+    visibility?: 'private' | 'public' | 'org' | 'project';
+    org_name?: string | null;
+    /** Null when the viewer can't see the project's name. */
+    project_name?: string | null;
+    /**
+     * The relay the stream goes through when it isn't the engine's (a relay its
+     * owner hosts). The engine's `getToken` is still asked for the credential.
+     */
+    relay_url?: string | null;
+}
+/**
+ * The keys of a stream in an end-to-end encrypted project: frames name their key id
+ * (the project key epoch & 0xff); `keyFor` resolves it (null: not available yet, the
+ * frame is dropped). The host (e.g. Kymoscope's key steward) unwraps them.
+ */
+export interface StreamKeyProvider {
+    keyFor(keyId: number | null): Promise<CryptoKey | null>;
+}
+/**
+ * How much of a stream a viewer keeps. Memory grows with the samples received,
+ * up to whichever limit comes first; past it the oldest samples are dropped.
+ */
+export interface LiveStreamOptions {
+    /** Samples kept per stream. Default 10,000,000. */
+    capacity?: number;
+    /** Memory a stream's samples may take, in MB (8 bytes per sample per channel,
+     *  time included). Default 512. */
+    maxMemoryMB?: number;
+}
+/** A host-fed stream: frames pushed from the page itself — no network, no crypto. */
+export interface LocalLiveStream {
+    id: string;
+    push: (frames: LiveMessage | LiveMessage[]) => void;
+    /**
+     * A block of samples by column: `t` and each signal the same length (typed
+     * arrays are copied in bulk). The way to feed high sample rates: no object
+     * per sample.
+     */
+    pushColumns: (block: LiveColumnsBlock) => void;
+    close: () => void;
+}
+export interface LiveConnection {
+    id: string;
+    name: string;
+    ownerName: string;
+    visibility: 'private' | 'public' | 'org' | 'project';
+    orgName: string | null;
+    projectName?: string | null;
+    /** Slow (~1 Hz) snapshot for column discovery / count / non-multiband charts. */
+    dataset: Dataset;
+    /** Live decimation source read by the multiband chart every frame (no React). */
+    source: LiveDataSource;
+    rowCount: number;
+    status: 'connecting' | 'live' | 'stale' | 'error';
+    error: string | null;
+    /** When a recording is running: its start time (ms since epoch). */
+    recordingSince: number | null;
+}

package/dist/types/lib/live/wire.d.ts

@@ -0,0 +1,25 @@
+export declare const KIND_SCHEMA = 1;
+export declare const KIND_FRAMES = 2;
+/** A block of samples by column (see columnsWire.ts): what high-rate publishers send. */
+export declare const KIND_COLUMNS = 3;
+export declare const KEY_ID_FLAG = 128;
+export interface SealedMessage {
+    kind: number;
+    /** The project key epoch & 0xff; null for password streams. */
+    keyId: number | null;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    aad: Uint8Array;
+}
+export declare function parseMessage(buf: ArrayBuffer): SealedMessage | null;
+/** The key of a message: one key, or per key id (project streams; null = not available). */
+export type MessageKey = CryptoKey | ((keyId: number | null) => Promise<CryptoKey | null>);
+/** Parse + decrypt. Null if malformed or its key isn't available; throws if authentication fails. */
+export declare function openMessage(key: MessageKey, buf: ArrayBuffer): Promise<{
+    kind: number;
+    plaintext: Uint8Array;
+} | null>;
+/** Seal a relay message (`keyId` given: the project-stream header). For tests and local publishers. */
+export declare function sealMessage(key: CryptoKey, kind: number, plaintext: Uint8Array, keyId?: number): Promise<ArrayBuffer>;
+/** @internal sealMessage with a fixed IV: pinned test vectors only (not in index.ts). */
+export declare function sealMessageWith(key: CryptoKey, kind: number, plaintext: Uint8Array, keyId?: number, _iv?: Uint8Array): Promise<ArrayBuffer>;

package/dist/types/lib/mathChannels/compile.d.ts

@@ -0,0 +1,22 @@
+import type { MathJsInstance, MathNode } from 'mathjs';
+/**
+ * A formula compiled to one JS loop over typed columns: writes row i's result
+ * to out[i] (NaN = null), reading input k from cols[k][i]. Throws what mathjs
+ * would throw on the first row it would throw on.
+ */
+export type Kernel = (out: Float64Array, cols: Float64Array[], n: number) => void;
+/**
+ * Compile `node` (inputs named by `inputs`, input k = cols[k]) or null when it
+ * holds anything not handled here, so the caller evaluates it with mathjs.
+ *
+ * Exact by construction rather than by reimplementing mathjs: values stay the
+ * JS values mathjs would see (numbers, booleans, null, Complex), every
+ * operator and function is the very function mathjs would call, and only the
+ * dispatch is skipped: when all arguments are numbers the call goes straight
+ * to the implementation typed-function would pick for them (typed.find),
+ * otherwise to the typed function itself (conversions, errors and all).
+ *
+ * A row with any non-finite input (a column, or a window op's result) is a
+ * gap (NaN) without evaluating.
+ */
+export declare function compileKernel(math: MathJsInstance, node: MathNode, inputs: string[]): Kernel | null;

package/dist/types/lib/mathChannels/evaluator.d.ts

@@ -0,0 +1,40 @@
+import type { Dataset } from '../parseDataset';
+import type { EvalResult, MathChannel } from './types';
+/** evalChannelColumns' result: values with NaN for null; `compiled` when a compiled kernel produced them. */
+export interface ColumnsResult extends Omit<EvalResult, 'values'> {
+    values: Float64Array;
+    compiled?: boolean;
+}
+export declare function evalChannel(channel: MathChannel, dataset: Dataset, xKey: string, otherChannels: MathChannel[]): EvalResult;
+/** Test-only: evaluate with mathjs alone (the reference the kernels must match). */
+export declare function _setCompiledKernels(on: boolean): void;
+/**
+ * evalChannel over columns: `column(name)` is that column's values (NaN or any
+ * non-finite value = empty), undefined when the dataset has no such column.
+ * Formulas run as compiled kernels when compileKernel handles them, else
+ * through mathjs row by row; both give the same values and statuses.
+ */
+export declare function evalChannelColumns(channel: MathChannel, column: (name: string) => Float64Array | undefined, xKey: string, length: number, otherChannels: MathChannel[], carry?: IntegralCarry): ColumnsResult;
+/**
+ * Running integrals across evaluations of a growing series (live channels are
+ * evaluated over the newest samples only): the k-th integral() call of a formula
+ * starts from `start(k)` instead of 0, and `done(k, values)` hands back what it
+ * computed, for the next evaluation to continue from.
+ */
+export interface IntegralCarry {
+    start(k: number): number;
+    done(k: number, values: ArrayLike<number | null>): void;
+}
+export declare function evalAllChannels(channels: MathChannel[], dataset: Dataset, xKey: string): Record<string, EvalResult>;
+type Materialized = {
+    rows: Dataset['rows'];
+    ok: MathChannel[];
+};
+/**
+ * `part`'s rows extended with the `ok` channels' values, evaluated on this part
+ * alone (window ops never mix samples across datasets). Cached per rows array
+ * and channels-array identity, so showing/hiding one dataset reuses the others'
+ * materialized rows instead of re-evaluating and re-cloning everything.
+ */
+export declare function materializeChannels(part: Dataset, channels: MathChannel[], xKey: string): Materialized;
+export {};

package/dist/types/lib/mathChannels/functions/conditional.d.ts

@@ -0,0 +1,2 @@
+import type { MathJsInstance } from 'mathjs';
+export declare function registerConditional(m: MathJsInstance): void;

package/dist/types/lib/mathChannels/functions/filters.d.ts

@@ -0,0 +1,7 @@
+import type { Numlike } from './windowOps';
+/** Median of finite values, used to infer sample rate from a time column (null or NaN = empty). */
+export declare function inferSampleRate(x: ArrayLike<Numlike>): number;
+export declare function lowpass(y: Numlike[], fc: number, fs: number): Numlike[];
+export declare function highpass(y: Numlike[], fc: number, fs: number): Numlike[];
+export declare function lowpassCol(y: Float64Array, fc: number, fs: number): Float64Array | null;
+export declare function highpassCol(y: Float64Array, fc: number, fs: number): Float64Array | null;

package/dist/types/lib/mathChannels/functions/index.d.ts

@@ -0,0 +1,3 @@
+import type { MathJsInstance } from 'mathjs';
+export declare function createMathInstanceWithFunctions(): MathJsInstance;
+export { FUNCTION_REFERENCE, type FunctionDoc } from './reference';

package/dist/types/lib/mathChannels/functions/reference.d.ts

@@ -0,0 +1,7 @@
+export interface FunctionDoc {
+    name: string;
+    signature: string;
+    description: string;
+    isWindow: boolean;
+}
+export declare const FUNCTION_REFERENCE: FunctionDoc[];

package/dist/types/lib/mathChannels/functions/windowOps.d.ts

@@ -0,0 +1,11 @@
+export type Numlike = number | null;
+export declare function derivative(y: Numlike[], x: Numlike[]): Numlike[];
+export declare function integral(y: Numlike[], x: Numlike[]): Numlike[];
+export declare function movavg(y: Numlike[], n: number): Numlike[];
+export declare function lag(y: Numlike[], n: number): Numlike[];
+export declare function lead(y: Numlike[], n: number): Numlike[];
+export declare function derivativeCol(y: Float64Array, x: Float64Array): Float64Array | null;
+export declare function integralCol(y: Float64Array, x: Float64Array): Float64Array | null;
+export declare function movavgCol(y: Float64Array, n: number): Float64Array | null;
+export declare function lagCol(y: Float64Array, n: number): Float64Array;
+export declare function leadCol(y: Float64Array, n: number): Float64Array;

package/dist/types/lib/mathChannels/index.d.ts

@@ -0,0 +1,13 @@
+export type { MathChannel, MathChannelPatch, EvalResult, EvalStatus, MathChannelsBundle, } from './types';
+export { newMathChannel } from './types';
+export { evalChannel, evalAllChannels, materializeChannels } from './evaluator';
+export { pickUsedChannels } from './usedChannels';
+export { parseFormula, extractFreeIdentifiers, WINDOW_FN_NAMES } from './parser';
+export { FUNCTION_REFERENCE } from './functions/reference';
+export type { FunctionDoc } from './functions/reference';
+export declare function isMathChannelName(name: string, channels: {
+    name: string;
+}[]): boolean;
+export declare function decorateColumnLabel(name: string, channels: {
+    name: string;
+}[]): string;

package/dist/types/lib/mathChannels/io.d.ts

@@ -0,0 +1,18 @@
+import type { MathChannel } from './types';
+export interface ExportEnvelope {
+    version: 1;
+    exportedAt: string;
+    channels: Array<{
+        name: string;
+        units: string;
+        formula: string;
+        enabled: boolean;
+        description?: string;
+    }>;
+}
+export interface ImportResult {
+    channels: MathChannel[];
+    errors: string[];
+}
+export declare function buildExportBlob(channels: MathChannel[]): Blob;
+export declare function parseImportFile(file: File): Promise<ImportResult>;

package/dist/types/lib/mathChannels/mathjsSetup.d.ts

@@ -0,0 +1,7 @@
+import { type MathJsInstance } from 'mathjs';
+export type SetupFn = (m: MathJsInstance) => void;
+export declare function createMathInstance(setup?: SetupFn): MathJsInstance;
+/** Parses a formula with an instance made by createMathInstance. */
+export declare function hostParse(m: MathJsInstance, formula: string): import("mathjs").MathNode;
+/** Evaluates a formula with an instance made by createMathInstance. */
+export declare function hostEvaluate(m: MathJsInstance, formula: string, scope?: Record<string, unknown>): unknown;

package/dist/types/lib/mathChannels/parseMath.d.ts

@@ -0,0 +1,12 @@
+import type { MathNode } from 'mathjs';
+/** parseFormula with the node typed as mathjs's MathNode, for the evaluator. */
+export type MathParseResult = {
+    ok: true;
+    node: MathNode;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseMathFormula(formula: string): MathParseResult;
+/** Test-only: clear the AST cache between tests if needed. */
+export declare function _resetParserCache(): void;

package/dist/types/lib/mathChannels/parser.d.ts

@@ -0,0 +1,22 @@
+export declare const WINDOW_FN_NAMES: readonly ["derivative", "integral", "movavg", "lag", "lead", "lowpass", "highpass"];
+/**
+ * A parsed formula: a mathjs expression tree, typed locally so the published declarations do not need
+ * mathjs. Pass it to {@link extractFreeIdentifiers}; anything deeper is a mathjs `MathNode`.
+ */
+export interface FormulaNode {
+    readonly type: string;
+    toString(): string;
+}
+export type ParseResult = {
+    ok: true;
+    node: FormulaNode;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseFormula(formula: string): ParseResult;
+export interface FreeIdentifiers {
+    identifiers: string[];
+    functions: string[];
+}
+export declare function extractFreeIdentifiers(formula: FormulaNode): FreeIdentifiers;

package/dist/types/lib/mathChannels/types.d.ts

@@ -0,0 +1,34 @@
+export type MathChannelSource = 'personal' | 'subscribed' | 'workbook';
+export interface MathChannel {
+    id: string;
+    name: string;
+    units: string;
+    formula: string;
+    enabled: boolean;
+    description?: string;
+    createdAt: number;
+    updatedAt: number;
+    source: MathChannelSource;
+    /** @deprecated use projectId */
+    sharedWithOrgId: string | null;
+    /** The project the channel belongs to (null: its owner's personal space). */
+    projectId: string | null;
+    projectName?: string | null;
+    ownerUserId: string;
+    ownerDisplayName: string | null;
+    ownerLastName: string | null;
+}
+export type MathChannelPatch = Partial<Pick<MathChannel, 'name' | 'units' | 'formula' | 'enabled' | 'description'>>;
+export type EvalStatus = 'ok' | 'missing-inputs' | 'parse-error' | 'runtime-error' | 'disabled' | 'references-channel';
+export interface EvalResult {
+    channelId: string;
+    status: EvalStatus;
+    values: (number | null)[];
+    message?: string;
+    missingCols?: string[];
+}
+export interface MathChannelsBundle {
+    version: 1;
+    channels: MathChannel[];
+}
+export declare function newMathChannel(partial?: Partial<MathChannel>): MathChannel;

package/dist/types/lib/mathChannels/usedChannels.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Math channels that are actually plotted — referenced by a panel (as a series,
+ * axis, color, heatmap column, ...) or used as the X key.
+ *
+ * Detection scans the serialized panel settings so it catches every reference
+ * shape without coupling to each chart type. Channels NOT returned can be skipped
+ * during materialization — a big per-frame win for live data, where materializing
+ * an unused channel spreads the whole dataset into new rows on every tick. The
+ * skipped channels stay available to add to a chart (the picker sources their
+ * names separately).
+ */
+export declare function pickUsedChannels<T extends {
+    name: string;
+}>(channels: T[], panelSettings: unknown, xKey: string): T[];

package/dist/types/lib/moduleWorker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Starts a module worker from a bundled worker URL (`import url from './x.worker.ts?worker&url'`).
+ * Browsers refuse `new Worker(url)` across origins, which is the case when the SDK script is served
+ * from a CDN; a same-origin blob module that imports the real worker is allowed (the import is an
+ * ordinary CORS fetch, and the worker's own relative imports resolve against its real URL).
+ */
+export declare function moduleWorker(url: string): Worker;