Quick Start

A complete walkthrough: connect to Lona and read sheet data.

1. Set up authentication

export LONA_ACCESS_TOKEN="lona_pat_..."

2. Create a client

import { LonaSdk, SheetPlatform } from "@tento-lona";

const client = new LonaSdk.Client({
  accessToken: process.env.LONA_ACCESS_TOKEN,
  storage: localStorage,
  platform: SheetPlatform.TEST,
});

3. List your sheets

const sheets = await client.sheets.list();

for (const sheet of sheets) {
  console.log(`${sheet.id} — ${sheet.title}`);
}

4. Open a sheet

const handle = await client.open(sheets[0].id.toString());
console.log(`Opened: ${handle.title}`);

5. Read the row tree

Every sheet has a tree of rows. Use handle.tree() to get the resolved tree (with virtual children expanded):

const tree = handle.tree();

// Pretty-print the tree
console.log(tree.print(node => {
  const row = handle.row(node.id.toString());
  const type = row?.type ?? "?";
  const label = row?.label ? ` "${row.label}"` : "";
  return `[${type}]${label}`;
}));

Example output:

├── [header] "Header"
├── [calendar] "Work"
│   ├── [calendar-list]
│   └── [timeline]
├── [weather] "Weather"
│   ├── [data-canvas]
│   └── [data-series]
└── [text] "Notes"

6. Access row metadata

for (const row of handle.rows.list) {
  console.log(`${row.type}: ${row.label ?? "(no label)"}`);
  console.log(`  timescale: ${row.timeScale}`);
  console.log(`  lookupKey: ${row.lookupKey}`);
}

7. Navigate parent/child relationships

const tree = handle.tree();

// Get children of a specific node
const firstNode = tree.nodes[0];
const children = tree.children(firstNode.id);
console.log(`${firstNode.id} has ${children.length} children`);

// Find a node's parent
for (const child of children) {
  const parentId = tree.parent(child.id);
  console.log(`  ${child.id} → parent: ${parentId}`);
}

8. Serialize back to wire format

const data = handle.serialize();
console.log(JSON.stringify(data, null, 2));

Full example

import { LonaSdk, SheetPlatform } from "@tento-lona";

const client = new LonaSdk.Client({
  accessToken: process.env.LONA_ACCESS_TOKEN,
  storage: localStorage,
  platform: SheetPlatform.TEST,
});

const sheets = await client.sheets.list();

for (const s of sheets) {
  const handle = await client.open(s.id.toString());
  const tree = handle.tree();

  console.log(`\n=== ${handle.title ?? s.id} ===`);
  console.log(tree.print(node => {
    const row = handle.row(node.id.toString());
    const lookupKey = row?.lookupKey ? ` (${row.lookupKey})` : "";
    return `[${row?.type}]${lookupKey}`;
  }));
}

See also

• Client Architecture — configuration options
• Sheets — listing and opening sheets
• Rows — row types and tree navigation
• Cells — reading, writing, and progressive cell loading