@mog-sdk/node 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,377 @@
+// ---------------------------------------------------------------------------
+// @mog/sdk — Type Declarations (auto-generated, do not edit)
+// ---------------------------------------------------------------------------
+
+// Opaque internal types — not part of the public SDK API.
+// Access these through the Workbook/Worksheet interfaces instead.
+/** @internal Rust compute engine bridge — use Workbook/Worksheet APIs instead */
+export type ComputeBridge = any;
+/** @internal Kernel document context — use Workbook/Worksheet APIs instead */
+export type DocumentContext = any;
+/** @internal NAPI engine interface */
+export interface NapiComputeEngine { [method: string]: (...args: unknown[]) => unknown; }
+/** @internal Kernel context for advanced consumers */
+export type IKernelContext = any;
+/** @internal Event bus */
+export type IEventBus = any;
+
+
+
+
+
+
+/**
+ * Save a workbook to a file path. Node.js only.
+ * Format determined by extension (.xlsx, .csv).
+ */
+declare function save(wb: Workbook, path: string): Promise<void>;
+
+
+/**
+ * A spreadsheet workbook — the primary API for all spreadsheet operations.
+ *
+ * Create with `createWorkbook()`. Access sheets via `getActiveSheet()`,
+ * `getSheet(index)`, or `getSheetByName(name)`.
+ *
+ * Sub-APIs: history, sheets, names, scenarios, styles, notifications,
+ * theme, viewport, protection, floatingObjects.
+ */
+export interface Workbook {
+  /** Get the currently active worksheet */
+  getActiveSheet(): Worksheet;
+  /** Get the active sheet ID */
+  getActiveSheetId(): string;
+  /** Set the active sheet by ID */
+  setActiveSheetId(sheetId: string): void;
+  /** Get sheet by 0-based index */
+  getSheet(index: number): Worksheet;
+  /** Get sheet by name */
+  getSheetByName(name: string): Worksheet | undefined;
+
+  /** Undo/redo, batch operations, checkpoints */
+  readonly history: WorkbookHistory;
+  /** Sheet CRUD: add, remove, rename, move, duplicate */
+  readonly sheets: WorkbookSheets;
+
+  /** Execute code in a sandboxed VM */
+  executeCode(code: string, options?: { timeout?: number }): Promise<unknown>;
+  /** Export workbook to XLSX buffer */
+  toBuffer(): Promise<Uint8Array>;
+  /** Dispose all resources — MUST call when done */
+  dispose(): void;
+
+  [key: string]: any;
+}
+
+export interface WorkbookHistory {
+  undo(): Promise<void>;
+  redo(): Promise<void>;
+  batch(fn: () => Promise<void>): Promise<void>;
+  [key: string]: any;
+}
+
+export interface WorkbookSheets {
+  add(name?: string): Promise<string>;
+  remove(sheetId: string): Promise<void>;
+  rename(sheetId: string, name: string): Promise<void>;
+  getAll(): Array<{ id: string; name: string; index: number }>;
+  [key: string]: any;
+}
+
+/**
+ * A single worksheet — read/write cells, formatting, charts, and more.
+ *
+ * Supports both A1 notation (`"A1"`) and numeric addressing (`(row, col)`).
+ *
+ * Sub-APIs: formats, layout, view, structure, charts, shapes, pictures,
+ * filters, validation, tables, pivots, slicers, comments, hyperlinks,
+ * outline, protection, print, settings, bindings.
+ */
+export interface Worksheet {
+  /** Sheet name */
+  readonly name: string;
+  /** Sheet ID */
+  readonly id: string;
+  /** 0-based sheet index */
+  getIndex(): number;
+
+  /** Set a cell value (A1 notation) */
+  setCell(address: string, value: unknown): Promise<void>;
+  /** Set a cell value (numeric) */
+  setCell(row: number, col: number, value: unknown): Promise<void>;
+
+  /** Get a cell's computed value */
+  getValue(address: string): Promise<unknown>;
+  getValue(row: number, col: number): Promise<unknown>;
+
+  /** Get a cell's formula (or undefined if none) */
+  getFormula(address: string): Promise<string | undefined>;
+  getFormula(row: number, col: number): Promise<string | undefined>;
+
+  /** Get full cell data */
+  getCell(address: string): Promise<CellData | undefined>;
+  getCell(row: number, col: number): Promise<CellData | undefined>;
+
+  /** Formatting sub-API */
+  readonly formats: WorksheetFormats;
+  /** Layout sub-API (row heights, column widths, merges) */
+  readonly layout: WorksheetLayout;
+  /** Chart operations */
+  readonly charts: WorksheetCharts;
+  /** Table operations */
+  readonly tables: WorksheetTables;
+
+  /** Describe the sheet for LLM consumption */
+  describe(): Promise<string>;
+  /** Describe a range for LLM consumption */
+  describeRange(range: string): Promise<string>;
+
+  [key: string]: any;
+}
+
+export interface CellData {
+  value: unknown;
+  formula?: string;
+  formattedValue?: string;
+  [key: string]: any;
+}
+
+export interface WorksheetFormats {
+  set(address: string, format: Record<string, unknown>): Promise<void>;
+  get(address: string): Promise<Record<string, unknown>>;
+  [key: string]: any;
+}
+
+export interface WorksheetLayout {
+  setRowHeight(row: number, height: number): Promise<void>;
+  setColumnWidth(col: number, width: number): Promise<void>;
+  merge(range: string): Promise<void>;
+  unmerge(range: string): Promise<void>;
+  [key: string]: any;
+}
+
+export interface WorksheetCharts {
+  add(type: string, dataRange: string, options?: Record<string, unknown>): Promise<string>;
+  remove(chartId: string): Promise<void>;
+  [key: string]: any;
+}
+
+export interface WorksheetTables {
+  add(range: string, options?: Record<string, unknown>): Promise<string>;
+  remove(tableId: string): Promise<void>;
+  [key: string]: any;
+}
+
+export interface CreateWorkbookOptions {
+  /** Document ID (auto-generated if omitted) */
+  documentId?: string;
+  /** XLSX source to import */
+  source?: { type: 'bytes'; data: Uint8Array } | { type: 'path'; path: string };
+  /** Import options */
+  importOptions?: Record<string, unknown>;
+}
+
+export interface WorkbookConfig {
+  ctx: any;
+  getActiveSheetId?: () => string;
+  setActiveSheetId?: (sheetId: string) => void;
+  eventBus: any;
+  [key: string]: any;
+}
+
+/**
+ * Create a new headless workbook.
+ *
+ * @example
+ * ```typescript
+ * import { createWorkbook } from '@mog/sdk';
+ * const wb = await createWorkbook();
+ * const ws = wb.getActiveSheet();
+ * await ws.setCell('A1', 42);
+ * ```
+ */
+export declare function createWorkbook(options?: CreateWorkbookOptions): Promise<Workbook>;
+
+/**
+ * HeadlessLifecycleSystem - Headless Boot Wrapper for the Spreadsheet Engine
+ *
+ * Thin shim that delegates to DocumentLifecycleSystem via DocumentFactory.
+ * DocumentLifecycleSystem accepts `{ environment: 'headless' }` and handles
+ * all headless-specific behavior (skipPersistenceLoad, no schema bridge,
+ * headless environment stubs, NAPI transport auto-detection).
+ *
+ * Architecture:
+ * - Uses `DocumentFactory.create({ environment: 'headless' })` for blank documents
+ * - Uses `DocumentFactory.createFromXlsx(source, { environment: 'headless' })` for XLSX import
+ * - No duplicated actor implementations — all lifecycle logic lives in DocumentLifecycleSystem
+ * - HeadlessEngine and createHeadlessEngine() are preserved for backward compatibility
+ *
+ * @see kernel/src/api/document/document-factory.ts - DocumentFactory
+ * @see kernel/src/document/document-lifecycle-system.ts - DocumentLifecycleSystem
+ */
+
+/**
+ * NapiAddonModule -- the object returned by require('compute-core-napi.node').
+ * Contains: ComputeEngine class + static free functions (compute_set_current_time, etc.)
+ */
+interface NapiAddonModule {
+    ComputeEngine: new (snapshotJson: string) => NapiComputeEngine;
+    [key: string]: unknown;
+}
+/**
+ * Options for creating a headless spreadsheet engine.
+ */
+interface HeadlessOptions {
+    /** Pre-loaded napi addon module (the object returned by require('compute-core-napi.node')) */
+    computeAddon: NapiAddonModule;
+    /** Document ID (defaults to random UUID) */
+    docId?: string;
+    /** XLSX buffer to import on boot (triggers hydrating state) */
+    xlsxSource?: Buffer;
+}
+/**
+ * Thin shim that delegates to DocumentFactory with `{ environment: 'headless' }`.
+ *
+ * Previously contained 5 duplicated actor implementations (createEngine,
+ * wireContext, startBridge, hydrateXlsx, disposeBridge). Now all lifecycle
+ * logic lives in DocumentLifecycleSystem, which handles headless-specific
+ * behavior when environment='headless'.
+ *
+ * Lifecycle:
+ * 1. Constructor stores options
+ * 2. create() calls DocumentFactory.create({ environment: 'headless' })
+ * 3. createFromXlsx() calls DocumentFactory.createFromXlsx(source, { environment: 'headless' })
+ * 4. dispose() calls handle.dispose()
+ */
+declare class HeadlessLifecycleSystem {
+    /** The document handle from DocumentFactory */
+    private handle;
+    /** The headless options (kept for backward compat) */
+    private readonly options;
+    constructor(options: HeadlessOptions);
+    /**
+     * Create a new blank document.
+     * Delegates to DocumentFactory.create() with headless environment.
+     */
+    create(docId: string): Promise<void>;
+    /**
+     * Create a document from an XLSX buffer.
+     * Delegates to DocumentFactory.createFromXlsx() with headless environment.
+     */
+    createFromXlsx(docId: string, xlsxSource: Buffer): Promise<void>;
+    /**
+     * Returns the DocumentContext from the handle.
+     * Throws if create() or createFromXlsx() has not been called.
+     */
+    get context(): DocumentContext;
+    /**
+     * Returns the ComputeBridge from the context.
+     * Throws if create() or createFromXlsx() has not been called.
+     */
+    get computeBridge(): ComputeBridge;
+    /**
+     * Dispose the document and clean up all resources.
+     * Safe to call multiple times (idempotent).
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * A headless spreadsheet engine instance.
+ *
+ * Wraps the lifecycle system and provides a clean public API.
+ * Created by `createHeadlessEngine()`.
+ *
+ * Provides two levels of access:
+ * - `workbook` / `general`: High-level External API (A1-notation, agent-friendly)
+ * - `computeBridge` / `context`: Low-level kernel access (row/col, identity-based)
+ */
+declare class HeadlessEngine {
+    private readonly lifecycle;
+    /** Cached unified Workbook instance (owns sheet cache, create once) */
+    private _workbook;
+    /** @internal */
+    constructor(lifecycle: HeadlessLifecycleSystem);
+    /**
+     * The unified Workbook — THE single API for all data and compute operations.
+     *
+     * Provides:
+     * - Sheet access: getSheet(index | name), getActiveSheet()
+     * - Sheet management: addSheet, removeSheet, moveSheet, renameSheet, etc.
+     * - Orchestration: undo, redo, batch, checkpoints, calc control, events
+     * - Named ranges, scenarios, introspection, code execution
+     *
+     * Each Worksheet provides:
+     * - Cell read/write with A1 AND numeric (row, col) overloads
+     * - Formatting, structure, merges, sort, charts, shapes
+     * - Filters, conditional formatting, validation, comments
+     * - Grouping, hyperlinks, pivots, slicers
+     * - LLM presentation: describe(), describeRange(), summarize()
+     *
+     * @see contracts/src/api/ — Interface definitions
+     */
+    get workbook(): Workbook;
+    /**
+     * Initialize the workbook instance asynchronously.
+     * Must be called after construction and before accessing `workbook`.
+     * @internal Called by `createHeadlessEngine()`.
+     */
+    initWorkbook(): Promise<void>;
+    /**
+     * Get or set the active sheet ID.
+     * Delegates to the workbook's internal active-sheet tracking.
+     */
+    get activeSheetId(): string;
+    set activeSheetId(id: string);
+    /**
+     * The fully wired DocumentContext -- provides access to all kernel services,
+     * bridges, event bus, and the compute bridge.
+     */
+    get context(): DocumentContext;
+    /**
+     * The Rust compute bridge -- direct access to the compute engine
+     * for cell mutations, formula evaluation, sheet operations, etc.
+     */
+    get computeBridge(): ComputeBridge;
+    /**
+     * Dispose the engine and clean up all resources.
+     *
+     * Sends DISPOSE event to the lifecycle machine and waits for
+     * 'disposed' state. Safe to call multiple times (idempotent).
+     *
+     * MUST be called when done to avoid resource leaks.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Create a headless spreadsheet engine.
+ *
+ * This boots the full kernel stack (compute-core, bridges, context) in Node.js
+ * without any browser dependencies. Uses the same lifecycle state machine as
+ * the browser app -- error handling, cleanup, and XLSX import support are shared.
+ *
+ * The engine uses `@mog/compute-core-napi` (a native Node.js addon) for
+ * the Rust compute core, providing the same performance as the Tauri desktop app.
+ *
+ * @param options - Configuration including the pre-loaded napi addon module
+ * @returns A ready-to-use HeadlessEngine
+ * @throws If engine initialization fails
+ *
+ * @example
+ * ```typescript
+ * // Load the napi addon
+ * const addon = require('@mog/compute-core-napi');
+ *
+ * // Create the headless engine
+ * const engine = await createHeadlessEngine({ computeAddon: addon });
+ *
+ * // Use the engine
+ * const bridge = engine.computeBridge;
+ * await bridge.setCell('sheet1', 0, 0, '=1+1');
+ *
+ * // Clean up
+ * await engine.dispose();
+ * ```
+ */
+declare function createHeadlessEngine(options: HeadlessOptions): Promise<HeadlessEngine>;
+
+export { HeadlessEngine, type HeadlessOptions, type NapiAddonModule, createHeadlessEngine, save };