zitejs 0.10.0-start.7 → 0.10.0-start.8

package/dist/esm/start/data/dispatch.js

@@ -0,0 +1,198 @@
+import { buildSdkNameMappingsForBase } from "./sqlNameMappings.js";
+import { transformFieldNamesToIds, transformFieldsToFieldIds, transformFiltersToFieldIds, transformLinkedRecordFields, transformMatchOnFields, transformRecordToSdkNames, transformSortToFieldIds, } from "./transformations.js";
+import { ZITE_PLATFORM_FAULT_FLAG, } from "./types.js";
+export const DEMO_UNAVAILABLE_MESSAGE = "This action is not available in demo mode";
+// An allowlist, so a database method added later is refused until it's listed.
+const DEMO_READ_DATABASE_METHODS = new Set([
+    "findOne",
+    "findAll",
+    "executeSql",
+    "findAllUsers",
+    "getDatabaseSchema",
+]);
+const STATUS_TO_ZITE_ERROR_CODE = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    429: "RATE_LIMITED",
+};
+// A 4xx answers with its status as a coded ZiteError; a 5xx stays as thrown, flagged as ours, not the app's.
+export function asZiteClientError(error) {
+    const status = error?.statusCode;
+    if (typeof status !== "number" || status < 400)
+        return error;
+    if (status >= 500) {
+        if (error && typeof error === "object")
+            error[ZITE_PLATFORM_FAULT_FLAG] = true;
+        return error;
+    }
+    const tagged = new Error(error instanceof Error ? error.message : String(error));
+    tagged.name = "ZiteError";
+    tagged.code = STATUS_TO_ZITE_ERROR_CODE[status] ?? "BAD_REQUEST";
+    tagged.statusCode = status;
+    tagged.cause = error;
+    if (error instanceof Error)
+        tagged.stack = error.stack;
+    return tagged;
+}
+/** One `zite.*` data call, as classic's dispatch runs it. */
+export async function executeDatabasesCall(context, methodName, params) {
+    try {
+        return await runDatabasesCall(context, methodName, params ?? {});
+    }
+    catch (error) {
+        throw asZiteClientError(error);
+    }
+}
+async function runDatabasesCall(context, methodName, params) {
+    const { baseRunner: sdk, baseId, nameMappings, tables } = context;
+    if (context.readOnly && !DEMO_READ_DATABASE_METHODS.has(methodName)) {
+        throw Object.assign(new Error(DEMO_UNAVAILABLE_MESSAGE), { statusCode: 403 });
+    }
+    if (methodName === "findAllUsers") {
+        return sdk.auth.findAll({
+            baseId,
+            appIds: params.appIds,
+            filters: params.filters,
+            filter: params.filter,
+            offset: params.offset,
+            sort: params.sort,
+            limit: params.limit,
+        });
+    }
+    if (methodName === "updateUserProfile") {
+        const userId = params.userId ?? params.id;
+        const profile = params.profile ?? params.data ?? params.record ?? params;
+        if (!userId || !profile || typeof profile !== "object") {
+            throw new Error("updateUserProfile requires a user id and profile data");
+        }
+        if ("email" in profile) {
+            throw new Error("A Zite user email address cannot be updated");
+        }
+        return sdk.auth.update({
+            baseId,
+            userId,
+            profile: { firstName: profile.firstName, lastName: profile.lastName, image: profile.image },
+        });
+    }
+    if (methodName === "executeSql") {
+        const query = params?.query ?? params?.sql;
+        if (typeof query !== "string" || query.trim() === "") {
+            throw new Error("executeSql requires a non-empty `query` parameter");
+        }
+        return await sdk.sql.execute({
+            baseId,
+            sql: query,
+            params: params.params,
+            statementTimeoutMs: params.statementTimeoutMs,
+            nameMappings: nameMappings && tables
+                ? buildSdkNameMappingsForBase({ metadata: { tables }, settingsNameMappings: nameMappings })
+                : undefined,
+        });
+    }
+    const tableId = params.tableId;
+    if (!tableId) {
+        throw new Error("Databases calls require tableId in params");
+    }
+    const fieldMappings = nameMappings?.tables?.[tableId]?.fields;
+    const table = tables?.find((t) => t.id === tableId);
+    switch (methodName) {
+        case "findOne": {
+            const { id: recordId, filters, fields } = params;
+            const transformedFields = transformFieldsToFieldIds(fields, table, fieldMappings);
+            if (recordId) {
+                const record = await sdk.records.get({ baseId, tableId, recordId, fields: transformedFields });
+                return transformRecordToSdkNames(record, fieldMappings);
+            }
+            const result = await sdk.records.findAll({
+                baseId,
+                tableId,
+                filters: filters ? transformFiltersToFieldIds(filters, fieldMappings) : undefined,
+                limit: 1,
+                fields: transformedFields,
+            });
+            if (result.records.length === 0)
+                return undefined;
+            return transformRecordToSdkNames(result.records[0], fieldMappings);
+        }
+        case "findAll": {
+            const { filters, sort, limit, offset, fields } = params;
+            const result = await sdk.records.findAll({
+                baseId,
+                tableId,
+                filters: filters ? transformFiltersToFieldIds(filters, fieldMappings) : undefined,
+                sort: transformSortToFieldIds(sort, table, fieldMappings),
+                limit: limit || 500,
+                offset,
+                fields: transformFieldsToFieldIds(fields, table, fieldMappings),
+            });
+            return {
+                records: result.records
+                    .map((r) => transformRecordToSdkNames(r, fieldMappings))
+                    .filter((r) => r !== undefined),
+                hasMore: result.hasMore,
+            };
+        }
+        case "create": {
+            const { record: recordData } = params;
+            if (!recordData)
+                throw new Error("Create requires record data");
+            const record = await sdk.records.create({
+                baseId,
+                tableId,
+                record: transformLinkedRecordFields(transformFieldNamesToIds(recordData, table, fieldMappings), table),
+            });
+            const transformed = transformRecordToSdkNames(record, fieldMappings);
+            if (!transformed)
+                throw new Error("Failed to create record");
+            return transformed;
+        }
+        case "update": {
+            const { id: recordId, record: recordData } = params;
+            if (!recordId || !recordData)
+                throw new Error("Update requires id and record data");
+            const record = await sdk.records.update({
+                baseId,
+                tableId,
+                recordId,
+                record: transformLinkedRecordFields(transformFieldNamesToIds(recordData, table, fieldMappings), table),
+            });
+            const transformed = transformRecordToSdkNames(record, fieldMappings);
+            if (!transformed)
+                throw new Error("Failed to update record");
+            // Both flat and `fields`, for compatibility.
+            return { ...transformed, fields: transformed };
+        }
+        case "delete": {
+            const { id: recordId } = params;
+            if (!recordId)
+                throw new Error("Delete requires id parameter");
+            await sdk.records.delete({ baseId, tableId, recordId });
+            return { success: true, id: recordId };
+        }
+        case "bulkCreate": {
+            const { records: recordsData, matchOn } = params;
+            if (!recordsData || recordsData.length === 0)
+                return { records: [] };
+            const result = await sdk.records.bulkCreate({
+                baseId,
+                tableId,
+                records: recordsData.map((r) => transformLinkedRecordFields(transformFieldNamesToIds(r, table, fieldMappings), table)),
+                matchOn: transformMatchOnFields(matchOn, fieldMappings),
+            });
+            const records = result.records
+                .map((r) => transformRecordToSdkNames(r, fieldMappings))
+                .filter((r) => r !== undefined)
+                .map((record) => {
+                // Both flat and nested fields, for backwards compatibility.
+                const { id, ...fields } = record;
+                return { id, ...fields, fields };
+            });
+            return { success: true, records };
+        }
+        default:
+            throw new Error(`Unknown databases method: ${methodName}`);
+    }
+}

