zitejs 0.9.50 → 0.9.52

package/dist/cjs/dev/index.js

@@ -15,18 +15,18 @@ function debounce(key, fn, ms) {
     debounceTimers.set(key, setTimeout(fn, ms));
 }
 function findAppDirs() {
-    const appsDir = 'apps';
+    const appsDir = "apps";
     if (!(0, fs_2.existsSync)(appsDir))
         return [];
     return (0, fs_2.readdirSync)(appsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
 }
 function getFlowId(appDir) {
     try {
-        const configPath = (0, path_1.join)('apps', appDir, 'zite.config.json');
+        const configPath = (0, path_1.join)("apps", appDir, "zite.config.json");
         if ((0, fs_2.existsSync)(configPath)) {
-            const config = JSON.parse((0, fs_2.readFileSync)(configPath, 'utf-8'));
+            const config = JSON.parse((0, fs_2.readFileSync)(configPath, "utf-8"));
             return config.id;
         }
     }
@@ -34,32 +34,32 @@ function getFlowId(appDir) {
     return undefined;
 }
 function regenerateAppTypedWrappers(appDir) {
-    const outDir = (0, path_1.join)('apps', appDir, '.zite');
+    const outDir = (0, path_1.join)("apps", appDir, ".zite");
     (0, fs_2.mkdirSync)(outDir, { recursive: true });
-    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, 'user.ts'), (0, lib_js_1.generateUserTs)());
-    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, 'auth.ts'), (0, lib_js_1.generateAuthWrapperTs)());
-    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, 'backend.ts'), (0, lib_js_1.generateBackendWrapperTs)());
+    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, "user.ts"), (0, lib_js_1.generateUserTs)());
+    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, "auth.ts"), (0, lib_js_1.generateAuthWrapperTs)());
+    (0, fs_2.writeFileSync)((0, path_1.join)(outDir, "backend.ts"), (0, lib_js_1.generateBackendWrapperTs)());
 }
 function regenerateAppApiTs(appDir) {
-    const apiDir = (0, path_1.join)('apps', appDir, 'src', 'api');
+    const apiDir = (0, path_1.join)("apps", appDir, "src", "api");
     if (!(0, fs_2.existsSync)(apiDir))
         return;
-    const endpointFiles = (0, fs_2.readdirSync)(apiDir).filter((f) => f.endsWith('.ts') || f.endsWith('.js'));
+    const endpointFiles = (0, fs_2.readdirSync)(apiDir).filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
     const content = (0, lib_js_1.generateApiTs)(endpointFiles);
     if (content) {
-        const outDir = (0, path_1.join)('apps', appDir, '.zite');
+        const outDir = (0, path_1.join)("apps", appDir, ".zite");
         (0, fs_2.mkdirSync)(outDir, { recursive: true });
-        (0, fs_2.writeFileSync)((0, path_1.join)(outDir, 'api.ts'), content);
+        (0, fs_2.writeFileSync)((0, path_1.join)(outDir, "api.ts"), content);
         console.log(`Updated apps/${appDir}/.zite/api.ts`);
     }
 }
 function regenerateAppAirtableSdk(appDir) {
-    const lockPath = (0, path_1.join)('apps', appDir, 'zite.lock');
+    const lockPath = (0, path_1.join)("apps", appDir, "zite.lock");
     console.log(`[airtable-sdk] Checking ${lockPath} exists: ${(0, fs_2.existsSync)(lockPath)}`);
     if (!(0, fs_2.existsSync)(lockPath))
         return;
     try {
-        const lockContent = JSON.parse((0, fs_2.readFileSync)(lockPath, 'utf-8'));
+        const lockContent = JSON.parse((0, fs_2.readFileSync)(lockPath, "utf-8"));
         const integrations = lockContent.integrations ?? {};
         console.log(`[airtable-sdk] Found ${Object.keys(integrations).length} integrations in lock:`, Object.keys(integrations));
         for (const [integrationId, integration] of Object.entries(integrations)) {
@@ -75,9 +75,9 @@ function regenerateAppAirtableSdk(appDir) {
             };
             const content = (0, lib_js_1.generateAirtableTs)(airtableLock);
             if (content) {
-                const outDir = (0, path_1.join)('apps', appDir, '.zite', 'integrations');
+                const outDir = (0, path_1.join)("apps", appDir, ".zite", "integrations");
                 (0, fs_2.mkdirSync)(outDir, { recursive: true });
-                (0, fs_2.writeFileSync)((0, path_1.join)(outDir, 'airtable.ts'), content);
+                (0, fs_2.writeFileSync)((0, path_1.join)(outDir, "airtable.ts"), content);
                 console.log(`Updated apps/${appDir}/.zite/integrations/airtable.ts`);
             }
         }
@@ -96,16 +96,16 @@ async function runGenerate() {
     // metadata from the backend API).
     // 1. Generate root .zite/db.ts from zite.schema.json
     try {
-        if ((0, fs_2.existsSync)('zite.schema.json')) {
-            const schema = JSON.parse((0, fs_2.readFileSync)('zite.schema.json', 'utf-8'));
+        if ((0, fs_2.existsSync)("zite.schema.json")) {
+            const schema = JSON.parse((0, fs_2.readFileSync)("zite.schema.json", "utf-8"));
             const dbTs = (0, lib_js_1.generateDbTs)(schema);
-            (0, fs_2.mkdirSync)('.zite', { recursive: true });
-            (0, fs_2.writeFileSync)((0, path_1.join)('.zite', 'db.ts'), dbTs);
-            console.log('Wrote .zite/db.ts');
+            (0, fs_2.mkdirSync)(".zite", { recursive: true });
+            (0, fs_2.writeFileSync)((0, path_1.join)(".zite", "db.ts"), dbTs);
+            console.log("Wrote .zite/db.ts");
         }
     }
     catch (err) {
-        console.warn('DB SDK generation failed:', err instanceof Error ? err.message : err);
+        console.warn("DB SDK generation failed:", err instanceof Error ? err.message : err);
     }
     // 2. Find all apps and regenerate their .zite/ files
     const appDirs = findAppDirs();
@@ -114,20 +114,20 @@ async function runGenerate() {
         regenerateAppTypedWrappers(app);
         regenerateAppAirtableSdk(app);
     }
-    console.log('Done!');
+    console.log("Done!");
 }
 async function runDev() {
-    const env = process.env.ZITE_ENV ?? 'production';
+    const env = process.env.ZITE_ENV ?? "production";
     console.log(`zitejs dev — environment: ${env}`);
-    console.log('');
+    console.log("");
     // 1. Run initial sync (generates root .zite/db.ts)
     try {
         await (0, index_js_1.runSync)();
     }
     catch (err) {
-        console.warn('Initial sync failed (continuing with watcher):', err instanceof Error ? err.message : err);
+        console.warn("Initial sync failed (continuing with watcher):", err instanceof Error ? err.message : err);
     }
-    console.log('');
+    console.log("");
     // 2. Find all apps and regenerate their .zite/ files
     const appDirs = findAppDirs();
     for (const app of appDirs) {
@@ -137,7 +137,7 @@ async function runDev() {
     // 3. Watch each app's src/api/ for endpoint changes
     let watchingAny = false;
     for (const app of appDirs) {
-        const apiDir = (0, path_1.join)('apps', app, 'src', 'api');
+        const apiDir = (0, path_1.join)("apps", app, "src", "api");
         if (!(0, fs_2.existsSync)(apiDir))
             continue;
         watchingAny = true;
@@ -145,7 +145,7 @@ async function runDev() {
         (0, fs_1.watch)(apiDir, { recursive: true }, (_event, filename) => {
             if (!filename)
                 return;
-            if (!filename.endsWith('.ts') && !filename.endsWith('.js'))
+            if (!filename.endsWith(".ts") && !filename.endsWith(".js"))
                 return;
             debounce(app, () => {
                 console.log(`Endpoint changed in ${app}: ${filename}`);
@@ -154,24 +154,24 @@ async function runDev() {
         });
     }
     if (!watchingAny) {
-        console.log('No apps with src/api/ found.');
+        console.log("No apps with src/api/ found.");
     }
     // 4. Watch zite.schema.json for schema drift
-    if ((0, fs_2.existsSync)('zite.schema.json')) {
-        console.log('Watching zite.schema.json for schema changes...');
-        (0, fs_1.watch)('zite.schema.json', () => {
-            debounce('schema', async () => {
-                console.log('Schema changed — re-running sync...');
+    if ((0, fs_2.existsSync)("zite.schema.json")) {
+        console.log("Watching zite.schema.json for schema changes...");
+        (0, fs_1.watch)("zite.schema.json", () => {
+            debounce("schema", async () => {
+                console.log("Schema changed — re-running sync...");
                 try {
                     await (0, index_js_1.runSync)();
                 }
                 catch (err) {
-                    console.error('Re-sync failed:', err instanceof Error ? err.message : err);
+                    console.error("Re-sync failed:", err instanceof Error ? err.message : err);
                 }
             }, 500);
         });
     }
-    console.log('');
-    console.log('Ready. Watching for changes... (Ctrl+C to stop)');
+    console.log("");
+    console.log("Ready. Watching for changes... (Ctrl+C to stop)");
     await new Promise(() => { });
 }

package/dist/cjs/sync/lib.d.ts

@@ -40,11 +40,13 @@ export type AirtableLockField = {
     id: string;
     sdkName: string;
     type: string;
-    options?: string[];
+    name: string;
+    config?: Record<string, unknown>;
 };
 export type AirtableLockTable = {
     id: string;
     sdkName: string;
+    primaryFieldId: string;
     fields: AirtableLockField[];
 };
 export type AirtableLock = {

package/dist/cjs/sync/lib.js

@@ -106,9 +106,7 @@ function fieldJsdoc(schemaField, table) {
     }
     if (def.type === "datetime") {
         const tpl = def.template;
-        const timeParts = [
-            "Date+time field (ISO 8601 timestamp)",
-        ];
+        const timeParts = ["Date+time field (ISO 8601 timestamp)"];
         if (tpl.dateFormat)
             timeParts.push(`date: ${tpl.dateFormat}`);
         if (tpl.timeFormat)
@@ -156,7 +154,8 @@ function fieldJsdoc(schemaField, table) {
     }
     if ((def.type === "single_select" || def.type === "multiple_select") &&
         def.template?.options) {
-        const count = (def.template.options ?? []).length;
+        const count = (def.template.options ?? [])
+            .length;
         if (count > MAX_SELECT_OPTIONS) {
             parts.push(`${count - MAX_SELECT_OPTIONS} more options omitted`);
         }
@@ -395,11 +394,12 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     externalSyncSource: "unknown",
     aiText: "string",
 };
-function airtableTsType(field) {
+function airtableTsType(field, lock, depth) {
+    const choices = field.config?.choices;
     if ((field.type === "singleSelect" || field.type === "multipleSelects") &&
-        field.options &&
-        field.options.length > 0) {
-        const literals = field.options
+        choices &&
+        choices.length > 0) {
+        const literals = choices
             .slice(0, MAX_SELECT_OPTIONS)
             .map((o) => `"${o.replace(/"/g, '\\"')}"`)
             .join(" | ");
@@ -408,15 +408,121 @@ function airtableTsType(field) {
             return `(${union})[]`;
         return union;
     }
+    if (field.type === "multipleLookupValues" && lock && (depth ?? 0) < 5) {
+        const linkFieldId = field.config?.recordLinkFieldId;
+        const targetFieldId = field.config?.fieldIdInLinkedTable;
+        if (linkFieldId && targetFieldId) {
+            const table = lock.tables.find((t) => t.fields.some((f) => f.id === linkFieldId));
+            const linkField = table?.fields.find((f) => f.id === linkFieldId);
+            const linkedTableId = linkField?.config?.linkedTableId;
+            if (linkedTableId) {
+                const linkedTable = lock.tables.find((t) => t.id === linkedTableId);
+                const targetField = linkedTable?.fields.find((f) => f.id === targetFieldId);
+                if (targetField) {
+                    const resolved = airtableTsType(targetField, lock, (depth ?? 0) + 1);
+                    return `${resolved}[] | undefined`;
+                }
+            }
+        }
+    }
     return AIRTABLE_FIELD_TYPE_MAP[field.type] ?? "unknown";
 }
+const READ_ONLY_AIRTABLE_FIELDS = new Set([
+    "autoNumber",
+    "count",
+    "formula",
+    "rollup",
+    "multipleLookupValues",
+    "createdTime",
+    "lastModifiedTime",
+    "createdBy",
+    "lastModifiedBy",
+    "button",
+    "externalSyncSource",
+    "aiText",
+]);
+function airtableFieldJsdoc(field, table) {
+    const parts = [];
+    if (table.primaryFieldId === field.id)
+        parts.push("Primary field");
+    if (READ_ONLY_AIRTABLE_FIELDS.has(field.type))
+        parts.push("Read-only; do not write");
+    if (field.type === "multipleRecordLinks") {
+        const linkedTableId = field.config?.linkedTableId;
+        if (linkedTableId)
+            parts.push(`Links to table ${linkedTableId}`);
+        if (field.config?.prefersSingleRecordLink)
+            parts.push("Single record only");
+    }
+    if (field.type === "multipleLookupValues")
+        parts.push("Lookup: value is an array — index or aggregate when displaying");
+    if (field.type === "percent")
+        parts.push("Raw decimal — multiply by 100 for display percentage");
+    parts.push(`"${field.name}"`);
+    if (field.type === "currency") {
+        const symbol = field.config?.symbol;
+        const precision = field.config?.precision;
+        if (symbol)
+            parts.push(`Display as currency with "${symbol}", ${precision ?? 2} decimals`);
+    }
+    if (field.type === "date") {
+        const fmt = field.config?.dateFormat;
+        if (fmt)
+            parts.push(`Date-only (ISO string), display as "${fmt}"`);
+    }
+    if (field.type === "dateTime") {
+        const dateFmt = field.config?.dateFormat;
+        const timeFmt = field.config?.timeFormat;
+        const tz = field.config?.timeZone;
+        const fmtParts = ["Date+time (ISO string)"];
+        if (dateFmt)
+            fmtParts.push(`date: ${dateFmt}`);
+        if (timeFmt)
+            fmtParts.push(`time: ${timeFmt}`);
+        if (tz)
+            fmtParts.push(`tz: ${tz}`);
+        parts.push(fmtParts.join(", "));
+    }
+    if (field.type === "rating") {
+        const max = field.config?.max;
+        if (max)
+            parts.push(`Max: ${max}`);
+    }
+    if (field.type === "duration") {
+        const fmt = field.config?.format;
+        if (fmt)
+            parts.push(`Value in seconds, display as "${fmt}"`);
+    }
+    if (field.type === "number" || field.type === "percent") {
+        const precision = field.config?.precision;
+        if (precision != null)
+            parts.push(`${precision} decimal places`);
+    }
+    if (parts.length <= 1)
+        return undefined;
+    return parts.join(". ");
+}
 function generateAirtableTs(lock) {
     if (lock.tables.length === 0)
         return null;
     const lines = [
         "// Auto-generated by zitejs generate from zite.lock. Do not edit manually.",
         "// Airtable SDK — uses createAirtableClient from zitejs/runtime.",
-        "// The airtable package is externalized (not bundled per-endpoint).",
+        "//",
+        "// Each exported table client has these methods:",
+        "//   findAll(options?: { offset?: string; limit?: number; filters?: unknown })",
+        "//     => Promise<{ records: T[]; offset: string | undefined; hasMore: boolean }>",
+        "//   findOne(params: { id?: string; filters?: unknown }) => Promise<T | undefined>",
+        "//   create(data: { record: Partial<T> }) => Promise<T>",
+        "//   bulkCreate(records: Partial<T>[]) => Promise<T[]>",
+        "//   update(id: string, data: { record: Partial<T> }) => Promise<T>",
+        "//   delete(id: string) => Promise<{ deleted: true }>",
+        "//",
+        "// Usage tips:",
+        "//   - Airtable has a strict rate limit of 5 requests/second per base",
+        "//   - Use bulkCreate() instead of calling create() in a loop",
+        "//   - findAll() offsets are opaque strings from previous calls, NOT numbers",
+        "//   - Always destructure record properties individually in create/update calls",
         "",
         "import { createAirtableClient } from 'zitejs/runtime';",
         "",
@@ -428,7 +534,11 @@ function generateAirtableTs(lock) {
         for (const field of table.fields) {
             if (field.sdkName === "id")
                 continue;
-            const tsType = airtableTsType(field);
+            const jsdoc = airtableFieldJsdoc(field, table);
+            if (jsdoc) {
+                lines.push(`  /** ${jsdoc} */`);
+            }
+            const tsType = airtableTsType(field, lock);
             lines.push(`  ${field.sdkName}: ${tsType};`);
         }
         lines.push("};");

package/dist/esm/dev/index.js

@@ -1,8 +1,8 @@
-import { watch } from 'fs';
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, } from 'fs';
-import { join } from 'path';
-import { runSync } from '../sync/index.js';
-import { generateDbTs, generateApiTs, generateUserTs, generateAuthWrapperTs, generateBackendWrapperTs, generateAirtableTs, } from '../sync/lib.js';
+import { watch } from "fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, } from "fs";
+import { join } from "path";
+import { runSync } from "../sync/index.js";
+import { generateDbTs, generateApiTs, generateUserTs, generateAuthWrapperTs, generateBackendWrapperTs, generateAirtableTs, } from "../sync/lib.js";
 const debounceTimers = new Map();
 function debounce(key, fn, ms) {
     const existing = debounceTimers.get(key);
@@ -11,18 +11,18 @@ function debounce(key, fn, ms) {
     debounceTimers.set(key, setTimeout(fn, ms));
 }
 function findAppDirs() {
-    const appsDir = 'apps';
+    const appsDir = "apps";
     if (!existsSync(appsDir))
         return [];
     return readdirSync(appsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .map(d => d.name);
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
 }
 function getFlowId(appDir) {
     try {
-        const configPath = join('apps', appDir, 'zite.config.json');
+        const configPath = join("apps", appDir, "zite.config.json");
         if (existsSync(configPath)) {
-            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const config = JSON.parse(readFileSync(configPath, "utf-8"));
             return config.id;
         }
     }
@@ -30,32 +30,32 @@ function getFlowId(appDir) {
     return undefined;
 }
 function regenerateAppTypedWrappers(appDir) {
-    const outDir = join('apps', appDir, '.zite');
+    const outDir = join("apps", appDir, ".zite");
     mkdirSync(outDir, { recursive: true });
-    writeFileSync(join(outDir, 'user.ts'), generateUserTs());
-    writeFileSync(join(outDir, 'auth.ts'), generateAuthWrapperTs());
-    writeFileSync(join(outDir, 'backend.ts'), generateBackendWrapperTs());
+    writeFileSync(join(outDir, "user.ts"), generateUserTs());
+    writeFileSync(join(outDir, "auth.ts"), generateAuthWrapperTs());
+    writeFileSync(join(outDir, "backend.ts"), generateBackendWrapperTs());
 }
 function regenerateAppApiTs(appDir) {
-    const apiDir = join('apps', appDir, 'src', 'api');
+    const apiDir = join("apps", appDir, "src", "api");
     if (!existsSync(apiDir))
         return;
-    const endpointFiles = readdirSync(apiDir).filter((f) => f.endsWith('.ts') || f.endsWith('.js'));
+    const endpointFiles = readdirSync(apiDir).filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
     const content = generateApiTs(endpointFiles);
     if (content) {
-        const outDir = join('apps', appDir, '.zite');
+        const outDir = join("apps", appDir, ".zite");
         mkdirSync(outDir, { recursive: true });
-        writeFileSync(join(outDir, 'api.ts'), content);
+        writeFileSync(join(outDir, "api.ts"), content);
         console.log(`Updated apps/${appDir}/.zite/api.ts`);
     }
 }
 function regenerateAppAirtableSdk(appDir) {
-    const lockPath = join('apps', appDir, 'zite.lock');
+    const lockPath = join("apps", appDir, "zite.lock");
     console.log(`[airtable-sdk] Checking ${lockPath} exists: ${existsSync(lockPath)}`);
     if (!existsSync(lockPath))
         return;
     try {
-        const lockContent = JSON.parse(readFileSync(lockPath, 'utf-8'));
+        const lockContent = JSON.parse(readFileSync(lockPath, "utf-8"));
         const integrations = lockContent.integrations ?? {};
         console.log(`[airtable-sdk] Found ${Object.keys(integrations).length} integrations in lock:`, Object.keys(integrations));
         for (const [integrationId, integration] of Object.entries(integrations)) {
@@ -71,9 +71,9 @@ function regenerateAppAirtableSdk(appDir) {
             };
             const content = generateAirtableTs(airtableLock);
             if (content) {
-                const outDir = join('apps', appDir, '.zite', 'integrations');
+                const outDir = join("apps", appDir, ".zite", "integrations");
                 mkdirSync(outDir, { recursive: true });
-                writeFileSync(join(outDir, 'airtable.ts'), content);
+                writeFileSync(join(outDir, "airtable.ts"), content);
                 console.log(`Updated apps/${appDir}/.zite/integrations/airtable.ts`);
             }
         }
@@ -92,16 +92,16 @@ export async function runGenerate() {
     // metadata from the backend API).
     // 1. Generate root .zite/db.ts from zite.schema.json
     try {
-        if (existsSync('zite.schema.json')) {
-            const schema = JSON.parse(readFileSync('zite.schema.json', 'utf-8'));
+        if (existsSync("zite.schema.json")) {
+            const schema = JSON.parse(readFileSync("zite.schema.json", "utf-8"));
             const dbTs = generateDbTs(schema);
-            mkdirSync('.zite', { recursive: true });
-            writeFileSync(join('.zite', 'db.ts'), dbTs);
-            console.log('Wrote .zite/db.ts');
+            mkdirSync(".zite", { recursive: true });
+            writeFileSync(join(".zite", "db.ts"), dbTs);
+            console.log("Wrote .zite/db.ts");
         }
     }
     catch (err) {
-        console.warn('DB SDK generation failed:', err instanceof Error ? err.message : err);
+        console.warn("DB SDK generation failed:", err instanceof Error ? err.message : err);
     }
     // 2. Find all apps and regenerate their .zite/ files
     const appDirs = findAppDirs();
@@ -110,20 +110,20 @@ export async function runGenerate() {
         regenerateAppTypedWrappers(app);
         regenerateAppAirtableSdk(app);
     }
-    console.log('Done!');
+    console.log("Done!");
 }
 export async function runDev() {
-    const env = process.env.ZITE_ENV ?? 'production';
+    const env = process.env.ZITE_ENV ?? "production";
     console.log(`zitejs dev — environment: ${env}`);
-    console.log('');
+    console.log("");
     // 1. Run initial sync (generates root .zite/db.ts)
     try {
         await runSync();
     }
     catch (err) {
-        console.warn('Initial sync failed (continuing with watcher):', err instanceof Error ? err.message : err);
+        console.warn("Initial sync failed (continuing with watcher):", err instanceof Error ? err.message : err);
     }
-    console.log('');
+    console.log("");
     // 2. Find all apps and regenerate their .zite/ files
     const appDirs = findAppDirs();
     for (const app of appDirs) {
@@ -133,7 +133,7 @@ export async function runDev() {
     // 3. Watch each app's src/api/ for endpoint changes
     let watchingAny = false;
     for (const app of appDirs) {
-        const apiDir = join('apps', app, 'src', 'api');
+        const apiDir = join("apps", app, "src", "api");
         if (!existsSync(apiDir))
             continue;
         watchingAny = true;
@@ -141,7 +141,7 @@ export async function runDev() {
         watch(apiDir, { recursive: true }, (_event, filename) => {
             if (!filename)
                 return;
-            if (!filename.endsWith('.ts') && !filename.endsWith('.js'))
+            if (!filename.endsWith(".ts") && !filename.endsWith(".js"))
                 return;
             debounce(app, () => {
                 console.log(`Endpoint changed in ${app}: ${filename}`);
@@ -150,24 +150,24 @@ export async function runDev() {
         });
     }
     if (!watchingAny) {
-        console.log('No apps with src/api/ found.');
+        console.log("No apps with src/api/ found.");
     }
     // 4. Watch zite.schema.json for schema drift
-    if (existsSync('zite.schema.json')) {
-        console.log('Watching zite.schema.json for schema changes...');
-        watch('zite.schema.json', () => {
-            debounce('schema', async () => {
-                console.log('Schema changed — re-running sync...');
+    if (existsSync("zite.schema.json")) {
+        console.log("Watching zite.schema.json for schema changes...");
+        watch("zite.schema.json", () => {
+            debounce("schema", async () => {
+                console.log("Schema changed — re-running sync...");
                 try {
                     await runSync();
                 }
                 catch (err) {
-                    console.error('Re-sync failed:', err instanceof Error ? err.message : err);
+                    console.error("Re-sync failed:", err instanceof Error ? err.message : err);
                 }
             }, 500);
         });
     }
-    console.log('');
-    console.log('Ready. Watching for changes... (Ctrl+C to stop)');
+    console.log("");
+    console.log("Ready. Watching for changes... (Ctrl+C to stop)");
     await new Promise(() => { });
 }

package/dist/esm/sync/lib.d.ts

@@ -40,11 +40,13 @@ export type AirtableLockField = {
     id: string;
     sdkName: string;
     type: string;
-    options?: string[];
+    name: string;
+    config?: Record<string, unknown>;
 };
 export type AirtableLockTable = {
     id: string;
     sdkName: string;
+    primaryFieldId: string;
     fields: AirtableLockField[];
 };
 export type AirtableLock = {

package/dist/esm/sync/lib.js

@@ -95,9 +95,7 @@ function fieldJsdoc(schemaField, table) {
     }
     if (def.type === "datetime") {
         const tpl = def.template;
-        const timeParts = [
-            "Date+time field (ISO 8601 timestamp)",
-        ];
+        const timeParts = ["Date+time field (ISO 8601 timestamp)"];
         if (tpl.dateFormat)
             timeParts.push(`date: ${tpl.dateFormat}`);
         if (tpl.timeFormat)
@@ -145,7 +143,8 @@ function fieldJsdoc(schemaField, table) {
     }
     if ((def.type === "single_select" || def.type === "multiple_select") &&
         def.template?.options) {
-        const count = (def.template.options ?? []).length;
+        const count = (def.template.options ?? [])
+            .length;
         if (count > MAX_SELECT_OPTIONS) {
             parts.push(`${count - MAX_SELECT_OPTIONS} more options omitted`);
         }
@@ -384,11 +383,12 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     externalSyncSource: "unknown",
     aiText: "string",
 };
-function airtableTsType(field) {
+function airtableTsType(field, lock, depth) {
+    const choices = field.config?.choices;
     if ((field.type === "singleSelect" || field.type === "multipleSelects") &&
-        field.options &&
-        field.options.length > 0) {
-        const literals = field.options
+        choices &&
+        choices.length > 0) {
+        const literals = choices
             .slice(0, MAX_SELECT_OPTIONS)
             .map((o) => `"${o.replace(/"/g, '\\"')}"`)
             .join(" | ");
@@ -397,15 +397,121 @@ function airtableTsType(field) {
             return `(${union})[]`;
         return union;
     }
+    if (field.type === "multipleLookupValues" && lock && (depth ?? 0) < 5) {
+        const linkFieldId = field.config?.recordLinkFieldId;
+        const targetFieldId = field.config?.fieldIdInLinkedTable;
+        if (linkFieldId && targetFieldId) {
+            const table = lock.tables.find((t) => t.fields.some((f) => f.id === linkFieldId));
+            const linkField = table?.fields.find((f) => f.id === linkFieldId);
+            const linkedTableId = linkField?.config?.linkedTableId;
+            if (linkedTableId) {
+                const linkedTable = lock.tables.find((t) => t.id === linkedTableId);
+                const targetField = linkedTable?.fields.find((f) => f.id === targetFieldId);
+                if (targetField) {
+                    const resolved = airtableTsType(targetField, lock, (depth ?? 0) + 1);
+                    return `${resolved}[] | undefined`;
+                }
+            }
+        }
+    }
     return AIRTABLE_FIELD_TYPE_MAP[field.type] ?? "unknown";
 }
+const READ_ONLY_AIRTABLE_FIELDS = new Set([
+    "autoNumber",
+    "count",
+    "formula",
+    "rollup",
+    "multipleLookupValues",
+    "createdTime",
+    "lastModifiedTime",
+    "createdBy",
+    "lastModifiedBy",
+    "button",
+    "externalSyncSource",
+    "aiText",
+]);
+function airtableFieldJsdoc(field, table) {
+    const parts = [];
+    if (table.primaryFieldId === field.id)
+        parts.push("Primary field");
+    if (READ_ONLY_AIRTABLE_FIELDS.has(field.type))
+        parts.push("Read-only; do not write");
+    if (field.type === "multipleRecordLinks") {
+        const linkedTableId = field.config?.linkedTableId;
+        if (linkedTableId)
+            parts.push(`Links to table ${linkedTableId}`);
+        if (field.config?.prefersSingleRecordLink)
+            parts.push("Single record only");
+    }
+    if (field.type === "multipleLookupValues")
+        parts.push("Lookup: value is an array — index or aggregate when displaying");
+    if (field.type === "percent")
+        parts.push("Raw decimal — multiply by 100 for display percentage");
+    parts.push(`"${field.name}"`);
+    if (field.type === "currency") {
+        const symbol = field.config?.symbol;
+        const precision = field.config?.precision;
+        if (symbol)
+            parts.push(`Display as currency with "${symbol}", ${precision ?? 2} decimals`);
+    }
+    if (field.type === "date") {
+        const fmt = field.config?.dateFormat;
+        if (fmt)
+            parts.push(`Date-only (ISO string), display as "${fmt}"`);
+    }
+    if (field.type === "dateTime") {
+        const dateFmt = field.config?.dateFormat;
+        const timeFmt = field.config?.timeFormat;
+        const tz = field.config?.timeZone;
+        const fmtParts = ["Date+time (ISO string)"];
+        if (dateFmt)
+            fmtParts.push(`date: ${dateFmt}`);
+        if (timeFmt)
+            fmtParts.push(`time: ${timeFmt}`);
+        if (tz)
+            fmtParts.push(`tz: ${tz}`);
+        parts.push(fmtParts.join(", "));
+    }
+    if (field.type === "rating") {
+        const max = field.config?.max;
+        if (max)
+            parts.push(`Max: ${max}`);
+    }
+    if (field.type === "duration") {
+        const fmt = field.config?.format;
+        if (fmt)
+            parts.push(`Value in seconds, display as "${fmt}"`);
+    }
+    if (field.type === "number" || field.type === "percent") {
+        const precision = field.config?.precision;
+        if (precision != null)
+            parts.push(`${precision} decimal places`);
+    }
+    if (parts.length <= 1)
+        return undefined;
+    return parts.join(". ");
+}
 export function generateAirtableTs(lock) {
     if (lock.tables.length === 0)
         return null;
     const lines = [
         "// Auto-generated by zitejs generate from zite.lock. Do not edit manually.",
         "// Airtable SDK — uses createAirtableClient from zitejs/runtime.",
-        "// The airtable package is externalized (not bundled per-endpoint).",
+        "//",
+        "// Each exported table client has these methods:",
+        "//   findAll(options?: { offset?: string; limit?: number; filters?: unknown })",
+        "//     => Promise<{ records: T[]; offset: string | undefined; hasMore: boolean }>",
+        "//   findOne(params: { id?: string; filters?: unknown }) => Promise<T | undefined>",
+        "//   create(data: { record: Partial<T> }) => Promise<T>",
+        "//   bulkCreate(records: Partial<T>[]) => Promise<T[]>",
+        "//   update(id: string, data: { record: Partial<T> }) => Promise<T>",
+        "//   delete(id: string) => Promise<{ deleted: true }>",
+        "//",
+        "// Usage tips:",
+        "//   - Airtable has a strict rate limit of 5 requests/second per base",
+        "//   - Use bulkCreate() instead of calling create() in a loop",
+        "//   - findAll() offsets are opaque strings from previous calls, NOT numbers",
+        "//   - Always destructure record properties individually in create/update calls",
         "",
         "import { createAirtableClient } from 'zitejs/runtime';",
         "",
@@ -417,7 +523,11 @@ export function generateAirtableTs(lock) {
         for (const field of table.fields) {
             if (field.sdkName === "id")
                 continue;
-            const tsType = airtableTsType(field);
+            const jsdoc = airtableFieldJsdoc(field, table);
+            if (jsdoc) {
+                lines.push(`  /** ${jsdoc} */`);
+            }
+            const tsType = airtableTsType(field, lock);
             lines.push(`  ${field.sdkName}: ${tsType};`);
         }
         lines.push("};");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.50",
+  "version": "0.9.52",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "main": "./dist/cjs/index.js",