5. Building tools for LeavenIT

This chapter is for the AI that writes a tool, and for the person who asks it. A LeavenIT tool is one self-contained HTML file. When it runs inside LeavenIT, it gets an object window.leavenit to save data and to work with tables. Outside LeavenIT, the same file must still work.

5.1 The rules of the tool page

LeavenIT runs every tool in a sealed frame on another domain (leavenit-tools.com). What this means for the code:

5.2 Saving data: window.leavenit

const lv = window.leavenit;   // undefined when the file is opened outside LeavenIT

All methods return Promises.

• Keys: 1 to 200 characters. Use prefixes to group them: notes/2026-10-27, settings.
• Pace: about 20 requests per second at most; beyond, calls fail with rate_limited. Save on change with a short delay, not on every keystroke.
• Never rename a key once people use the tool: their data stays under the old key. Add a schema_version field inside values to migrate formats.
• lv.connected is true when the person is signed in and the data is saved on LeavenIT; false for a visitor (data then lives in memory only, until the page closes).
• lv.version is the version of this interface (currently 1).

Personal and shared data

By default, data belongs to the person (scope: 'me'). When the tool is opened inside a shared folder, it can also use the data of that folder, shared by its members:

await lv.set('menu', items, { scope: 'shared' });
const menu = await lv.get('menu', { scope: 'shared' });

lv.context tells where the tool is opened:

// { type: 'me' }   or
// { type: 'group', group: { id, name, role, memberCount }, space: { id, name }, permission: 'read' | 'write', canWrite: true | false }
if (lv.context.type === 'group' && !lv.context.canWrite) hideEditButtons();

Not overwriting someone else's change

For shared values that several people edit (these options apply to scope: 'shared' only), read with withMeta, then write with ifVersion:

const cur = await lv.get('menu', { scope: 'shared', withMeta: true });   // { value, version, updatedAt, updatedBy }
try {
  await lv.set('menu', updated, { scope: 'shared', ifVersion: cur.version });   // returns { version }
} catch (e) {
  if (e.code === 'conflict') showMessage('Someone changed the menu. Reload to see their version.');
}

For shared data, lv.list(prefix, { scope: 'shared', limit, after }) pages through long lists (limit up to 1000, after = the last key received).

The fallback to use in every tool

const store = window.leavenit ?? {
  get: async (k) => JSON.parse(localStorage.getItem(k) ?? 'null'),
  set: async (k, v) => localStorage.setItem(k, JSON.stringify(v)),
  delete: async (k) => localStorage.removeItem(k),
  list: async (p = '') => Object.keys(localStorage).filter((k) => k.startsWith(p)).map((k) => ({ key: k, value: JSON.parse(localStorage.getItem(k)) })),
};

Errors (e.code, e.message)

5.3 Tables: window.leavenit.sql

For large data (thousands to millions of rows), tools use tables. window.leavenit.sql exists only when tables are available on the person's account: always check it.

const sql = window.leavenit?.sql;
if (!sql) showMessage('Tables are not available here.');

// A typical read: the 10 best sellers, with a parameter
const r = await sql.query('orders', 'select item, sum(qty) as total from data where shop = ? group by item order by total desc limit 10', [shop]);

Table names: lowercase letters, digits and _, starting with a letter (orders_2026).

The SQL dialect (SQLite 3.49)

• The whole block script is one transaction: all or nothing.
• Allowed: SELECT, WITH, VALUES, INSERT, UPDATE, DELETE, REPLACE, CREATE TABLE / INDEX / VIEW, DROP, ALTER, ANALYZE, EXPLAIN. Refused: PRAGMA, ATTACH, DETACH, VACUUM, transactions, triggers, virtual tables.
• Imported columns are text, and empty cells are '', not NULL: use nullif(x, '').
• Clean values with the functions LeavenIT adds: to_number(x) ('1 250,50 €' → 1250.5, 'n/a' → NULL), to_date(x) (dd/mm/yyyy, yyyy-mm-dd, '4 Mar 2026' → 'yyyy-mm-dd'), upper(x) and lower(x) (Unicode), regexp_replace(text, pattern, replacement) (JavaScript regular expressions).
• Don't clean with CAST: CAST('n/a' AS INTEGER) gives 0 silently. Use to_number.
• 7/2 gives 3: write 7*1.0/2. Always add ORDER BY after GROUP BY. No ILIKE (use lower(x) LIKE …), no ::, no QUALIFY, no try_cast. Window functions, WITH and FULL JOIN work.

Table errors

5.4 The prompt to give your AI

People can paste this into the AI that writes their tool:

Write a single self-contained HTML file. It must work offline and without any network request. Libraries only from cdnjs, jsdelivr, unpkg or esm.sh. No remote images. Don't use alert(), confirm() or prompt(): show messages inside the page. To save data, use window.leavenit if it exists (async get(key, options), set(key, value, options), delete(key, options), list(prefix, options)), otherwise localStorage. Never rename existing data keys. For data shared with a group, use { scope: 'shared' }, check window.leavenit.context.canWrite before showing edit buttons, and pass { ifVersion } when updating a shared value. For large data, use window.leavenit.sql if it exists (tables, preview, query with the table always called data, importFile, export, undo); its SQL dialect is SQLite 3.49 with to_number, to_date and regexp_replace.