package/dist/esm/start/data/index.d.ts

@@ -0,0 +1,18 @@
+import type { DataNameMappings } from "./types.js";
+import type { HostMode, PlatformSession } from "../types.js";
+/** What generated `zite.*` calls go out under. */
+export declare const DATA_INTEGRATION_ID = "databases";
+type Found = {
+    baseId: string | null;
+    nameMappings: DataNameMappings | null;
+};
+/**
+ * The build's data context, or undefined from a host that predates the app's own
+ * dispatch, whose `databases` platform call still answers.
+ */
+export declare const dataContextOf: (session: PlatformSession) => Promise<Found | undefined>;
+/** One `zite.*` call, translated here and sent to base-runner through the platform. */
+export declare function runDataCall(session: PlatformSession, found: Found, mode: HostMode, methodName: string, sent: unknown): Promise<unknown>;
+/** For tests: forget what this isolate learned. */
+export declare const resetDataDispatch: () => void;
+export {};

package/dist/esm/start/data/index.js

@@ -0,0 +1,76 @@
+import { createBaseRunner } from "./baseRunner.js";
+import { asZiteClientError, executeDatabasesCall } from "./dispatch.js";
+/** What generated `zite.*` calls go out under. */
+export const DATA_INTEGRATION_ID = "databases";
+// Schema changes aren't redeployed, so a new table or field reaches calls within this, as on the host.
+const TABLES_REUSE_MS = 60_000;
+// One build per script, so per isolate: what the platform says the build's base is, and that base's tables.
+// Only answers are kept, never a pending call: one request's RPC session mustn't hold up another's.
+let context;
+let tables;
+let unsupported = false;
+const tablesOf = async (baseRunner, baseId) => {
+    if (tables?.baseId === baseId && Date.now() - tables.at < TABLES_REUSE_MS)
+        return tables.tables;
+    const base = await baseRunner.bases.get({ baseId });
+    tables = { baseId, tables: base.tables, at: Date.now() };
+    return base.tables;
+};
+// What Workers RPC throws for a method the host doesn't have yet.
+const NOT_IMPLEMENTED = /does not implement (?:the )?method/i;
+/**
+ * The build's data context, or undefined from a host that predates the app's own
+ * dispatch, whose `databases` platform call still answers.
+ */
+export const dataContextOf = async (session) => {
+    if (unsupported || !session.dataContext || !session.dataFetch)
+        return undefined;
+    if (context)
+        return context;
+    try {
+        const answer = await session.dataContext();
+        context = { baseId: answer.baseId, nameMappings: answer.nameMappings ?? null };
+        return context;
+    }
+    catch (error) {
+        if (error instanceof Error && NOT_IMPLEMENTED.test(error.message)) {
+            unsupported = true;
+            return undefined;
+        }
+        throw error;
+    }
+};
+/**
+ * The table id classic's generated client sends: its SDK name mapped through the
+ * build's name mappings, which on classic the client does from the run's config.
+ */
+const tableIdOf = (nameMappings, sent) => {
+    for (const [id, table] of Object.entries(nameMappings?.tables ?? {})) {
+        if (table.mapping?.sdkName === sent)
+            return id;
+    }
+    return sent;
+};
+/** One `zite.*` call, translated here and sent to base-runner through the platform. */
+export async function runDataCall(session, found, mode, methodName, sent) {
+    const params = sent && typeof sent === "object" && typeof sent.tableId === "string"
+        ? { ...sent, tableId: tableIdOf(found.nameMappings, sent.tableId) }
+        : sent;
+    if (!found.baseId)
+        throw asZiteClientError(Object.assign(new Error("This app has no database"), { statusCode: 404 }));
+    const baseRunner = createBaseRunner((request) => session.dataFetch(request));
+    let baseTables;
+    try {
+        baseTables = await tablesOf(baseRunner, found.baseId);
+    }
+    catch (error) {
+        throw asZiteClientError(error);
+    }
+    return executeDatabasesCall({ baseRunner, baseId: found.baseId, nameMappings: found.nameMappings, tables: baseTables, readOnly: mode === "demo" }, methodName, params);
+}
+/** For tests: forget what this isolate learned. */
+export const resetDataDispatch = () => {
+    context = undefined;
+    tables = undefined;
+    unsupported = false;
+};

