zitejs 0.9.41 → 0.9.42

package/dist/cjs/sync/index.js

@@ -12,9 +12,11 @@ const DB_ENVIRONMENTS = {
     local: "http://localhost:2507/api/v1",
 };
 const env = process.env.ZITE_ENV ?? "production";
-const BASE_URL = process.env.ZITE_DB_URL ?? DB_ENVIRONMENTS[env] ?? DB_ENVIRONMENTS.production;
+const BASE_URL = process.env.ZITE_DB_URL ??
+    DB_ENVIRONMENTS[env] ??
+    DB_ENVIRONMENTS.production;
 const TOKEN = process.env.ZITE_DB_TOKEN ?? "";
-async function fetchBaseMetadata(baseId) {
+async function fetchDatabase(baseId) {
     const url = `${BASE_URL}/bases/${encodeURIComponent(baseId)}`;
     const res = await fetch(url, {
         headers: { Authorization: `Bearer ${TOKEN}` },
@@ -35,6 +37,15 @@ function resolveBaseId() {
         return undefined;
     }
 }
+function readExistingSchema() {
+    try {
+        if ((0, fs_1.existsSync)("zite.schema.json")) {
+            return JSON.parse((0, fs_1.readFileSync)("zite.schema.json", "utf-8"));
+        }
+    }
+    catch { }
+    return undefined;
+}
 async function runSync() {
     if (!TOKEN) {
         throw new Error("ZITE_DB_TOKEN is required.");
@@ -44,12 +55,13 @@ async function runSync() {
         throw new Error("Could not determine base ID.");
     }
     console.log(`Syncing database ${baseId}...`);
-    const base = await fetchBaseMetadata(baseId);
-    console.log(`Found ${base.tables?.length ?? 0} tables`);
-    const schema = (0, lib_js_1.generateSchema)(base);
+    const database = await fetchDatabase(baseId);
+    console.log(`Found ${database.tables?.length ?? 0} tables`);
+    const existingSchema = readExistingSchema();
+    const schema = (0, lib_js_1.generateSchema)(database, existingSchema);
     (0, fs_1.writeFileSync)("zite.schema.json", JSON.stringify(schema, null, 2));
     console.log("Wrote zite.schema.json");
-    const dbTs = (0, lib_js_1.generateDbTs)(base, schema);
+    const dbTs = (0, lib_js_1.generateDbTs)(schema);
     const dotZite = ".zite";
     (0, fs_1.mkdirSync)(dotZite, { recursive: true });
     (0, fs_1.writeFileSync)((0, path_1.join)(dotZite, "db.ts"), dbTs);

package/dist/cjs/sync/lib.js

@@ -11,6 +11,7 @@ exports.generateBackendWrapperTs = generateBackendWrapperTs;
 const FIELD_TYPE_MAP = {
     single_line_text: "string",
     long_text: "string",
+    rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
@@ -29,6 +30,25 @@ const FIELD_TYPE_MAP = {
     lookup: "unknown",
     autonumber: "number",
     source: "string",
+    formula: "unknown",
+    created_at: "string",
+    updated_at: "string",
+};
+const MAX_SELECT_OPTIONS = 100;
+const NUMBER_FORMAT_EXAMPLES = {
+    local: "1,000,000.50",
+    comma_period: "1,000,000.50",
+    period_comma: "1.000.000,50",
+    space_comma: "1 000 000,50",
+    space_period: "1 000 000.50",
+    no_separator: "1000000.50",
+};
+const DURATION_FORMAT_EXAMPLES = {
+    "h:mm": "1:23",
+    "h:mm:ss": "1:23:03",
+    "h:mm:ss.s": "1:23:03.0",
+    "h:mm:ss.ss": "1:23:03.00",
+    "h:mm:ss.sss": "1:23:03.000",
 };
 function toPascalCase(name) {
     return name
@@ -39,33 +59,157 @@ function toCamelCase(name) {
     const pascal = toPascalCase(name);
     return pascal.charAt(0).toLowerCase() + pascal.slice(1);
 }
-function tsTypeForField(field) {
-    if (FIELD_TYPE_MAP[field.type])
-        return FIELD_TYPE_MAP[field.type];
-    const lowerName = field.name?.toLowerCase() ?? "";
-    if (lowerName === "createdat" ||
-        lowerName === "created_at" ||
-        lowerName === "updatedat" ||
-        lowerName === "updated_at") {
-        return "string";
+function tsTypeForSchemaField(def) {
+    if (def.type === "single_select" || def.type === "multiple_select") {
+        const options = def.template
+            ?.options;
+        if (options && options.length > 0) {
+            const literals = options
+                .slice(0, MAX_SELECT_OPTIONS)
+                .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
+                .join(" | ");
+            const union = `${literals} | string`;
+            if (def.type === "multiple_select")
+                return `(${union})[]`;
+            return union;
+        }
     }
+    if (FIELD_TYPE_MAP[def.type])
+        return FIELD_TYPE_MAP[def.type];
     return "string";
 }
-function generateSchema(base) {
-    const schema = { tables: {} };
-    for (const table of base.tables ?? []) {
-        const tableName = toCamelCase(table.name);
-        const fields = {};
-        for (const field of table.fields ?? []) {
-            fields[toCamelCase(field.name)] = { id: field.id };
+function fieldJsdoc(schemaField, table) {
+    const def = schemaField.definition;
+    const parts = [];
+    if (table.primaryFieldId === schemaField.id)
+        parts.push("Primary field");
+    if (def.type === "created_at" ||
+        def.type === "updated_at" ||
+        def.type === "lookup" ||
+        def.type === "formula" ||
+        def.type === "autonumber") {
+        parts.push("Read-only");
+    }
+    if (def.type === "linked_record") {
+        const tpl = def.template;
+        if (tpl.tableId)
+            parts.push(`Links to table ${tpl.tableId}`);
+        if (tpl.allowMultiple === false)
+            parts.push("Single record only");
+    }
+    parts.push(`"${def.name}"`);
+    if (def.type === "date") {
+        const tpl = def.template;
+        if (tpl.dateFormat)
+            parts.push(`Date-only field (YYYY-MM-DD string), display as "${tpl.dateFormat}" format`);
+    }
+    if (def.type === "datetime") {
+        const tpl = def.template;
+        const timeParts = [
+            "Date+time field (ISO 8601 timestamp)",
+        ];
+        if (tpl.dateFormat)
+            timeParts.push(`date: ${tpl.dateFormat}`);
+        if (tpl.timeFormat)
+            timeParts.push(`time: ${tpl.timeFormat}`);
+        if (tpl.timezone)
+            timeParts.push(`tz: ${tpl.timezone}`);
+        if (tpl.displayTimeZone)
+            timeParts.push("timezone displayed to user");
+        parts.push(timeParts.join(", "));
+    }
+    if (def.type === "currency") {
+        const tpl = def.template;
+        if (tpl.currencySymbol) {
+            const formatHint = NUMBER_FORMAT_EXAMPLES[tpl.numberFormat ?? "local"] ?? "";
+            parts.push(`Value is a raw number; display as currency with symbol "${tpl.currencySymbol}", ${tpl.decimalPlaces ?? 2} decimal places, format: ${tpl.numberFormat ?? "local"} (e.g. ${formatHint})`);
+        }
+    }
+    if (def.type === "number") {
+        const tpl = def.template;
+        const formatHint = NUMBER_FORMAT_EXAMPLES[tpl.numberFormat ?? "local"] ?? "";
+        parts.push(`${tpl.decimalPlaces ?? 0} decimal places, format: ${tpl.numberFormat ?? "local"} (e.g. ${formatHint})`);
+    }
+    if (def.type === "percent") {
+        const tpl = def.template;
+        if (tpl.decimalPlaces !== undefined)
+            parts.push(`${tpl.decimalPlaces} decimal places`);
+    }
+    if (def.type === "duration") {
+        const tpl = def.template;
+        if (tpl.format) {
+            const example = DURATION_FORMAT_EXAMPLES[tpl.format] ?? "";
+            parts.push(`Value is in seconds; display in "${tpl.format}" format (${example})`);
+        }
+    }
+    if (def.type === "rating") {
+        const tpl = def.template;
+        if (tpl.maxRating)
+            parts.push(`Max rating: ${tpl.maxRating}`);
+    }
+    if (def.type === "created_at") {
+        parts.push("Auto-set when record was created (ISO 8601)");
+    }
+    if (def.type === "updated_at") {
+        parts.push("Auto-set when record was last modified (ISO 8601)");
+    }
+    if ((def.type === "single_select" || def.type === "multiple_select") &&
+        def.template?.options) {
+        const count = (def.template.options ?? []).length;
+        if (count > MAX_SELECT_OPTIONS) {
+            parts.push(`${count - MAX_SELECT_OPTIONS} more options omitted`);
+        }
+    }
+    if (parts.length <= 1)
+        return undefined;
+    return parts.join(". ");
+}
+/**
+ * Build a ZiteSchema from a Database API response.
+ *
+ * If `existingSchema` is provided, locked SDK names are preserved for
+ * tables/fields that already exist (matched by ID). New tables/fields
+ * get fresh camelCase SDK names. This is how `zitejs sync` preserves
+ * name stability across schema changes.
+ */
+function generateSchema(database, existingSchema) {
+    const existingTableById = new Map();
+    for (const t of existingSchema?.tables ?? []) {
+        existingTableById.set(t.id, t);
+    }
+    const tables = [];
+    for (const table of database.tables) {
+        const existingTable = existingTableById.get(table.id);
+        const existingFieldById = new Map();
+        for (const f of existingTable?.fields ?? []) {
+            existingFieldById.set(f.id, f);
+        }
+        const fields = [];
+        for (const field of table.fields) {
+            const existing = existingFieldById.get(field.id);
+            const { id: _id, order: _order, ...definition } = field;
+            fields.push({
+                id: field.id,
+                sdkName: existing?.sdkName ?? toCamelCase(field.name),
+                definition,
+            });
         }
-        schema.tables[tableName] = { id: table.id, fields };
+        tables.push({
+            id: table.id,
+            sdkName: existingTable?.sdkName ?? toCamelCase(table.name),
+            primaryFieldId: table.primaryFieldId,
+            fields,
+        });
     }
-    return schema;
+    return { tables };
 }
-function generateDbTs(base, schema) {
+/**
+ * Generate .zite/db.ts purely from ZiteSchema.
+ * Pure function — no external data needed beyond what's in the schema file.
+ */
+function generateDbTs(schema) {
     const lines = [];
-    lines.push("// Auto-generated by zitejs sync. Do not edit manually.");
+    lines.push("// Auto-generated by zitejs generate. Do not edit manually.");
     lines.push("//");
     lines.push("// Usage in endpoint files (src/api/*.ts):");
     lines.push('//   import { zite } from "zitejs/db";');
@@ -97,26 +241,28 @@ function generateDbTs(base, schema) {
     lines.push('//   - Load the "zite:sql" skill for full SQL reference (formulas, lookups, etc.)');
     lines.push("import { createTableClient, createSqlClient } from 'zitejs/runtime';");
     lines.push("");
-    for (const table of base.tables ?? []) {
-        const className = toPascalCase(table.name);
+    for (const table of schema.tables) {
+        const className = toPascalCase(table.sdkName);
         const recordType = `${className}RecordType`;
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
-        for (const field of table.fields ?? []) {
-            const fieldName = toCamelCase(field.name);
-            if (fieldName === "id")
+        for (const field of table.fields) {
+            if (field.sdkName === "id")
                 continue;
-            const tsType = tsTypeForField(field);
-            lines.push(`  ${fieldName}: ${tsType};`);
+            const tsType = tsTypeForSchemaField(field.definition);
+            const jsdoc = fieldJsdoc(field, table);
+            if (jsdoc) {
+                lines.push(`  /** ${jsdoc} */`);
+            }
+            lines.push(`  ${field.sdkName}: ${tsType};`);
         }
         lines.push("};");
         lines.push("");
     }
     lines.push("export const zite = {");
-    for (const table of base.tables ?? []) {
-        const className = toPascalCase(table.name);
-        const propName = toCamelCase(table.name);
-        lines.push(`  ${propName}: createTableClient<${className}RecordType>('${className}'),`);
+    for (const table of schema.tables) {
+        const className = toPascalCase(table.sdkName);
+        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType>('${className}'),`);
     }
     lines.push(`  sql: createSqlClient(),`);
     lines.push("};");
@@ -144,14 +290,12 @@ function generateApiTs(endpointFiles) {
         lines.push(`export const ${name} = createCaller(${name}Endpoint, '${name}');`);
     }
     lines.push("");
-    // Inferred input/output types per endpoint (e.g. GetDashboardInputType, GetDashboardOutputType)
     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("");
-    // Also export as a single api object
     lines.push("export const api = {");
     for (const name of endpointNames) {
         lines.push(`  ${name},`);
@@ -160,6 +304,11 @@ function generateApiTs(endpointFiles) {
     lines.push("");
     return lines.join("\n");
 }
+function tsTypeForField(field) {
+    if (FIELD_TYPE_MAP[field.type])
+        return FIELD_TYPE_MAP[field.type];
+    return "string";
+}
 function generateUserTs(usersTableFields) {
     const lines = [
         "// Auto-generated by zitejs sync. Do not edit manually.",

package/dist/esm/client/index.d.ts

@@ -249,7 +249,7 @@ export declare class Zite {
                 linkedRecordFieldId: string;
                 lookupFieldId: string;
                 formulaExpression?: string | undefined;
-                resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
             };
         } | {
             name: string;
@@ -260,9 +260,9 @@ export declare class Zite {
             type: "formula";
             template: {
                 expression: string;
-                resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                 formatting?: {
-                    numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                    numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                     currencyCode?: string | undefined;
                     decimalPlaces?: number | undefined;
                     numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;
@@ -428,7 +428,7 @@ export declare class Zite {
                 linkedRecordFieldId: string;
                 lookupFieldId: string;
                 formulaExpression?: string | undefined;
-                resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
             };
         } | {
             name: string;
@@ -439,9 +439,9 @@ export declare class Zite {
             type: "formula";
             template: {
                 expression: string;
-                resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                 formatting?: {
-                    numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                    numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                     currencyCode?: string | undefined;
                     decimalPlaces?: number | undefined;
                     numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;
@@ -617,7 +617,7 @@ export declare class Zite {
                     linkedRecordFieldId: string;
                     lookupFieldId: string;
                     formulaExpression?: string | undefined;
-                    resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                    resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                 };
             } | {
                 name: string;
@@ -628,9 +628,9 @@ export declare class Zite {
                 type: "formula";
                 template: {
                     expression: string;
-                    resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                    resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                     formatting?: {
-                        numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                        numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                         currencyCode?: string | undefined;
                         decimalPlaces?: number | undefined;
                         numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;
@@ -809,7 +809,7 @@ export declare class Zite {
                     linkedRecordFieldId: string;
                     lookupFieldId: string;
                     formulaExpression?: string | undefined;
-                    resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                    resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                 };
             } | {
                 name: string;
@@ -820,9 +820,9 @@ export declare class Zite {
                 type: "formula";
                 template: {
                     expression: string;
-                    resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                    resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                     formatting?: {
-                        numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                        numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                         currencyCode?: string | undefined;
                         decimalPlaces?: number | undefined;
                         numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;
@@ -1009,7 +1009,7 @@ export declare class Zite {
                         linkedRecordFieldId: string;
                         lookupFieldId: string;
                         formulaExpression?: string | undefined;
-                        resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                        resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                     };
                 } | {
                     name: string;
@@ -1020,9 +1020,9 @@ export declare class Zite {
                     type: "formula";
                     template: {
                         expression: string;
-                        resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                        resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                         formatting?: {
-                            numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                            numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                             currencyCode?: string | undefined;
                             decimalPlaces?: number | undefined;
                             numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;
@@ -1210,7 +1210,7 @@ export declare class Zite {
                         linkedRecordFieldId: string;
                         lookupFieldId: string;
                         formulaExpression?: string | undefined;
-                        resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                        resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                     };
                 } | {
                     name: string;
@@ -1221,9 +1221,9 @@ export declare class Zite {
                     type: "formula";
                     template: {
                         expression: string;
-                        resultType?: "number" | "boolean" | "date" | "text" | "array" | undefined;
+                        resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
                         formatting?: {
-                            numberDisplayType?: "number" | "currency" | "percent" | "duration" | undefined;
+                            numberDisplayType?: "number" | "currency" | "duration" | "percent" | undefined;
                             currencyCode?: string | undefined;
                             decimalPlaces?: number | undefined;
                             numberFormat?: "local" | "comma_period" | "period_comma" | "space_comma" | "space_period" | undefined;

package/dist/esm/sync/index.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, } from "fs";
 import { join } from "path";
-import { generateSchema, generateDbTs, generateApiTs } from "./lib.js";
+import { generateSchema, generateDbTs, generateApiTs, } from "./lib.js";
 const DB_ENVIRONMENTS = {
     production: "https://tables.fillout.com/api/v1",
     staging: "https://tables.filloutstaging.com/api/v1",
     local: "http://localhost:2507/api/v1",
 };
 const env = process.env.ZITE_ENV ?? "production";
-const BASE_URL = process.env.ZITE_DB_URL ?? DB_ENVIRONMENTS[env] ?? DB_ENVIRONMENTS.production;
+const BASE_URL = process.env.ZITE_DB_URL ??
+    DB_ENVIRONMENTS[env] ??
+    DB_ENVIRONMENTS.production;
 const TOKEN = process.env.ZITE_DB_TOKEN ?? "";
-async function fetchBaseMetadata(baseId) {
+async function fetchDatabase(baseId) {
     const url = `${BASE_URL}/bases/${encodeURIComponent(baseId)}`;
     const res = await fetch(url, {
         headers: { Authorization: `Bearer ${TOKEN}` },
@@ -31,6 +33,15 @@ function resolveBaseId() {
         return undefined;
     }
 }
+function readExistingSchema() {
+    try {
+        if (existsSync("zite.schema.json")) {
+            return JSON.parse(readFileSync("zite.schema.json", "utf-8"));
+        }
+    }
+    catch { }
+    return undefined;
+}
 export async function runSync() {
     if (!TOKEN) {
         throw new Error("ZITE_DB_TOKEN is required.");
@@ -40,12 +51,13 @@ export async function runSync() {
         throw new Error("Could not determine base ID.");
     }
     console.log(`Syncing database ${baseId}...`);
-    const base = await fetchBaseMetadata(baseId);
-    console.log(`Found ${base.tables?.length ?? 0} tables`);
-    const schema = generateSchema(base);
+    const database = await fetchDatabase(baseId);
+    console.log(`Found ${database.tables?.length ?? 0} tables`);
+    const existingSchema = readExistingSchema();
+    const schema = generateSchema(database, existingSchema);
     writeFileSync("zite.schema.json", JSON.stringify(schema, null, 2));
     console.log("Wrote zite.schema.json");
-    const dbTs = generateDbTs(base, schema);
+    const dbTs = generateDbTs(schema);
     const dotZite = ".zite";
     mkdirSync(dotZite, { recursive: true });
     writeFileSync(join(dotZite, "db.ts"), dbTs);

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

@@ -1,26 +1,35 @@
-export type BaseMetadata = {
-    tables?: Array<{
-        id: string;
-        name: string;
-        fields?: Array<{
-            id: string;
-            name: string;
-            type: string;
-        }>;
-    }>;
+import type { PublicFieldDefinition } from "../types/fields.js";
+import type { Database } from "../types/tables.js";
+export type ZiteSchemaField = {
+    id: string;
+    sdkName: string;
+    definition: PublicFieldDefinition;
+};
+export type ZiteSchemaTable = {
+    id: string;
+    sdkName: string;
+    primaryFieldId?: string;
+    fields: ZiteSchemaField[];
 };
 export type ZiteSchema = {
-    tables: Record<string, {
-        id: string;
-        fields: Record<string, {
-            id: string;
-        }>;
-    }>;
+    tables: ZiteSchemaTable[];
 };
 export declare function toPascalCase(name: string): string;
 export declare function toCamelCase(name: string): string;
-export declare function generateSchema(base: BaseMetadata): ZiteSchema;
-export declare function generateDbTs(base: BaseMetadata, schema: ZiteSchema): string;
+/**
+ * Build a ZiteSchema from a Database API response.
+ *
+ * If `existingSchema` is provided, locked SDK names are preserved for
+ * tables/fields that already exist (matched by ID). New tables/fields
+ * get fresh camelCase SDK names. This is how `zitejs sync` preserves
+ * name stability across schema changes.
+ */
+export declare function generateSchema(database: Database, existingSchema?: ZiteSchema): ZiteSchema;
+/**
+ * Generate .zite/db.ts purely from ZiteSchema.
+ * Pure function — no external data needed beyond what's in the schema file.
+ */
+export declare function generateDbTs(schema: ZiteSchema): string;
 export declare function generateApiTs(endpointFiles: string[]): string | null;
 export declare function generateUserTs(usersTableFields?: Array<{
     name: string;

package/dist/esm/sync/lib.js

@@ -1,6 +1,7 @@
 const FIELD_TYPE_MAP = {
     single_line_text: "string",
     long_text: "string",
+    rich_text: "string",
     email: "string",
     url: "string",
     phone_number: "string",
@@ -19,6 +20,25 @@ const FIELD_TYPE_MAP = {
     lookup: "unknown",
     autonumber: "number",
     source: "string",
+    formula: "unknown",
+    created_at: "string",
+    updated_at: "string",
+};
+const MAX_SELECT_OPTIONS = 100;
+const NUMBER_FORMAT_EXAMPLES = {
+    local: "1,000,000.50",
+    comma_period: "1,000,000.50",
+    period_comma: "1.000.000,50",
+    space_comma: "1 000 000,50",
+    space_period: "1 000 000.50",
+    no_separator: "1000000.50",
+};
+const DURATION_FORMAT_EXAMPLES = {
+    "h:mm": "1:23",
+    "h:mm:ss": "1:23:03",
+    "h:mm:ss.s": "1:23:03.0",
+    "h:mm:ss.ss": "1:23:03.00",
+    "h:mm:ss.sss": "1:23:03.000",
 };
 export function toPascalCase(name) {
     return name
@@ -29,33 +49,157 @@ export function toCamelCase(name) {
     const pascal = toPascalCase(name);
     return pascal.charAt(0).toLowerCase() + pascal.slice(1);
 }
-function tsTypeForField(field) {
-    if (FIELD_TYPE_MAP[field.type])
-        return FIELD_TYPE_MAP[field.type];
-    const lowerName = field.name?.toLowerCase() ?? "";
-    if (lowerName === "createdat" ||
-        lowerName === "created_at" ||
-        lowerName === "updatedat" ||
-        lowerName === "updated_at") {
-        return "string";
+function tsTypeForSchemaField(def) {
+    if (def.type === "single_select" || def.type === "multiple_select") {
+        const options = def.template
+            ?.options;
+        if (options && options.length > 0) {
+            const literals = options
+                .slice(0, MAX_SELECT_OPTIONS)
+                .map((o) => `"${o.label.replace(/"/g, '\\"')}"`)
+                .join(" | ");
+            const union = `${literals} | string`;
+            if (def.type === "multiple_select")
+                return `(${union})[]`;
+            return union;
+        }
     }
+    if (FIELD_TYPE_MAP[def.type])
+        return FIELD_TYPE_MAP[def.type];
     return "string";
 }
-export function generateSchema(base) {
-    const schema = { tables: {} };
-    for (const table of base.tables ?? []) {
-        const tableName = toCamelCase(table.name);
-        const fields = {};
-        for (const field of table.fields ?? []) {
-            fields[toCamelCase(field.name)] = { id: field.id };
+function fieldJsdoc(schemaField, table) {
+    const def = schemaField.definition;
+    const parts = [];
+    if (table.primaryFieldId === schemaField.id)
+        parts.push("Primary field");
+    if (def.type === "created_at" ||
+        def.type === "updated_at" ||
+        def.type === "lookup" ||
+        def.type === "formula" ||
+        def.type === "autonumber") {
+        parts.push("Read-only");
+    }
+    if (def.type === "linked_record") {
+        const tpl = def.template;
+        if (tpl.tableId)
+            parts.push(`Links to table ${tpl.tableId}`);
+        if (tpl.allowMultiple === false)
+            parts.push("Single record only");
+    }
+    parts.push(`"${def.name}"`);
+    if (def.type === "date") {
+        const tpl = def.template;
+        if (tpl.dateFormat)
+            parts.push(`Date-only field (YYYY-MM-DD string), display as "${tpl.dateFormat}" format`);
+    }
+    if (def.type === "datetime") {
+        const tpl = def.template;
+        const timeParts = [
+            "Date+time field (ISO 8601 timestamp)",
+        ];
+        if (tpl.dateFormat)
+            timeParts.push(`date: ${tpl.dateFormat}`);
+        if (tpl.timeFormat)
+            timeParts.push(`time: ${tpl.timeFormat}`);
+        if (tpl.timezone)
+            timeParts.push(`tz: ${tpl.timezone}`);
+        if (tpl.displayTimeZone)
+            timeParts.push("timezone displayed to user");
+        parts.push(timeParts.join(", "));
+    }
+    if (def.type === "currency") {
+        const tpl = def.template;
+        if (tpl.currencySymbol) {
+            const formatHint = NUMBER_FORMAT_EXAMPLES[tpl.numberFormat ?? "local"] ?? "";
+            parts.push(`Value is a raw number; display as currency with symbol "${tpl.currencySymbol}", ${tpl.decimalPlaces ?? 2} decimal places, format: ${tpl.numberFormat ?? "local"} (e.g. ${formatHint})`);
+        }
+    }
+    if (def.type === "number") {
+        const tpl = def.template;
+        const formatHint = NUMBER_FORMAT_EXAMPLES[tpl.numberFormat ?? "local"] ?? "";
+        parts.push(`${tpl.decimalPlaces ?? 0} decimal places, format: ${tpl.numberFormat ?? "local"} (e.g. ${formatHint})`);
+    }
+    if (def.type === "percent") {
+        const tpl = def.template;
+        if (tpl.decimalPlaces !== undefined)
+            parts.push(`${tpl.decimalPlaces} decimal places`);
+    }
+    if (def.type === "duration") {
+        const tpl = def.template;
+        if (tpl.format) {
+            const example = DURATION_FORMAT_EXAMPLES[tpl.format] ?? "";
+            parts.push(`Value is in seconds; display in "${tpl.format}" format (${example})`);
+        }
+    }
+    if (def.type === "rating") {
+        const tpl = def.template;
+        if (tpl.maxRating)
+            parts.push(`Max rating: ${tpl.maxRating}`);
+    }
+    if (def.type === "created_at") {
+        parts.push("Auto-set when record was created (ISO 8601)");
+    }
+    if (def.type === "updated_at") {
+        parts.push("Auto-set when record was last modified (ISO 8601)");
+    }
+    if ((def.type === "single_select" || def.type === "multiple_select") &&
+        def.template?.options) {
+        const count = (def.template.options ?? []).length;
+        if (count > MAX_SELECT_OPTIONS) {
+            parts.push(`${count - MAX_SELECT_OPTIONS} more options omitted`);
+        }
+    }
+    if (parts.length <= 1)
+        return undefined;
+    return parts.join(". ");
+}
+/**
+ * Build a ZiteSchema from a Database API response.
+ *
+ * If `existingSchema` is provided, locked SDK names are preserved for
+ * tables/fields that already exist (matched by ID). New tables/fields
+ * get fresh camelCase SDK names. This is how `zitejs sync` preserves
+ * name stability across schema changes.
+ */
+export function generateSchema(database, existingSchema) {
+    const existingTableById = new Map();
+    for (const t of existingSchema?.tables ?? []) {
+        existingTableById.set(t.id, t);
+    }
+    const tables = [];
+    for (const table of database.tables) {
+        const existingTable = existingTableById.get(table.id);
+        const existingFieldById = new Map();
+        for (const f of existingTable?.fields ?? []) {
+            existingFieldById.set(f.id, f);
+        }
+        const fields = [];
+        for (const field of table.fields) {
+            const existing = existingFieldById.get(field.id);
+            const { id: _id, order: _order, ...definition } = field;
+            fields.push({
+                id: field.id,
+                sdkName: existing?.sdkName ?? toCamelCase(field.name),
+                definition,
+            });
         }
-        schema.tables[tableName] = { id: table.id, fields };
+        tables.push({
+            id: table.id,
+            sdkName: existingTable?.sdkName ?? toCamelCase(table.name),
+            primaryFieldId: table.primaryFieldId,
+            fields,
+        });
     }
-    return schema;
+    return { tables };
 }
-export function generateDbTs(base, schema) {
+/**
+ * Generate .zite/db.ts purely from ZiteSchema.
+ * Pure function — no external data needed beyond what's in the schema file.
+ */
+export function generateDbTs(schema) {
     const lines = [];
-    lines.push("// Auto-generated by zitejs sync. Do not edit manually.");
+    lines.push("// Auto-generated by zitejs generate. Do not edit manually.");
     lines.push("//");
     lines.push("// Usage in endpoint files (src/api/*.ts):");
     lines.push('//   import { zite } from "zitejs/db";');
@@ -87,26 +231,28 @@ export function generateDbTs(base, schema) {
     lines.push('//   - Load the "zite:sql" skill for full SQL reference (formulas, lookups, etc.)');
     lines.push("import { createTableClient, createSqlClient } from 'zitejs/runtime';");
     lines.push("");
-    for (const table of base.tables ?? []) {
-        const className = toPascalCase(table.name);
+    for (const table of schema.tables) {
+        const className = toPascalCase(table.sdkName);
         const recordType = `${className}RecordType`;
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
-        for (const field of table.fields ?? []) {
-            const fieldName = toCamelCase(field.name);
-            if (fieldName === "id")
+        for (const field of table.fields) {
+            if (field.sdkName === "id")
                 continue;
-            const tsType = tsTypeForField(field);
-            lines.push(`  ${fieldName}: ${tsType};`);
+            const tsType = tsTypeForSchemaField(field.definition);
+            const jsdoc = fieldJsdoc(field, table);
+            if (jsdoc) {
+                lines.push(`  /** ${jsdoc} */`);
+            }
+            lines.push(`  ${field.sdkName}: ${tsType};`);
         }
         lines.push("};");
         lines.push("");
     }
     lines.push("export const zite = {");
-    for (const table of base.tables ?? []) {
-        const className = toPascalCase(table.name);
-        const propName = toCamelCase(table.name);
-        lines.push(`  ${propName}: createTableClient<${className}RecordType>('${className}'),`);
+    for (const table of schema.tables) {
+        const className = toPascalCase(table.sdkName);
+        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType>('${className}'),`);
     }
     lines.push(`  sql: createSqlClient(),`);
     lines.push("};");
@@ -134,14 +280,12 @@ export function generateApiTs(endpointFiles) {
         lines.push(`export const ${name} = createCaller(${name}Endpoint, '${name}');`);
     }
     lines.push("");
-    // Inferred input/output types per endpoint (e.g. GetDashboardInputType, GetDashboardOutputType)
     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("");
-    // Also export as a single api object
     lines.push("export const api = {");
     for (const name of endpointNames) {
         lines.push(`  ${name},`);
@@ -150,6 +294,11 @@ export function generateApiTs(endpointFiles) {
     lines.push("");
     return lines.join("\n");
 }
+function tsTypeForField(field) {
+    if (FIELD_TYPE_MAP[field.type])
+        return FIELD_TYPE_MAP[field.type];
+    return "string";
+}
 export function generateUserTs(usersTableFields) {
     const lines = [
         "// Auto-generated by zitejs sync. Do not edit manually.",

package/dist/esm/types/fields.d.ts

@@ -11,29 +11,29 @@ export declare const fieldTypeEnum: readonly ["currency", "single_line_text", "l
 export type FieldType = (typeof fieldTypeEnum)[number];
 export declare const fieldTypeSchema: z.ZodEnum<{
     number: "number";
+    currency: "currency";
     single_line_text: "single_line_text";
     long_text: "long_text";
-    email: "email";
-    url: "url";
-    phone_number: "phone_number";
-    currency: "currency";
-    percent: "percent";
-    rating: "rating";
-    duration: "duration";
+    rich_text: "rich_text";
     single_select: "single_select";
     multiple_select: "multiple_select";
-    checkbox: "checkbox";
     date: "date";
     datetime: "datetime";
+    checkbox: "checkbox";
     attachments: "attachments";
+    email: "email";
+    url: "url";
+    phone_number: "phone_number";
+    rating: "rating";
+    duration: "duration";
+    percent: "percent";
     linked_record: "linked_record";
     lookup: "lookup";
-    autonumber: "autonumber";
     source: "source";
+    formula: "formula";
+    autonumber: "autonumber";
     created_at: "created_at";
     updated_at: "updated_at";
-    rich_text: "rich_text";
-    formula: "formula";
 }>;
 export declare const selectOptionSchema: z.ZodObject<{
     value: z.ZodString;
@@ -185,8 +185,8 @@ export declare const lookupTemplateSchema: z.ZodObject<{
         number: "number";
         boolean: "boolean";
         date: "date";
-        text: "text";
         array: "array";
+        text: "text";
     }>>;
 }, z.core.$strip>;
 export declare const sourceTemplateSchema: z.ZodObject<{}, z.core.$strip>;
@@ -196,15 +196,15 @@ export declare const formulaTemplateSchema: z.ZodObject<{
         number: "number";
         boolean: "boolean";
         date: "date";
-        text: "text";
         array: "array";
+        text: "text";
     }>>;
     formatting: z.ZodOptional<z.ZodObject<{
         numberDisplayType: z.ZodOptional<z.ZodEnum<{
             number: "number";
             currency: "currency";
-            percent: "percent";
             duration: "duration";
+            percent: "percent";
         }>>;
         currencyCode: z.ZodOptional<z.ZodString>;
         decimalPlaces: z.ZodOptional<z.ZodNumber>;
@@ -444,8 +444,8 @@ export declare const publicFieldDefinitionSchema: z.ZodDiscriminatedUnion<[z.Zod
             number: "number";
             boolean: "boolean";
             date: "date";
-            text: "text";
             array: "array";
+            text: "text";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -461,15 +461,15 @@ export declare const publicFieldDefinitionSchema: z.ZodDiscriminatedUnion<[z.Zod
             number: "number";
             boolean: "boolean";
             date: "date";
-            text: "text";
             array: "array";
+            text: "text";
         }>>;
         formatting: z.ZodOptional<z.ZodObject<{
             numberDisplayType: z.ZodOptional<z.ZodEnum<{
                 number: "number";
                 currency: "currency";
-                percent: "percent";
                 duration: "duration";
+                percent: "percent";
             }>>;
             currencyCode: z.ZodOptional<z.ZodString>;
             decimalPlaces: z.ZodOptional<z.ZodNumber>;

package/dist/esm/types/tables.d.ts

@@ -198,8 +198,8 @@ export declare const fieldSchema: z.ZodIntersection<z.ZodObject<{
             number: "number";
             boolean: "boolean";
             date: "date";
-            text: "text";
             array: "array";
+            text: "text";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -215,15 +215,15 @@ export declare const fieldSchema: z.ZodIntersection<z.ZodObject<{
             number: "number";
             boolean: "boolean";
             date: "date";
-            text: "text";
             array: "array";
+            text: "text";
         }>>;
         formatting: z.ZodOptional<z.ZodObject<{
             numberDisplayType: z.ZodOptional<z.ZodEnum<{
                 number: "number";
                 currency: "currency";
-                percent: "percent";
                 duration: "duration";
+                percent: "percent";
             }>>;
             currencyCode: z.ZodOptional<z.ZodString>;
             decimalPlaces: z.ZodOptional<z.ZodNumber>;
@@ -489,8 +489,8 @@ export declare const tableSchema: z.ZodObject<{
                 number: "number";
                 boolean: "boolean";
                 date: "date";
-                text: "text";
                 array: "array";
+                text: "text";
             }>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
@@ -506,15 +506,15 @@ export declare const tableSchema: z.ZodObject<{
                 number: "number";
                 boolean: "boolean";
                 date: "date";
-                text: "text";
                 array: "array";
+                text: "text";
             }>>;
             formatting: z.ZodOptional<z.ZodObject<{
                 numberDisplayType: z.ZodOptional<z.ZodEnum<{
                     number: "number";
                     currency: "currency";
-                    percent: "percent";
                     duration: "duration";
+                    percent: "percent";
                 }>>;
                 currencyCode: z.ZodOptional<z.ZodString>;
                 decimalPlaces: z.ZodOptional<z.ZodNumber>;
@@ -775,8 +775,8 @@ export declare const publicTableDefinitionSchema: z.ZodObject<{
                 number: "number";
                 boolean: "boolean";
                 date: "date";
-                text: "text";
                 array: "array";
+                text: "text";
             }>>;
         }, z.core.$strip>;
     }, z.core.$strip>, z.ZodObject<{
@@ -792,15 +792,15 @@ export declare const publicTableDefinitionSchema: z.ZodObject<{
                 number: "number";
                 boolean: "boolean";
                 date: "date";
-                text: "text";
                 array: "array";
+                text: "text";
             }>>;
             formatting: z.ZodOptional<z.ZodObject<{
                 numberDisplayType: z.ZodOptional<z.ZodEnum<{
                     number: "number";
                     currency: "currency";
-                    percent: "percent";
                     duration: "duration";
+                    percent: "percent";
                 }>>;
                 currencyCode: z.ZodOptional<z.ZodString>;
                 decimalPlaces: z.ZodOptional<z.ZodNumber>;
@@ -1063,8 +1063,8 @@ export declare const databaseSchema: z.ZodObject<{
                     number: "number";
                     boolean: "boolean";
                     date: "date";
-                    text: "text";
                     array: "array";
+                    text: "text";
                 }>>;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodObject<{
@@ -1080,15 +1080,15 @@ export declare const databaseSchema: z.ZodObject<{
                     number: "number";
                     boolean: "boolean";
                     date: "date";
-                    text: "text";
                     array: "array";
+                    text: "text";
                 }>>;
                 formatting: z.ZodOptional<z.ZodObject<{
                     numberDisplayType: z.ZodOptional<z.ZodEnum<{
                         number: "number";
                         currency: "currency";
-                        percent: "percent";
                         duration: "duration";
+                        percent: "percent";
                     }>>;
                     currencyCode: z.ZodOptional<z.ZodString>;
                     decimalPlaces: z.ZodOptional<z.ZodNumber>;

package/package.json

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