# @mog-sdk/sdk

Headless spreadsheet engine for Node.js. 582 spreadsheet formula functions, XLSX import/export, charts, tables, pivots, and conditional formatting, all powered by a native Rust engine.

## API Discovery

This SDK includes a built-in introspection API. Use it to explore the full API surface programmatically — no need to read type definitions:

```typescript
import { api } from '@mog-sdk/sdk';

// Overview: list all methods and sub-APIs
api.describe()
// → { workbook: { methods: [...], subApis: ['sheets','history','names',...] },
//     worksheet: { methods: [...], subApis: ['charts','formats','tables',...] } }

// Drill into a sub-API
api.describe('ws.charts')
// → { name: 'WorksheetCharts', methods: [{ name: 'add', signature: '...', tags: ['action'] }, ...] }

// Get a specific method with full type info
api.describe('ws.charts.add')
// → { name: 'add', signature: '...', tags: ['action'], types: { ChartConfig: { definition: '...' } } }

// Direct methods on root interfaces
api.describe('ws.setCell')
api.describe('wb.batch')

// Look up a type definition
api.describe('type:ChartType')
```

Paths use `wb.*` for workbook and `ws.*` for worksheet. Sub-APIs are accessed as `ws.{subApi}.{method}`.

## Agent API Guidance

When generating Mog code, use `api.describe(...)` for valid Mog methods and
`api.guidance` for source preflight and wrong-dialect explanations:

```typescript
api.describe('ws.tables.add')
api.describe('ws.filters.setColumnFilter')
api.guidance.analyze(source)
api.guidance.explain('context.workbook.worksheets.getActiveWorksheet')
api.guidance.explain('wb.activeSheet')
api.guidance.preflight(source)
```

For each diagnostic, inspect `diagnostic.mogReplacements` for replacement
paths/snippets and `diagnostic.references` for follow-up `api.guidance.explain`
queries.

Code shaped like the Microsoft Office JavaScript spreadsheet API is diagnosed,
not supported. Do not use `Excel.run`, `Office.context`, `context.sync()`,
`.load(...)`, `.isNullObject`, Range proxy assignment such as
`range.values = data`, or `range.format.fill.color`. Use Mog-native APIs such
as the injected `wb` object, `const ws = wb.activeSheet`,
`await wb.getSheet(name)`, `await ws.setRange(range, data)`, and
`await ws.formats.setRange(range, format)`.

## Quick Start

```typescript
import { createWorkbook } from '@mog-sdk/sdk';

const wb = await createWorkbook();
const ws = wb.activeSheet;

// Write cells (formulas auto-recalc)
await ws.setCell('A1', 100);
await ws.setCell('A2', 200);
await ws.setCell('A3', '=SUM(A1:A2)');
console.log(await ws.getValue('A3')); // 300

// Bulk write
await ws.setRange('B1', [['Name', 'Score'], ['Alice', 92], ['Bob', 85]]);

// Read
const data = await ws.getData();           // CellValue[][]
const csv = await ws.toCSV();              // RFC 4180 CSV string
const json = await ws.toJSON();            // [{ Name: 'Alice', Score: 92 }, ...]
await ws.describeRange('A1:B3');           // LLM-friendly text summary

// Always dispose when done
await wb.dispose();
```

## Open & Save XLSX

```typescript
import { createWorkbook } from '@mog-sdk/sdk';

// Open from file path or buffer
const wb = await createWorkbook('data.xlsx');
const wb = await createWorkbook(readFileSync('data.xlsx'));
const wb = await createWorkbook('data.xlsx', { valuesOnly: true });

// Save to file path or buffer
await wb.save('output.xlsx');         // writes file, returns buffer
const buf = await wb.save();          // buffer only
const buf = await wb.toXlsx();        // same as save() without side effects
```

## Sub-API Examples

```typescript
// Sheets
await wb.sheets.add('Sheet2');
await wb.sheets.rename('Sheet1', 'Sales');
await wb.getOrCreateSheet('Data');          // idempotent sheet access

// Tables
await ws.tables.add('A1:C10', { name: 'Sales', hasHeaders: true });

// Filters
await ws.filters.add('A1:C10');
await ws.filters.setColumnFilter(0, { type: 'value', values: ['Widget'] });

// Charts
await ws.charts.add({ type: 'bar', dataRange: 'A1:B5' });

// Formatting
await ws.formats.set('A1', { bold: true, fontColor: '#FF0000' });

// Structure
await ws.structure.insertRows(5, 3);
await ws.structure.merge('A1:B1');

// History
await wb.history.undo();
await wb.history.redo();

// LLM helpers
await ws.summarize();                      // LLM-friendly sheet overview
await ws.describe('A1');                   // cell description with formula
await ws.describeRange('A1:D5');           // tabular text summary
```
