zitejs 0.9.41 → 0.9.43

package/dist/esm/dev/index.js

@@ -2,7 +2,7 @@ import { watch } from 'fs';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, } from 'fs';
 import { join } from 'path';
 import { runSync } from '../sync/index.js';
-import { generateApiTs, generateUserTs, generateAuthWrapperTs, generateBackendWrapperTs, } from '../sync/lib.js';
+import { generateApiTs, generateUserTs, generateAuthWrapperTs, generateBackendWrapperTs, generateAirtableTs, } from '../sync/lib.js';
 const debounceTimers = new Map();
 function debounce(key, fn, ms) {
     const existing = debounceTimers.get(key);
@@ -49,6 +49,42 @@ function regenerateAppApiTs(appDir) {
         console.log(`Updated apps/${appDir}/.zite/api.ts`);
     }
 }
+function regenerateAppAirtableSdk(appDir) {
+    const lockPath = join('apps', appDir, 'zite.lock');
+    if (!existsSync(lockPath))
+        return;
+    try {
+        const lockContent = JSON.parse(readFileSync(lockPath, 'utf-8'));
+        const integrations = lockContent.integrations ?? {};
+        for (const [integrationId, integration] of Object.entries(integrations)) {
+            const int = integration;
+            if (!int.idMappings?.tables)
+                continue;
+            const airtableLock = {
+                integrationId,
+                tables: Object.entries(int.idMappings.tables).map(([sdkName, tableId]) => ({
+                    id: tableId,
+                    sdkName,
+                    fields: Object.entries(int.idMappings?.fields?.[sdkName] ?? {}).map(([fieldSdkName, fieldId]) => ({
+                        id: fieldId,
+                        sdkName: fieldSdkName,
+                        type: 'singleLineText',
+                    })),
+                })),
+            };
+            const content = generateAirtableTs(airtableLock);
+            if (content) {
+                const outDir = join('apps', appDir, '.zite', 'integrations');
+                mkdirSync(outDir, { recursive: true });
+                writeFileSync(join(outDir, 'airtable.ts'), content);
+                console.log(`Updated apps/${appDir}/.zite/integrations/airtable.ts`);
+            }
+        }
+    }
+    catch {
+        // Lock file invalid or missing — skip
+    }
+}
 export async function runGenerate() {
     // 1. Run sync (generates root .zite/db.ts)
     try {
@@ -62,6 +98,7 @@ export async function runGenerate() {
     for (const app of appDirs) {
         regenerateAppApiTs(app);
         regenerateAppTypedWrappers(app);
+        regenerateAppAirtableSdk(app);
     }
     console.log('Done!');
 }

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

@@ -39,5 +39,31 @@ export declare function createSqlClient(): (params: {
     query: string;
     params?: unknown[];
 }) => Promise<SqlResult>;
+export interface AirtableTableClient<T> {
+    findAll(options?: {
+        offset?: string;
+        limit?: number;
+        filters?: unknown;
+    }): Promise<{
+        records: T[];
+        offset: string | undefined;
+        hasMore: boolean;
+    }>;
+    findOne(params: {
+        id?: string;
+        filters?: unknown;
+    }): Promise<T | undefined>;
+    create(data: {
+        record: Partial<T>;
+    }): Promise<T>;
+    bulkCreate(records: Partial<T>[]): Promise<T[]>;
+    update(id: string, data: {
+        record: Partial<T>;
+    }): Promise<T>;
+    delete(id: string): Promise<{
+        deleted: true;
+    }>;
+}
+export declare function createAirtableClient<T>(integrationId: string, className: string, implicitParams: Record<string, unknown>): AirtableTableClient<T>;
 export { createCaller } from "../caller/index.js";
 export type { EndpointConfig } from "../caller/index.js";

package/dist/esm/runtime/index.js

@@ -71,4 +71,33 @@ export function createSqlClient() {
         ...params,
     });
 }