package/dist/esm/start/data/sqlNameMappings.d.ts

@@ -0,0 +1,58 @@
+import type { NameMappings } from './types.js';
+/**
+ * Settings shape this helper reads — a subset of zite.lock's `nameMappings`
+ * carrying table and field SDK names keyed by tableId / fieldId.
+ */
+export interface SdkNameMappingsSourceSettings {
+    tables: Record<string, {
+        mapping: {
+            sdkName: string;
+        };
+        fields: Record<string, {
+            mapping: {
+                sdkName: string;
+            };
+        }>;
+    }>;
+}
+/**
+ * Minimum metadata shape this helper reads — tables, fields, and the
+ * `linked_record` edges between them. `template` is optional + loose-typed to
+ * accept both BaseMetadata and the runtime's SimpleTableDefinition shape.
+ *
+ * `deletedAt` accepts `Date` as well as the wire's ISO string so backend
+ * callers (whose metadata types carry model-shaped dates) can pass their
+ * tables straight through — only its truthiness is read.
+ */
+export interface SdkNameMappingsSourceMetadata {
+    tables: ReadonlyArray<{
+        id: string;
+        name: string;
+        deletedAt?: string | Date | null;
+        fields: ReadonlyArray<{
+            id: string;
+            name: string;
+            type: string;
+            deletedAt?: string | Date | null;
+            template?: {
+                tableId?: string;
+                isInverse?: boolean;
+            } & Record<string, unknown>;
+        }>;
+    }>;
+}
+/**
+ * Build the complete `NameMappings` wire payload for a base in SDK namespace.
+ * Applies the link-table conventions (alphabetical PascalCase concat for the
+ * name; `<tableCamel>Id` for column aliases) so base-runner does no
+ * derivations of its own.
+ *
+ * Dedupe rules mirror base-runner's `linkTablesByHumanName` keys:
+ *  - one entry per ordered pair of tables (forward + inverse collapse to one)
+ *  - forward direction wins for source/target orientation when both observed
+ *  - multiple `linked_record` fields between the same pair share one entry
+ */
+export declare const buildSdkNameMappingsForBase: ({ metadata, settingsNameMappings, }: {
+    metadata: SdkNameMappingsSourceMetadata;
+    settingsNameMappings: SdkNameMappingsSourceSettings;
+}) => NameMappings;

