zitejs 0.9.40 → 0.9.42

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.",