+export function createAirtableClient(integrationId, className, implicitParams) {
+    return {
+        findAll: (options) => getSdkCall()(integrationId, className, "findAll", {
+            ...implicitParams,
+            ...options,
+        }),
+        findOne: (params) => getSdkCall()(integrationId, className, "findOne", {
+            ...implicitParams,
+            ...params,
+        }),
+        create: (data) => getSdkCall()(integrationId, className, "create", {
+            ...implicitParams,
+            ...data,
+        }),
+        bulkCreate: (records) => getSdkCall()(integrationId, className, "bulkCreate", {
+            ...implicitParams,
+            records,
+        }),
+        update: (id, data) => getSdkCall()(integrationId, className, "update", {
+            ...implicitParams,
+            id,
+            ...data,
+        }),
+        delete: (id) => getSdkCall()(integrationId, className, "delete", {
+            ...implicitParams,
+            id,
+        }),
+    };
+}
 export { createCaller } from "../caller/index.js";

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,30 +1,55 @@
-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;
     type: string;
 }>): string;
 export declare function generateAuthWrapperTs(): string;
+export type AirtableLockField = {
+    id: string;
+    sdkName: string;
+    type: string;
+    options?: string[];
+};
+export type AirtableLockTable = {
+    id: string;
+    sdkName: string;
+    fields: AirtableLockField[];
+};
+export type AirtableLock = {
+    integrationId: string;
+    tables: AirtableLockTable[];
+};
+export declare function generateAirtableTs(lock: AirtableLock): string | null;
 export declare function generateBackendWrapperTs(): 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);
         }
-        schema.tables[tableName] = { id: table.id, fields };
+        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,
+            });
+        }
+        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.",
@@ -198,6 +347,86 @@ export function generateAuthWrapperTs() {
         "",
     ].join("\n");
 }
+const AIRTABLE_FIELD_TYPE_MAP = {
+    singleLineText: "string",
+    multilineText: "string",
+    richText: "string",
+    email: "string",
+    url: "string",
+    phoneNumber: "string",
+    number: "number",
+    currency: "number",
+    percent: "number",
+    rating: "number",
+    duration: "number",
+    singleSelect: "string",
+    multipleSelects: "string[]",
+    checkbox: "boolean",
+    date: "string",
+    dateTime: "string",
+    attachment: "Array<{ url: string; filename?: string }>",
+    multipleRecordLinks: "string | string[]",
+    formula: "unknown",
+    rollup: "unknown",
+    lookup: "unknown",
+    count: "number",
+    autoNumber: "number",
+    barcode: "string",
+    button: "unknown",
+    createdTime: "string",
+    lastModifiedTime: "string",
+    createdBy: "unknown",
+    lastModifiedBy: "unknown",
+    externalSyncSource: "unknown",
+    aiText: "string",
+};
+function airtableTsType(field) {
+    if ((field.type === "singleSelect" || field.type === "multipleSelects") &&
+        field.options &&
+        field.options.length > 0) {
+        const literals = field.options
+            .slice(0, MAX_SELECT_OPTIONS)
+            .map((o) => `"${o.replace(/"/g, '\\"')}"`)
+            .join(" | ");
+        const union = `${literals} | string`;
+        if (field.type === "multipleSelects")
+            return `(${union})[]`;
+        return union;
+    }
+    return AIRTABLE_FIELD_TYPE_MAP[field.type] ?? "unknown";
+}
+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).",
+        "",
+        "import { createAirtableClient } from 'zitejs/runtime';",
+        "",
+    ];
+    for (const table of lock.tables) {
+        const recordType = `${table.sdkName}RecordType`;
+        lines.push(`export type ${recordType} = {`);
+        lines.push("  id: string;");
+        for (const field of table.fields) {
+            if (field.sdkName === "id")
+                continue;
+            const tsType = airtableTsType(field);
+            lines.push(`  ${field.sdkName}: ${tsType};`);
+        }
+        lines.push("};");
+        lines.push("");
+        lines.push(`export const ${table.sdkName} = createAirtableClient<${recordType}>(`);
+        lines.push(`  '${lock.integrationId}',`);
+        lines.push(`  '${table.sdkName}',`);
+        lines.push(`  { tableId: '${table.id}' },`);
+        lines.push(`);`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
 export function generateBackendWrapperTs() {
     return [
         "// Auto-generated type-narrowing wrapper. Do not edit manually.",