package/dist/esm/start/data/sqlNameMappings.js

@@ -0,0 +1,92 @@
+// SDK-name `NameMappings` builder for the SQL endpoint. Lives next to the
+// other SDK-name-aware transformations in this package (e.g.
+// `transformRecordToSdkNames`) so cloudflare-lambda can import it without
+// taking a runtime dep on `@fillout/zite`. Pure data transformation — walks
+// BaseMetadata + the zite.lock-style nameMappings and applies the link-table
+// conventions to produce a complete wire payload.
+const getLinkTableSdkName = (a, b) => {
+    const [first, second] = [a, b].sort();
+    return `${first}${second}`;
+};
+const getLinkColumnSdkAlias = (sdkTableName, side, isSelfReference) => {
+    const camel = sdkTableName.charAt(0).toLowerCase() + sdkTableName.slice(1);
+    if (isSelfReference) {
+        return `${side}${camel.charAt(0).toUpperCase()}${camel.slice(1)}Id`;
+    }
+    return `${camel}Id`;
+};
+/**
+ * Build the complete `NameMappings` wire payload for a base in SDK namespace.
+ * Applies the link-table conventions (alphabetical PascalCase concat for the
+ * name; `<tableCamel>Id` for column aliases) so base-runner does no
+ * derivations of its own.
+ *
+ * Dedupe rules mirror base-runner's `linkTablesByHumanName` keys:
+ *  - one entry per ordered pair of tables (forward + inverse collapse to one)
+ *  - forward direction wins for source/target orientation when both observed
+ *  - multiple `linked_record` fields between the same pair share one entry
+ */
+export const buildSdkNameMappingsForBase = ({ metadata, settingsNameMappings, }) => {
+    const tablesById = new Map();
+    for (const t of metadata.tables) {
+        if (!t.deletedAt)
+            tablesById.set(t.id, t);
+    }
+    const tables = {};
+    for (const table of metadata.tables) {
+        if (table.deletedAt)
+            continue;
+        const tableMapping = settingsNameMappings.tables[table.id];
+        if (!tableMapping)
+            continue;
+        const fields = {};
+        for (const field of table.fields) {
+            if (field.deletedAt)
+                continue;
+            const sdkName = tableMapping.fields[field.id]?.mapping.sdkName;
+            if (sdkName)
+                fields[field.name] = sdkName;
+        }
+        tables[table.name] = {
+            displayName: tableMapping.mapping.sdkName,
+            fields,
+        };
+    }
+    const linkTables = {};
+    for (const source of metadata.tables) {
+        if (source.deletedAt)
+            continue;
+        for (const field of source.fields) {
+            if (field.deletedAt)
+                continue;
+            if (field.type !== 'linked_record')
+                continue;
+            // Only forward fields drive the entry. Inverse fields are auto-generated
+            // mirrors of a forward field on the other side — using them would flip
+            // the source/target orientation. Multiple forward fields between the
+            // same pair (e.g. Orders.customer + Orders.shippingAddress → Customers)
+            // produce identical entries, so the repeated write is idempotent.
+            if (field.template?.isInverse === true)
+                continue;
+            const targetTableId = field.template?.tableId;
+            if (!targetTableId)
+                continue;
+            const target = tablesById.get(targetTableId);
+            if (!target)
+                continue;
+            const sourceSdkName = settingsNameMappings.tables[source.id]?.mapping.sdkName;
+            const targetSdkName = settingsNameMappings.tables[target.id]?.mapping.sdkName;
+            if (!sourceSdkName || !targetSdkName)
+                continue;
+            const [humanFirst, humanSecond] = [source.name, target.name].sort();
+            const humanLinkName = `${humanFirst}__${humanSecond}`;
+            const isSelfReference = source.id === target.id;
+            linkTables[humanLinkName] = {
+                displayName: getLinkTableSdkName(sourceSdkName, targetSdkName),
+                sourceIdColumnAlias: getLinkColumnSdkAlias(sourceSdkName, 'source', isSelfReference),
+                targetIdColumnAlias: getLinkColumnSdkAlias(targetSdkName, 'target', isSelfReference),
+            };
+        }
+    }
+    return { tables, linkTables };
+};

