@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/connections/api.d.ts

@@ -0,0 +1,879 @@
+/**
+ * External API Contracts
+ *
+ * Type definitions for the external-facing spreadsheet API.
+ * These interfaces define the public API surface for AI agents
+ * and external consumers.
+ */
+import type { CellAddress, CellData, CellFormat, CellRange, CellValue, CellValuePrimitive, SheetInfo } from '../core/core';
+import type { CodeExecutionOptions, CodeExecutionResult } from '../core/execution';
+import type { Chart as ApiChart, ChartConfig as ApiChartConfig } from '../data/charts';
+import type { ApiSortOptions } from '../data/sorting';
+import type { TableConfig } from '../data/tables';
+import type { SpreadsheetEvent, SpreadsheetEventType } from '../events';
+import type { ApiError } from './api-errors';
+/**
+ * Standard result type for all write operations.
+ * Uses discriminated union pattern for type-safe error handling.
+ */
+export type OperationResult<T = void> = {
+    success: true;
+    data: T;
+    affectedCells?: CellAddress[];
+} | {
+    success: false;
+    error: ApiError;
+};
+/**
+ * Helper type for void operations (no data returned on success)
+ */
+export type VoidResult = OperationResult<void>;
+/**
+ * Summary of sheet contents
+ */
+export interface SheetSnapshot {
+    /** Sheet ID */
+    id: string;
+    /** Sheet name */
+    name: string;
+    /** Sheet index (0-based) */
+    index: number;
+    /** Range containing all non-empty cells, or null if sheet is empty */
+    usedRange: CellRange | null;
+    /** Number of cells with data */
+    cellCount: number;
+    /** Number of cells with formulas */
+    formulaCount: number;
+    /** Number of charts in this sheet */
+    chartCount: number;
+    /** Sheet dimensions */
+    dimensions: {
+        rows: number;
+        cols: number;
+    };
+}
+/**
+ * Summary of workbook contents
+ */
+export interface WorkbookSnapshot {
+    /** All sheets in the workbook */
+    sheets: SheetSnapshot[];
+    /** ID of the active sheet */
+    activeSheetId: string;
+    /** Total number of sheets */
+    sheetCount: number;
+}
+/**
+ * Information about a spreadsheet function
+ */
+export interface FunctionInfo {
+    /** Function name (e.g., "SUM", "VLOOKUP") */
+    name: string;
+    /** Function category (e.g., "Math", "Lookup", "Text") */
+    category: string;
+    /** Description of what the function does */
+    description: string;
+    /** Syntax example (e.g., "SUM(number1, [number2], ...)") */
+    syntax: string;
+    /** Parameter descriptions */
+    parameters: FunctionParameter[];
+    /** Return type description */
+    returnType: string;
+    /** Usage examples */
+    examples: string[];
+}
+/**
+ * Function parameter description
+ */
+export interface FunctionParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter description */
+    description: string;
+    /** Whether the parameter is optional */
+    optional?: boolean;
+    /** Whether the parameter can be repeated */
+    repeating?: boolean;
+    /** Expected type(s) */
+    type?: string;
+}
+/**
+ * Information about a merged region.
+ *
+ * This is the external API representation - it exposes only resolved positions,
+ * hiding internal CellId implementation details.
+ */
+export interface MergedRegionInfo {
+    /** Start row (0-based) */
+    startRow: number;
+    /** Start column (0-based) */
+    startCol: number;
+    /** End row (0-based, inclusive) */
+    endRow: number;
+    /** End column (0-based, inclusive) */
+    endCol: number;
+    /** Row span (endRow - startRow + 1) */
+    rowSpan: number;
+    /** Column span (endCol - startCol + 1) */
+    colSpan: number;
+}
+/**
+ * Shape types supported by the API.
+ * Matches ShapeType from floating-objects.ts for consistency.
+ */
+export type ApiShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'parallelogram' | 'trapezoid' | 'nonIsoscelesTrapezoid' | 'heptagon' | 'decagon' | 'dodecagon' | 'teardrop' | 'pie' | 'pieWedge' | 'blockArc' | 'donut' | 'noSmoking' | 'plaque' | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'chevron' | 'leftArrowCallout' | 'rightArrowCallout' | 'upArrowCallout' | 'downArrowCallout' | 'leftRightArrowCallout' | 'upDownArrowCallout' | 'quadArrowCallout' | 'bentArrow' | 'uturnArrow' | 'circularArrow' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'swooshArrow' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'ribbon' | 'ribbon2' | 'ellipseRibbon' | 'ellipseRibbon2' | 'leftRightRibbon' | 'banner' | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloud' | 'callout1' | 'callout2' | 'callout3' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'line' | 'lineArrow' | 'lineDoubleArrow' | 'curve' | 'arc' | 'connector' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' | 'flowChartProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOfflineStorage' | 'flowChartOnlineStorage' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'flowChartDelay' | 'flowChartAlternateProcess' | 'flowChartOffpageConnector' | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'smileyFace' | 'foldedCorner' | 'bevel' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'can' | 'cube' | 'plus' | 'cross' | 'irregularSeal1' | 'irregularSeal2' | 'homePlate' | 'funnel' | 'verticalScroll' | 'horizontalScroll' | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonForwardNext' | 'actionButtonBackPrevious' | 'actionButtonEnd' | 'actionButtonBeginning' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'bracketPair' | 'bracePair' | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' | 'gear6' | 'gear9' | 'cornerTabs' | 'squareTabs' | 'plaqueTabs' | 'chartX' | 'chartStar' | 'chartPlus';
+/**
+ * Shape position configuration for API.
+ */
+export interface ApiShapePosition {
+    /** Anchor row (0-based) */
+    anchorRow: number;
+    /** Anchor column (0-based) */
+    anchorCol: number;
+    /** X offset from cell in pixels */
+    xOffset?: number;
+    /** Y offset from cell in pixels */
+    yOffset?: number;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+}
+/**
+ * Shape fill configuration.
+ */
+export interface ApiShapeFill {
+    /** Fill type */
+    type: 'none' | 'solid' | 'gradient';
+    /** Fill color (for solid) */
+    color?: string;
+}
+/**
+ * Shape outline configuration.
+ */
+export interface ApiShapeOutline {
+    /** Outline style */
+    style: 'none' | 'solid' | 'dashed' | 'dotted';
+    /** Outline color */
+    color?: string;
+    /** Outline width in pixels */
+    width?: number;
+}
+/**
+ * Shape configuration for API operations.
+ */
+export interface ApiShapeConfig {
+    /** Shape type */
+    type: ApiShapeType;
+    /** Position configuration */
+    position: ApiShapePosition;
+    /** Optional name for the shape */
+    name?: string;
+    /** Fill configuration */
+    fill?: ApiShapeFill;
+    /** Outline configuration */
+    outline?: ApiShapeOutline;
+    /** Text content inside the shape */
+    text?: string;
+    /** Rotation angle in degrees (0-360) */
+    rotation?: number;
+    /** Whether the shape is locked */
+    locked?: boolean;
+}
+/**
+ * Shape data returned by the API.
+ */
+export interface ApiShape extends ApiShapeConfig {
+    /** Unique shape ID */
+    id: string;
+    /** Sheet ID the shape belongs to */
+    sheetId: string;
+    /** Z-order within the sheet */
+    zIndex: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Last update timestamp */
+    updatedAt?: number;
+}
+/**
+ * Per-sheet operations interface.
+ * Obtained via SpreadsheetAPI.sheet(sheetId) or .activeSheet()
+ */
+export interface ISheetAPI {
+    /** The sheet ID this API operates on */
+    readonly sheetId: string;
+    /**
+     * Get complete cell data including formula, format, etc.
+     * Returns undefined if cell is empty.
+     */
+    getCell(row: number, col: number): CellData | undefined | Promise<CellData | undefined>;
+    /**
+     * Get the computed value of a cell.
+     * For formula cells, returns the calculated result.
+     */
+    getValue(row: number, col: number): CellValue | Promise<CellValue>;
+    /**
+     * Get the display string of a cell (formatted value).
+     */
+    getDisplayValue(row: number, col: number): string | Promise<string>;
+    /**
+     * Get the formula of a cell, if any.
+     */
+    getFormula(row: number, col: number): string | undefined | Promise<string | undefined>;
+    /**
+     * Get the format of a cell.
+     */
+    getFormat(row: number, col: number): CellFormat | undefined | Promise<CellFormat | undefined>;
+    /**
+     * Set a cell's value. If value starts with "=", it's treated as a formula.
+     */
+    setCell(row: number, col: number, value: CellValuePrimitive): Promise<OperationResult<void>>;
+    /**
+     * Clear a cell's value.
+     */
+    clearCell(row: number, col: number): Promise<OperationResult<void>>;
+    /**
+     * Get all cell data in a range.
+     */
+    getRange(range: CellRange): CellData[][] | Promise<CellData[][]>;
+    /**
+     * Get just the values from a range.
+     */
+    getRangeValues(range: CellRange): CellValue[][] | Promise<CellValue[][]>;
+    /**
+     * Set values in a range from a 2D array.
+     * Array dimensions determine the range size.
+     */
+    setRange(startRow: number, startCol: number, values: CellValuePrimitive[][]): Promise<OperationResult<void>>;
+    /**
+     * Clear all values in a range.
+     */
+    clearRange(range: CellRange): Promise<OperationResult<void>>;
+    /**
+     * Set format for a single cell.
+     */
+    setFormat(row: number, col: number, format: Partial<CellFormat>): OperationResult<void>;
+    /**
+     * Set format for a range.
+     */
+    setRangeFormat(range: CellRange, format: Partial<CellFormat>): OperationResult<void>;
+    /**
+     * Clear format from a cell.
+     */
+    clearFormat(row: number, col: number): OperationResult<void>;
+    /**
+     * Insert rows at the specified position.
+     */
+    insertRows(startRow: number, count: number): OperationResult<void>;
+    /**
+     * Delete rows starting at the specified position.
+     */
+    deleteRows(startRow: number, count: number): OperationResult<void>;
+    /**
+     * Insert columns at the specified position.
+     */
+    insertColumns(startCol: number, count: number): OperationResult<void>;
+    /**
+     * Delete columns starting at the specified position.
+     */
+    deleteColumns(startCol: number, count: number): OperationResult<void>;
+    /**
+     * Merge cells in a range.
+     *
+     * Creates a merged region where the top-left cell contains the value
+     * and spans across all cells in the range. Other cells in the range
+     * are cleared.
+     *
+     * @param range - The range to merge
+     * @returns OperationResult with the merge info, or error if range is invalid/overlaps
+     *
+     * @example
+     * ```typescript
+     * // Merge cells A1:B2
+     * const result = sheet.mergeCells({ startRow: 0, startCol: 0, endRow: 1, endCol: 1 });
+     * if (result.success) {
+     *   console.log('Merged region created');
+     * }
+     * ```
+     */
+    mergeCells(range: CellRange): OperationResult<MergedRegionInfo>;
+    /**
+     * Unmerge cells in a range.
+     *
+     * Removes any merged regions whose origin falls within the given range.
+     * The origin cell retains its value.
+     *
+     * @param range - The range to unmerge
+     * @returns OperationResult with the count of merges removed
+     */
+    unmergeCells(range: CellRange): OperationResult<{
+        count: number;
+    }>;
+    /**
+     * Get all merged regions in this sheet.
+     *
+     * @returns Array of merged regions with their resolved positions
+     */
+    getMergedRegions(): MergedRegionInfo[] | Promise<MergedRegionInfo[]>;
+    /**
+     * Get the merge containing a specific cell, if any.
+     *
+     * @param row - Row index (0-based)
+     * @param col - Column index (0-based)
+     * @returns The merge info if cell is in a merge, undefined otherwise
+     */
+    getMergeAt(row: number, col: number): MergedRegionInfo | undefined | Promise<MergedRegionInfo | undefined>;
+    /**
+     * Create a new chart on this sheet.
+     *
+     * @param config - Chart configuration
+     * @returns OperationResult with the created chart's ID
+     *
+     * @example
+     * ```typescript
+     * const result = sheet.createChart({
+     *   type: 'bar',
+     *   dataRange: 'A1:D10',
+     *   position: { anchorRow: 0, anchorCol: 5, width: 8, height: 15 },
+     *   title: 'Sales by Region',
+     * });
+     * if (result.success) {
+     *   console.log('Created chart:', result.data.chartId);
+     * }
+     * ```
+     */
+    createChart(config: ApiChartConfig): OperationResult<{
+        chartId: string;
+    }> | Promise<OperationResult<{
+        chartId: string;
+    }>>;
+    /**
+     * Update an existing chart's configuration.
+     *
+     * @param chartId - ID of the chart to update
+     * @param updates - Partial configuration to apply
+     * @returns OperationResult indicating success or failure
+     */
+    updateChart(chartId: string, updates: Partial<ApiChartConfig>): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Delete a chart from this sheet.
+     *
+     * @param chartId - ID of the chart to delete
+     * @returns OperationResult indicating success or failure
+     */
+    deleteChart(chartId: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Get a chart by ID.
+     *
+     * @param chartId - ID of the chart
+     * @returns The chart configuration, or undefined if not found
+     */
+    getChart(chartId: string): ApiChart | undefined | Promise<ApiChart | undefined>;
+    /**
+     * Get all charts on this sheet.
+     *
+     * @returns Array of chart configurations
+     */
+    getCharts(): ApiChart[] | Promise<ApiChart[]>;
+    /**
+     * Create a new shape on this sheet.
+     *
+     * @param config - Shape configuration
+     * @returns OperationResult with the created shape
+     */
+    createShape(config: ApiShapeConfig): OperationResult<ApiShape> | Promise<OperationResult<ApiShape>>;
+    /**
+     * Get a shape by ID.
+     *
+     * @param shapeId - ID of the shape
+     * @returns The shape, or undefined if not found
+     */
+    getShape(shapeId: string): ApiShape | undefined;
+    /**
+     * Get all shapes on this sheet.
+     *
+     * @returns Array of shapes
+     */
+    getShapes(): ApiShape[];
+    /**
+     * Update a shape's properties.
+     *
+     * @param shapeId - ID of the shape to update
+     * @param updates - Partial configuration to apply
+     * @returns OperationResult indicating success or failure
+     */
+    updateShape(shapeId: string, updates: Partial<ApiShapeConfig>): OperationResult<void>;
+    /**
+     * Delete a shape from this sheet.
+     *
+     * @param shapeId - ID of the shape to delete
+     * @returns OperationResult indicating success or failure
+     */
+    deleteShape(shapeId: string): OperationResult<void>;
+    /**
+     * Move a shape to a new position.
+     *
+     * @param shapeId - ID of the shape to move
+     * @param x - New X position in pixels
+     * @param y - New Y position in pixels
+     * @returns OperationResult indicating success or failure
+     */
+    moveShape(shapeId: string, x: number, y: number): OperationResult<void>;
+    /**
+     * Resize a shape.
+     *
+     * @param shapeId - ID of the shape to resize
+     * @param width - New width in pixels
+     * @param height - New height in pixels
+     * @returns OperationResult indicating success or failure
+     */
+    resizeShape(shapeId: string, width: number, height: number): OperationResult<void>;
+    /**
+     * Rotate a shape.
+     *
+     * @param shapeId - ID of the shape to rotate
+     * @param angle - Rotation angle in degrees (0-360)
+     * @returns OperationResult indicating success or failure
+     */
+    rotateShape(shapeId: string, angle: number): OperationResult<void>;
+    /**
+     * Flip a shape horizontally or vertically.
+     *
+     * @param shapeId - ID of the shape to flip
+     * @param direction - 'horizontal' or 'vertical'
+     * @returns OperationResult indicating success or failure
+     */
+    flipShape(shapeId: string, direction: 'horizontal' | 'vertical'): OperationResult<void>;
+    /**
+     * Duplicate a shape.
+     *
+     * @param shapeId - ID of the shape to duplicate
+     * @param offsetX - Optional horizontal offset for the duplicate (default: 20px)
+     * @param offsetY - Optional vertical offset for the duplicate (default: 20px)
+     * @returns OperationResult with the duplicated shape
+     */
+    duplicateShape(shapeId: string, offsetX?: number, offsetY?: number): OperationResult<ApiShape>;
+    /**
+     * Bring a shape to the front (highest z-index).
+     *
+     * @param shapeId - ID of the shape
+     * @returns OperationResult indicating success or failure
+     */
+    bringShapeToFront(shapeId: string): OperationResult<void>;
+    /**
+     * Send a shape to the back (lowest z-index).
+     *
+     * @param shapeId - ID of the shape
+     * @returns OperationResult indicating success or failure
+     */
+    sendShapeToBack(shapeId: string): OperationResult<void>;
+    /**
+     * Get the range containing all non-empty cells.
+     */
+    getUsedRange(): CellRange | null;
+    /**
+     * Find cells matching a predicate.
+     */
+    findCells(predicate: (cell: CellData, row: number, col: number) => boolean): CellAddress[];
+    /**
+     * Find cells by value.
+     */
+    findByValue(value: CellValue): CellAddress[];
+    /**
+     * Find cells with formulas matching a pattern.
+     */
+    findByFormula(pattern: RegExp): CellAddress[];
+    /**
+     * Get cells that depend on the specified cell.
+     */
+    getDependents(row: number, col: number): CellAddress[] | Promise<CellAddress[]>;
+    /**
+     * Get cells that the specified cell references.
+     */
+    getPrecedents(row: number, col: number): CellAddress[] | Promise<CellAddress[]>;
+    /**
+     * Sort a range of cells.
+     *
+     * Sorts the data in a range based on one or more columns.
+     * Uses the Cell Identity Model internally - cells keep their identity
+     * (CellIds), only positions change.
+     *
+     * @param range - The range to sort
+     * @param options - Sort options specifying columns and directions
+     * @returns OperationResult with the number of rows that changed position
+     *
+     * @example
+     * ```typescript
+     * // Sort A1:C10 by column B ascending
+     * const result = sheet.sortRange(
+     *   { startRow: 0, startCol: 0, endRow: 9, endCol: 2 },
+     *   { sortBy: [{ column: 1, direction: 'asc' }], hasHeaders: true }
+     * );
+     * if (result.success) {
+     *   console.log(`${result.data.rowsMoved} rows were reordered`);
+     * }
+     *
+     * // Multi-column sort: primary by column A, secondary by column C
+     * sheet.sortRange(range, {
+     *   sortBy: [
+     *     { column: 0, direction: 'asc' },
+     *     { column: 2, direction: 'desc' }
+     *   ],
+     *   hasHeaders: true
+     * });
+     * ```
+     */
+    sortRange(range: CellRange, options: ApiSortOptions): OperationResult<{
+        rowsMoved: number;
+    }> | OperationResult<{
+        dispatched: boolean;
+    }> | Promise<OperationResult<{
+        rowsMoved: number;
+    }>> | Promise<OperationResult<{
+        dispatched: boolean;
+    }>>;
+}
+/**
+ * Main spreadsheet API facade.
+ * Entry point for all spreadsheet operations.
+ */
+export interface ISpreadsheetAPI {
+    /**
+     * Get a SheetAPI for the specified sheet.
+     */
+    sheet(sheetId: string): ISheetAPI;
+    /**
+     * Get a SheetAPI for the currently active sheet.
+     */
+    activeSheet(): ISheetAPI | Promise<ISheetAPI>;
+    /**
+     * Create a new sheet with the given name.
+     */
+    createSheet(name: string): OperationResult<{
+        sheetId: string;
+    }> | Promise<OperationResult<{
+        sheetId: string;
+    }>>;
+    /**
+     * Delete a sheet.
+     */
+    deleteSheet(sheetId: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Rename a sheet.
+     */
+    renameSheet(sheetId: string, name: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Get all sheet IDs in order.
+     */
+    getSheetIds(): string[] | Promise<string[]>;
+    /**
+     * Get metadata for a sheet.
+     */
+    getSheetMeta(sheetId: string): SheetInfo | undefined | Promise<SheetInfo | undefined>;
+    /**
+     * Move a sheet to a new position.
+     * @param sheetId The sheet to move
+     * @param newIndex The zero-based target index
+     */
+    moveSheet(sheetId: string, newIndex: number): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Force a full recalculation of the workbook.
+     * Normally recalc happens automatically after each write.
+     */
+    recalc(): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Suspend automatic recalculation.
+     * While suspended, writes still go to the engine but intermediate
+     * recalc results are not applied to the store. Call `resumeCalc()`
+     * to trigger a single recalc and apply all changes.
+     */
+    suspendCalc(): void;
+    /**
+     * Resume automatic recalculation and trigger a full recalc.
+     * Applies all changes accumulated since `suspendCalc()`.
+     */
+    resumeCalc(): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Check if calculation is currently suspended.
+     */
+    isCalcSuspended(): boolean;
+    /**
+     * Execute multiple operations as a single undoable transaction.
+     */
+    batch(fn: (api: ISpreadsheetAPI) => void): OperationResult<void>;
+    /**
+     * Undo the last operation.
+     */
+    undo(): OperationResult<void>;
+    /**
+     * Redo the last undone operation.
+     */
+    redo(): OperationResult<void>;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Create a table from a range.
+     * @param sheetId Sheet to create the table in
+     * @param range Cell range for the table (startRow, startCol, endRow, endCol)
+     * @param options Optional table configuration
+     * @returns OperationResult with the table name on success
+     */
+    createTable(sheetId: string, range: {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    }, options?: {
+        name?: string;
+        hasHeaderRow?: boolean;
+        hasTotalRow?: boolean;
+        styleName?: string;
+    }): OperationResult<string> | Promise<OperationResult<string>>;
+    /**
+     * Get all tables in a sheet.
+     * @param sheetId Sheet identifier
+     * @returns Array of table info
+     */
+    getTables(sheetId: string): Array<{
+        name: string;
+        range: {
+            startRow: number;
+            startCol: number;
+            endRow: number;
+            endCol: number;
+        };
+        hasHeaderRow: boolean;
+        hasTotalRow: boolean;
+        styleName: string;
+        columns: string[];
+    }> | Promise<Array<{
+        name: string;
+        range: {
+            startRow: number;
+            startCol: number;
+            endRow: number;
+            endCol: number;
+        };
+        hasHeaderRow: boolean;
+        hasTotalRow: boolean;
+        styleName: string;
+        columns: string[];
+    }>>;
+    /**
+     * Get a specific table by name.
+     * @param sheetId Sheet identifier
+     * @param tableName Table name
+     * @returns Table info or undefined if not found
+     */
+    getTable(sheetId: string, tableName: string): {
+        name: string;
+        range: {
+            startRow: number;
+            startCol: number;
+            endRow: number;
+            endCol: number;
+        };
+        hasHeaderRow: boolean;
+        hasTotalRow: boolean;
+        styleName: string;
+        columns: string[];
+    } | undefined | Promise<{
+        name: string;
+        range: {
+            startRow: number;
+            startCol: number;
+            endRow: number;
+            endCol: number;
+        };
+        hasHeaderRow: boolean;
+        hasTotalRow: boolean;
+        styleName: string;
+        columns: string[];
+    } | undefined>;
+    /**
+     * Get the table containing a specific cell.
+     * @param sheetId Sheet identifier
+     * @param row Row index
+     * @param col Column index
+     * @returns Table config if cell is in a table, undefined otherwise
+     */
+    getTableAtCell(sheetId: string, row: number, col: number): TableConfig | undefined | Promise<TableConfig | undefined>;
+    /**
+     * Delete a table (keeps cell data).
+     * @param sheetId Sheet identifier
+     * @param tableName Table name
+     * @returns OperationResult indicating success or failure
+     */
+    deleteTable(sheetId: string, tableName: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Rename a table.
+     * @param sheetId Sheet identifier
+     * @param oldName Current table name
+     * @param newName New table name
+     * @returns OperationResult indicating success or failure
+     */
+    renameTable(sheetId: string, oldName: string, newName: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Toggle a table's total row.
+     * @param sheetId Sheet identifier
+     * @param tableName Table name
+     * @param show Whether to show the total row
+     * @returns OperationResult indicating success or failure
+     */
+    toggleTableTotalRow(sheetId: string, tableName: string, show: boolean): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Set total function for a table column.
+     * @param sheetId Sheet identifier
+     * @param tableName Table name
+     * @param columnName Column name
+     * @param func Total function to apply (uppercase: SUM, AVERAGE, etc. or lowercase)
+     * @returns OperationResult indicating success or failure
+     */
+    setTableTotalFunction(sheetId: string, tableName: string, columnName: string, func: 'AVERAGE' | 'COUNT' | 'COUNTA' | 'MAX' | 'MIN' | 'STDDEV' | 'SUM' | 'VAR' | 'none'): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Define a new named range.
+     * @param name The name (e.g., "SalesData", "TaxRate")
+     * @param refersTo A1-style reference (e.g., "=Sheet1!$A$1:$B$10")
+     * @param options Optional scope and comment
+     */
+    defineName(name: string, refersTo: string, options?: {
+        scope?: string;
+        comment?: string;
+    }): OperationResult<{
+        id: string;
+        name: string;
+    }> | Promise<OperationResult<{
+        id: string;
+        name: string;
+    }>>;
+    /**
+     * Get all defined names.
+     */
+    getDefinedNames(): Array<{
+        id: string;
+        name: string;
+        refersToA1: string;
+        scope?: string;
+        comment?: string;
+    }> | Promise<Array<{
+        id: string;
+        name: string;
+        refersToA1: string;
+        scope?: string;
+        comment?: string;
+    }>>;
+    /**
+     * Get a specific defined name by name.
+     * @param name The name to find
+     * @param scope Optional scope (undefined = workbook scope)
+     */
+    getDefinedName(name: string, scope?: string): {
+        id: string;
+        name: string;
+        refersToA1: string;
+        scope?: string;
+        comment?: string;
+    } | undefined | Promise<{
+        id: string;
+        name: string;
+        refersToA1: string;
+        scope?: string;
+        comment?: string;
+    } | undefined>;
+    /**
+     * Update a defined name.
+     * @param id The ID of the name to update
+     * @param updates Fields to update
+     */
+    updateDefinedName(id: string, updates: {
+        name?: string;
+        refersTo?: string;
+        comment?: string;
+    }): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Delete a defined name.
+     * @param id The ID of the name to delete
+     */
+    deleteDefinedName(id: string): OperationResult<void> | Promise<OperationResult<void>>;
+    /**
+     * Validate a potential name (without creating it).
+     * @param name The name to validate
+     * @param scope Optional scope
+     */
+    validateDefinedName(name: string, scope?: string): {
+        valid: boolean;
+        error?: string;
+        message?: string;
+    } | Promise<{
+        valid: boolean;
+        error?: string;
+        message?: string;
+    }>;
+    /**
+     * Get a snapshot of the workbook state.
+     * Useful for understanding what exists before making changes.
+     */
+    getWorkbookSnapshot(): WorkbookSnapshot | Promise<WorkbookSnapshot>;
+    /**
+     * Get all available spreadsheet functions.
+     */
+    getFunctionCatalog(): FunctionInfo[];
+    /**
+     * Get detailed info about a specific function.
+     */
+    getFunctionInfo(name: string): FunctionInfo | undefined;
+    /**
+     * Subscribe to spreadsheet events.
+     * Returns an unsubscribe function.
+     */
+    on<K extends SpreadsheetEventType>(eventType: K, handler: (event: Extract<SpreadsheetEvent, {
+        type: K;
+    }>) => void): () => void;
+    /**
+     * Execute AI-generated code in a sandboxed Web Worker.
+     *
+     * This method provides secure code execution for AI agents. The code runs
+     * in an isolated Web Worker with no DOM access, no localStorage, and
+     * no network access. All spreadsheet operations go through the API.
+     *
+     * The code has access to:
+     * - `workbook` - Async proxy to SpreadsheetAPI
+     * - `store` - Persistent key-value store between executions
+     * - `console` - Console methods (captured and returned in logs)
+     *
+     * @param code - TypeScript/JavaScript code to execute
+     * @param options - Execution options (timeout, store, etc.)
+     * @returns Execution result with affected cells, logs, and timing
+     *
+     * @example
+     * ```typescript
+     * const result = await api.executeCode(`
+     *   const sheet = await workbook.activeSheet();
+     *   await sheet.setCell(0, 0, "Hello from AI!");
+     *   await sheet.setRange(1, 0, [
+     *     ["Name", "Score"],
+     *     ["Alice", 100],
+     *     ["Bob", 95],
+     *   ]);
+     *   console.log("Done!");
+     * `);
+     *
+     * if (result.status === 'success') {
+     *   console.log(`Modified ${result.changeCount} cells`);
+     *   console.log(`Logs: ${result.logs.join('\n')}`);
+     * } else {
+     *   console.error(`Error: ${result.error}`);
+     * }
+     * ```
+     */
+    executeCode(code: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+}
+export type { ApiError, ApiErrorCode } from './api-errors';
+export type { CellAddress, CellData, CellFormat, CellRange, CellValue, CellValuePrimitive };
+//# sourceMappingURL=api.d.ts.map