zitejs 0.9.51 → 0.9.53

package/dist/cjs/caller/index.d.ts

@@ -4,4 +4,5 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown> {
         context: unknown;
     }) => Promise<TOutput> | TOutput;
 }
+export declare function createCaller<TInput, TOutput>(name: string, flowId?: string): (input: TInput) => Promise<TOutput>;
 export declare function createCaller<TInput, TOutput>(endpoint: EndpointConfig<TInput, TOutput>, name: string, flowId?: string): (input: TInput) => Promise<TOutput>;

package/dist/cjs/caller/index.js

@@ -3,13 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCaller = createCaller;
 const env_js_1 = require("../internal/env.js");
 const ENVIRONMENTS = {
-    production: 'https://workflows.zite.com',
-    staging: 'https://workflows.zitestaging.com',
-    local: 'http://localhost:2506',
+    production: "https://workflows.zite.com",
+    staging: "https://workflows.zitestaging.com",
+    local: "http://localhost:2506",
 };
 function getRunnerUrl() {
-    const env = (0, env_js_1.getEnv)('ZITE_ENV', 'VITE_ZITE_ENV') ?? 'production';
-    return (0, env_js_1.getEnv)('ZITE_RUNNER_URL', 'VITE_ZITE_RUNNER_URL') ?? ENVIRONMENTS[env] ?? ENVIRONMENTS.production;
+    const env = (0, env_js_1.getEnv)("ZITE_ENV", "VITE_ZITE_ENV") ?? "production";
+    return ((0, env_js_1.getEnv)("ZITE_RUNNER_URL", "VITE_ZITE_RUNNER_URL") ??
+        ENVIRONMENTS[env] ??
+        ENVIRONMENTS.production);
 }
 /**
  * Get the user's usage token for endpoint auth.
@@ -17,33 +19,39 @@ function getRunnerUrl() {
  * In external mode: stored in localStorage by the auth flow
  */
 function getUsageToken() {
-    if (typeof window !== 'undefined') {
+    if (typeof window !== "undefined") {
         const win = window;
-        if (typeof win._ziteUsageToken === 'string')
+        if (typeof win._ziteUsageToken === "string")
             return win._ziteUsageToken;
     }
     // Fallback to stored auth token (external mode)
-    if (typeof localStorage !== 'undefined') {
-        const stored = localStorage.getItem('zite.auth.token');
+    if (typeof localStorage !== "undefined") {
+        const stored = localStorage.getItem("zite.auth.token");
         if (stored)
             return stored;
     }
-    return '';
+    return "";
 }
-function createCaller(endpoint, name, flowId) {
+function createCaller(endpointOrName, nameOrFlowId, flowId) {
+    const name = typeof endpointOrName === "string" ? endpointOrName : nameOrFlowId;
+    const resolvedFlowId = typeof endpointOrName === "string" ? nameOrFlowId : flowId;
     return async (input) => {
-        const appId = flowId ?? (0, env_js_1.getEnv)('ZITE_FLOW_ID', 'VITE_ZITE_FLOW_ID') ?? '';
+        const appId = resolvedFlowId ?? (0, env_js_1.getEnv)("ZITE_FLOW_ID", "VITE_ZITE_FLOW_ID") ?? "";
         const token = getUsageToken();
-        const res = await fetch(getRunnerUrl() + '/public/' + appId + '/api/' + name, {
-            method: 'POST',
+        const res = await fetch(getRunnerUrl() + "/public/" + appId + "/api/" + name, {
+            method: "POST",
             headers: {
                 ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                'Content-Type': 'application/json',
+                "Content-Type": "application/json",
             },
-            body: JSON.stringify({ inputs: input, mode: 'preview', usageToken: token }),
+            body: JSON.stringify({
+                inputs: input,
+                mode: "preview",
+                usageToken: token,
+            }),
         });
         if (!res.ok) {
-            const text = await res.text().catch(() => '');
+            const text = await res.text().catch(() => "");
             throw new Error(`API call failed (${res.status}): ${text}`);
         }
         return res.json();

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

@@ -282,18 +282,18 @@ function generateApiTs(endpointFiles) {
     for (const file of endpointFiles) {
         const name = file.replace(/\.(ts|js)$/, "");
         const camelName = toCamelCase(name);
-        lines.push(`import ${camelName}Endpoint from '../src/api/${name}';`);
+        const pascal = toPascalCase(camelName);
+        lines.push(`import type { default as _${pascal}Ep } from '../src/api/${name}';`);
         endpointNames.push(camelName);
     }
     lines.push("");
-    for (const name of endpointNames) {
-        lines.push(`export const ${name} = createCaller(${name}Endpoint, '${name}');`);
-    }
-    lines.push("");
     for (const name of endpointNames) {
         const pascal = toPascalCase(name);
-        lines.push(`export type ${pascal}InputType = Parameters<typeof ${name}Endpoint.execute>[0]['input'];`);
-        lines.push(`export type ${pascal}OutputType = Awaited<ReturnType<typeof ${name}Endpoint.execute>>;`);
+        lines.push(`type _${pascal}Cfg = typeof _${pascal}Ep;`);
+        lines.push(`export type ${pascal}InputType = Parameters<_${pascal}Cfg['execute']>[0]['input'];`);
+        lines.push(`export type ${pascal}OutputType = Awaited<ReturnType<_${pascal}Cfg['execute']>>;`);
+        lines.push(`export const ${name} = createCaller<${pascal}InputType, ${pascal}OutputType>('${name}');`);
+        lines.push("");
     }
     lines.push("");
     lines.push("export const api = {");
@@ -394,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(" | ");
@@ -407,15 +408,106 @@ 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 })",
@@ -425,6 +517,12 @@ function generateAirtableTs(lock) {
         "//   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';",
         "",
@@ -436,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/caller/index.d.ts

@@ -4,4 +4,5 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown> {
         context: unknown;
     }) => Promise<TOutput> | TOutput;
 }
+export declare function createCaller<TInput, TOutput>(name: string, flowId?: string): (input: TInput) => Promise<TOutput>;
 export declare function createCaller<TInput, TOutput>(endpoint: EndpointConfig<TInput, TOutput>, name: string, flowId?: string): (input: TInput) => Promise<TOutput>;

package/dist/esm/caller/index.js

@@ -1,12 +1,14 @@
-import { getEnv } from '../internal/env.js';
+import { getEnv } from "../internal/env.js";
 const ENVIRONMENTS = {
-    production: 'https://workflows.zite.com',
-    staging: 'https://workflows.zitestaging.com',
-    local: 'http://localhost:2506',
+    production: "https://workflows.zite.com",
+    staging: "https://workflows.zitestaging.com",
+    local: "http://localhost:2506",
 };
 function getRunnerUrl() {
-    const env = getEnv('ZITE_ENV', 'VITE_ZITE_ENV') ?? 'production';
-    return getEnv('ZITE_RUNNER_URL', 'VITE_ZITE_RUNNER_URL') ?? ENVIRONMENTS[env] ?? ENVIRONMENTS.production;
+    const env = getEnv("ZITE_ENV", "VITE_ZITE_ENV") ?? "production";
+    return (getEnv("ZITE_RUNNER_URL", "VITE_ZITE_RUNNER_URL") ??
+        ENVIRONMENTS[env] ??
+        ENVIRONMENTS.production);
 }
 /**
  * Get the user's usage token for endpoint auth.
@@ -14,33 +16,39 @@ function getRunnerUrl() {
  * In external mode: stored in localStorage by the auth flow
  */
 function getUsageToken() {
-    if (typeof window !== 'undefined') {
+    if (typeof window !== "undefined") {
         const win = window;
-        if (typeof win._ziteUsageToken === 'string')
+        if (typeof win._ziteUsageToken === "string")
             return win._ziteUsageToken;
     }
     // Fallback to stored auth token (external mode)
-    if (typeof localStorage !== 'undefined') {
-        const stored = localStorage.getItem('zite.auth.token');
+    if (typeof localStorage !== "undefined") {
+        const stored = localStorage.getItem("zite.auth.token");
         if (stored)
             return stored;
     }
-    return '';
+    return "";
 }
-export function createCaller(endpoint, name, flowId) {
+export function createCaller(endpointOrName, nameOrFlowId, flowId) {
+    const name = typeof endpointOrName === "string" ? endpointOrName : nameOrFlowId;
+    const resolvedFlowId = typeof endpointOrName === "string" ? nameOrFlowId : flowId;
     return async (input) => {
-        const appId = flowId ?? getEnv('ZITE_FLOW_ID', 'VITE_ZITE_FLOW_ID') ?? '';
+        const appId = resolvedFlowId ?? getEnv("ZITE_FLOW_ID", "VITE_ZITE_FLOW_ID") ?? "";
         const token = getUsageToken();
-        const res = await fetch(getRunnerUrl() + '/public/' + appId + '/api/' + name, {
-            method: 'POST',
+        const res = await fetch(getRunnerUrl() + "/public/" + appId + "/api/" + name, {
+            method: "POST",
             headers: {
                 ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                'Content-Type': 'application/json',
+                "Content-Type": "application/json",
             },
-            body: JSON.stringify({ inputs: input, mode: 'preview', usageToken: token }),
+            body: JSON.stringify({
+                inputs: input,
+                mode: "preview",
+                usageToken: token,
+            }),
         });
         if (!res.ok) {
-            const text = await res.text().catch(() => '');
+            const text = await res.text().catch(() => "");
             throw new Error(`API call failed (${res.status}): ${text}`);
         }
         return res.json();

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

@@ -271,18 +271,18 @@ export function generateApiTs(endpointFiles) {
     for (const file of endpointFiles) {
         const name = file.replace(/\.(ts|js)$/, "");
         const camelName = toCamelCase(name);
-        lines.push(`import ${camelName}Endpoint from '../src/api/${name}';`);
+        const pascal = toPascalCase(camelName);
+        lines.push(`import type { default as _${pascal}Ep } from '../src/api/${name}';`);
         endpointNames.push(camelName);
     }
     lines.push("");
-    for (const name of endpointNames) {
-        lines.push(`export const ${name} = createCaller(${name}Endpoint, '${name}');`);
-    }
-    lines.push("");
     for (const name of endpointNames) {
         const pascal = toPascalCase(name);
-        lines.push(`export type ${pascal}InputType = Parameters<typeof ${name}Endpoint.execute>[0]['input'];`);
-        lines.push(`export type ${pascal}OutputType = Awaited<ReturnType<typeof ${name}Endpoint.execute>>;`);
+        lines.push(`type _${pascal}Cfg = typeof _${pascal}Ep;`);
+        lines.push(`export type ${pascal}InputType = Parameters<_${pascal}Cfg['execute']>[0]['input'];`);
+        lines.push(`export type ${pascal}OutputType = Awaited<ReturnType<_${pascal}Cfg['execute']>>;`);
+        lines.push(`export const ${name} = createCaller<${pascal}InputType, ${pascal}OutputType>('${name}');`);
+        lines.push("");
     }
     lines.push("");
     lines.push("export const api = {");
@@ -383,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(" | ");
@@ -396,15 +397,106 @@ 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 })",
@@ -414,6 +506,12 @@ export function generateAirtableTs(lock) {
         "//   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';",
         "",
@@ -425,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.51",
+  "version": "0.9.53",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "main": "./dist/cjs/index.js",