package/dist/esm/start/data/transformations.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Database Record Transformation Utilities
+ *
+ * Shared transformation functions for converting between:
+ * - SDK field names ↔ database field IDs
+ * - LLM-friendly formats ↔ database formats
+ *
+ * Used by both workflow-runner and cloudflare-lambda.
+ */
+import type { SimpleTableDefinition, FieldMappings, DatabaseRecord } from './types.js';
+/**
+ * Build reverse lookup map: sdkName → fieldId
+ */
+export declare function buildSdkNameToFieldIdMap(fieldMappings: FieldMappings | undefined): Record<string, string>;
+/**
+ * Transform SDK field names to database field IDs in filters
+ */
+export declare function transformFiltersToFieldIds(filters: Record<string, unknown>, fieldMappings: FieldMappings | undefined): Record<string, unknown>;
+/**
+ * Transform SDK field names to database field IDs inside a formula expression.
+ *
+ * The base-runner formula evaluator only accepts display names or field IDs
+ * in `{fieldRef}` placeholders — never SDK names. The LLM, however, sees the
+ * codebase through the SDK (camelCase fields like `count`), so it naturally
+ * writes `{count}` in expressions. This rewrite normalizes those references
+ * to field IDs at the SDK boundary, mirroring how `transformFiltersToFieldIds`
+ * normalizes filter keys.
+ *
+ * Behavior:
+ * - `{sdkName}` → `{fieldId}` when sdkName matches a field in `fieldMappings`
+ * - `{fieldId}` → unchanged (already a valid id)
+ * - `{anything else}` → unchanged (let the formula validator reject with a
+ *   clear, table-specific error message)
+ * - `{linkField.targetField}` (cross-table) → unchanged (target field lives
+ *   in another table; resolving it requires a separate per-link mapping
+ *   that the SDK boundary doesn't have)
+ */
+export declare function transformFormulaExpressionToFieldIds(expression: string, fieldMappings: FieldMappings | undefined): string;
+/**
+ * Transform record data to use field IDs instead of field names.
+ *
+ * LLMs often use human-readable field names, but the database expects field IDs.
+ * Uses a three-step fallback:
+ * 1. Check if key is already a valid field ID
+ * 2. Match by field name (case-insensitive)
+ * 3. Match by SDK name from field mappings
+ *
+ * @param recordData - The record data with potentially mixed keys
+ * @param table - Table definition for field name lookups (optional)
+ * @param fieldMappings - SDK name mappings (optional)
+ */
+export declare function transformFieldNamesToIds(recordData: Record<string, unknown>, table: SimpleTableDefinition | undefined, fieldMappings: FieldMappings | undefined): Record<string, unknown>;
+/**
+ * Simple transformation using only field mappings (no table definition).
+ * Used when table metadata is not available.
+ */
+export declare function transformRecordToFieldIds(recordData: Record<string, unknown>, fieldMappings: FieldMappings | undefined): Record<string, unknown>;
+/**
+ * Transform linked record fields to ensure they are arrays.
+ *
+ * Handles common LLM mistakes:
+ * - Passing a string instead of an array of record IDs
+ * - Passing null/undefined instead of an empty array
+ * - Passing literal strings like "null" or "undefined"
+ *
+ * @param recordData - Record data (should already have field IDs as keys)
+ * @param table - Table definition for field type lookups
+ */
+export declare function transformLinkedRecordFields(recordData: Record<string, unknown>, table: SimpleTableDefinition | undefined): Record<string, unknown>;
+/**
+ * Transform database record to use SDK field names
+ *
+ * @param record - Raw database record with field IDs
+ * @param fieldMappings - SDK name mappings
+ */
+export declare function transformRecordToSdkNames(record: {
+    id: string;
+    data: Record<string, unknown>;
+} | undefined, fieldMappings: FieldMappings | undefined): DatabaseRecord | undefined;
+/**
+ * Transform multiple records for input (SDK → Database)
+ */
+export declare function transformRecordsForInput(records: Record<string, unknown>[], table: SimpleTableDefinition | undefined, fieldMappings: FieldMappings | undefined): Record<string, unknown>[];
+/**
+ * Transform multiple records for output (Database → SDK)
+ */
+export declare function transformRecordsForOutput(records: Array<{
+    id: string;
+    data: Record<string, unknown>;
+}>, fieldMappings: FieldMappings | undefined): DatabaseRecord[];
+/**
+ * Transform an array of SDK field names to field IDs.
+ *
+ * Used for the `fields` parameter in findOne/findAll to select which fields to return.
+ * Uses the same three-step fallback as transformFieldNamesToIds:
+ * 1. Check if name is already a valid field ID
+ * 2. Match by field name (case-insensitive)
+ * 3. Match by SDK name from field mappings
+ *
+ * @param fields - Array of SDK field names (e.g. ['customerName', 'email'])
+ * @param table - Table definition for field name lookups (optional)
+ * @param fieldMappings - SDK name mappings (optional)
+ * @returns Array of field IDs, or undefined if input is undefined
+ */
+export declare function transformFieldsToFieldIds(fields: string[] | undefined, table: SimpleTableDefinition | undefined, fieldMappings: FieldMappings | undefined): string[] | undefined;
+/**
+ * Resolve the field references in a sort spec to field IDs.
+ *
+ * Sort arrives from app code using SDK names (`closeDate`), but base-runner
+ * resolves sort fields by field ID or display name only, and silently skips one
+ * it cannot match. Running the references through the same resolution order as
+ * `fields` is what makes a sort on a multi-word field ("Close date" ->
+ * `closeDate`) actually apply instead of being dropped without an error.
+ *
+ * System sort fields (`id`, `createdAt`, `updatedAt`) have no mapping and fall
+ * through unchanged, which is what base-runner expects.
+ */
+export declare function transformSortToFieldIds(sort: string | Array<{
+    field: string;
+    direction?: 'asc' | 'desc';
+}> | undefined, table: SimpleTableDefinition | undefined, fieldMappings: FieldMappings | undefined): Array<{
+    field: string;
+    direction: 'asc' | 'desc';
+}> | undefined;
+/**
+ * Transform matchOn field names to field IDs
+ */
+export declare function transformMatchOnFields(matchOn: string[] | undefined, fieldMappings: FieldMappings | undefined): string[] | undefined;