zitejs 0.9.94 → 0.9.96

package/dist/esm/sync/lib.js

@@ -1,5 +1,6 @@
 import { parse } from "@babel/parser";
 const AUTH_USERS_TABLE_ID = "zite_user";
+/** What a field's value looks like when a record is READ back. */
 const FIELD_TYPE_MAP = {
     single_line_text: "string",
     long_text: "string",
@@ -17,16 +18,79 @@ const FIELD_TYPE_MAP = {
     checkbox: "boolean",
     date: "string | null",
     datetime: "string | null",
-    attachments: "Array<{ url: string; name?: string }>",
-    linked_record: "string | string[]",
-    user: "string | string[]",
+    attachments: "ZiteAttachment[]",
+    // base-runner normalizes both of these to an array on write and stores them
+    // that way, so a read never produces a bare string.
+    linked_record: "string[]",
+    user: "string[]",
     lookup: "unknown",
+    rollup: "unknown",
     autonumber: "number",
     source: "string",
     formula: "unknown",
     created_at: "string",
     updated_at: "string",
+    updated_by: "string | null",
 };
+/**
+ * Field types whose WRITE shape differs from their read shape — the API accepts
+ * looser input than it stores.
+ */
+const FIELD_INPUT_TYPE_MAP = {
+    attachments: "ZiteAttachmentInput[]",
+    linked_record: "string | string[] | null",
+    user: "string | string[] | null",
+};
+/**
+ * Computed and system-managed fields, omitted from the generated input type
+ * rather than typed and then refused at runtime.
+ *
+ * Mirrors `COMPUTED_FIELD_TYPES` in the product's own `shared/bases/fields`.
+ * The first six are rejected by `createRecordDataSchema` — each has a
+ * `refine(val => val == null)`, so a non-null write errors (null is a no-op
+ * clear). `created_at` / `updated_at` are refused differently: they have no
+ * column at all, so a write is silently dropped, which is the worse outcome to
+ * leave typed as writable.
+ */
+const READ_ONLY_FIELD_TYPES = new Set([
+    "lookup",
+    "rollup",
+    "source",
+    "formula",
+    "autonumber",
+    "updated_by",
+    "created_at",
+    "updated_at",
+]);
+/**
+ * Emitted once per `db.ts`. The old inline `{ url: string; name?: string }` was
+ * wrong in both directions: `name` is not a property the API returns (it is
+ * `filename` / `originalName`), and the other six read properties were missing.
+ */
+const ATTACHMENT_TYPES = [
+    "/** An attachment as returned when reading a record. */",
+    "export type ZiteAttachment = {",
+    "  /** Original filename as uploaded. */",
+    "  filename: string;",
+    "  /** Display name — may differ from `filename`. */",
+    "  originalName: string;",
+    "  /** File size in bytes. */",
+    "  size: number;",
+    "  mimeType: string;",
+    "  /** Publicly accessible URL. */",
+    "  url: string;",
+    "  /** ISO timestamp of the upload. */",
+    "  uploadedAt: string;",
+    "  metadata?: Record<string, unknown>;",
+    "};",
+    "",
+    "/** What you may write to an attachments field: a URL, a URL with a name, or an attachment you read earlier. */",
+    "export type ZiteAttachmentInput =",
+    "  | string",
+    "  | { url: string; filename?: string }",
+    "  | ZiteAttachment;",
+    "",
+];
 const MAX_SELECT_OPTIONS = 100;
 const NUMBER_FORMAT_EXAMPLES = {
     local: "1,000,000.50",
@@ -43,6 +107,19 @@ const DURATION_FORMAT_EXAMPLES = {
     "h:mm:ss.ss": "1:23:03.00",
     "h:mm:ss.sss": "1:23:03.000",
 };
+// Naming the format alone ("display as `european` format") doesn't say what to
+// render — these mirror the pickers in the database UI, which is what the user
+// chose from. `local` is the viewer's system locale, so it has no fixed example.
+const DATE_FORMAT_EXAMPLES = {
+    long: "January 15, 2024",
+    us: "1/15/2024",
+    european: "15/01/2024",
+    iso: "2024-01-15",
+};
+const withDateFormatExample = (format) => {
+    const example = DATE_FORMAT_EXAMPLES[format];
+    return example ? `"${format}" format (e.g. ${example})` : `"${format}" format`;
+};
 export function toPascalCase(name) {
     const pascal = name
         .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
@@ -69,7 +146,7 @@ function keepValidSdkName(sdkName) {
         return undefined;
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(sdkName) ? sdkName : undefined;
 }
-function tsTypeForSchemaField(def) {
+function tsTypeForSchemaField(def, variant = "read") {
     if (def.type === "single_select" || def.type === "multiple_select") {
         const options = def.template
             ?.options;
@@ -84,11 +161,17 @@ function tsTypeForSchemaField(def) {
             return union;
         }
     }
+    if (variant === "write" && FIELD_INPUT_TYPE_MAP[def.type]) {
+        return FIELD_INPUT_TYPE_MAP[def.type];
+    }
     if (FIELD_TYPE_MAP[def.type])
         return FIELD_TYPE_MAP[def.type];
-    return "string";
+    // Not `string`. A field type this generator doesn't know about is not a
+    // string just because most of them are — asserting one lets `record.value`
+    // silently pass as `string` everywhere it flows.
+    return "unknown";
 }
-function fieldJsdoc(schemaField, table) {
+function fieldJsdoc(schemaField, table, schema) {
     const def = schemaField.definition;
     const parts = [];
     if (table.primaryFieldId === schemaField.id)
@@ -102,8 +185,12 @@ function fieldJsdoc(schemaField, table) {
     }
     if (def.type === "linked_record") {
         const tpl = def.template;
-        if (tpl.tableId)
-            parts.push(`Links to table ${tpl.tableId}`);
+        if (tpl.tableId) {
+            // The SDK name, not the raw `tbl...` id — the id appears nowhere the
+            // reader can act on, while the SDK name is the property on `zite`.
+            const linked = schema?.tables.find((t) => t.id === tpl.tableId);
+            parts.push(`Links to ${linked ? linked.sdkName : tpl.tableId}`);
+        }
         if (tpl.allowMultiple === false)
             parts.push("Single record only");
     }
@@ -111,13 +198,13 @@ function fieldJsdoc(schemaField, table) {
     if (def.type === "date") {
         const tpl = def.template;
         if (tpl.dateFormat)
-            parts.push(`Date-only field (YYYY-MM-DD string), null when unset, display as "${tpl.dateFormat}" format`);
+            parts.push(`Date-only field (YYYY-MM-DD string), null when unset, display as ${withDateFormatExample(tpl.dateFormat)}`);
     }
     if (def.type === "datetime") {
         const tpl = def.template;
         const timeParts = ["Date+time field (ISO 8601 timestamp), null when unset"];
         if (tpl.dateFormat)
-            timeParts.push(`date: ${tpl.dateFormat}`);
+            timeParts.push(`date: ${withDateFormatExample(tpl.dateFormat)}`);
         if (tpl.timeFormat)
             timeParts.push(`time: ${tpl.timeFormat}`);
         if (tpl.timezone)
@@ -236,12 +323,13 @@ function generateSentinelSdkTypes() {
         "  | { created: number }",
         "  | { created: 0; preview: true; wouldCreate: number };",
         "",
+        // Must match `AuthUser` in zitejs/runtime and `User` in zitejs/auth.
         "export interface ZiteAuthUser {",
         "  id: string;",
         "  name: string;",
         "  email: string;",
-        "  firstName: string | null;",
-        "  lastName: string | null;",
+        "  firstName?: string;",
+        "  lastName?: string;",
         "  image: string | null;",
         "}",
         "",
@@ -311,13 +399,30 @@ export function generateDbTs(schema) {
     lines.push("//");
     lines.push("// Table client methods (all take a single params object):");
     lines.push("//   .findAll({ filters?, sort?, offset?, limit?, fields? }) → { records: T[], hasMore: boolean }");
-    lines.push("//     filters: { fieldName: value } for equality, { fieldName: { contains|gt|lt|gte|lte: value } } for operators");
+    lines.push("//     filters: { fieldName: value } for equality, or { fieldName: { <op>: value } }");
+    lines.push("//     operators: contains, not, in, notIn, lt, lte, gt, gte");
+    lines.push('//       `not: null` means "is set"; `in`/`notIn` with an empty array apply NO filter');
     lines.push("//     sort: [{ field: 'fieldName', direction: 'asc' | 'desc' }]");
+    lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
     lines.push("//   .update({ id, record }) → { id: string, fields: Partial<T> }");
-    lines.push("//   .delete({ id }) → { id: string }");
+    lines.push("//   .delete({ id }) → { success: true, id: string }");
     lines.push("//   .bulkCreate({ records, matchOn? }) → { success: boolean, records: T[] }");
+    lines.push("//     up to 100 records per call; matchOn upserts on those fields");
+    lines.push("//");
+    lines.push("// Reading these types:");
+    lines.push("//   SDK names are stable identifiers — they do NOT change when a table or field is");
+    lines.push('//   renamed. Each carries its current user-facing name in quotes (// "Task Name").');
+    lines.push("//   Where the two differ the field was renamed, and the quoted name is what it means");
+    lines.push("//   now — treat it as the source of truth.");
+    lines.push("//   Values are RAW: dates are ISO strings, durations are seconds. Format them for");
+    lines.push("//   display yourself, following the display config in each field's comment.");
+    lines.push("//   PERCENT fields are stored as decimals — 0.5 is 50%, 1.0 is 100%.");
+    lines.push("//   LINKED RECORD fields hold UUID record ids from findOne/findAll — never invent one.");
+    lines.push("//   Computed and system-managed fields (formula, rollup, lookup, autonumber,");
+    lines.push("//   created/updated timestamps and more) are absent from the *Input types —");
+    lines.push("//   a write to one is rejected or silently dropped.");
     lines.push("//");
     lines.push("// Zite auth users:");
     lines.push("//   zite.auth.findAllUsers({ appIds?, filter?, filters?, sort?, limit?, offset? })");
@@ -329,6 +434,9 @@ export function generateDbTs(schema) {
     lines.push("// Raw SQL (read-only SELECTs for aggregates, joins, multi-table queries):");
     lines.push('//   zite.sql({ query: "SELECT ...", params?: [...] })');
     lines.push("//     → { rows: Record<string, unknown>[], columns, rowCount, truncated }");
+    lines.push("//     Capped at 2000 rows — `truncated: true` means there were more, so paginate in");
+    lines.push("//     SQL rather than assuming you got everything. Queries time out after 10s.");
+    lines.push("//     columns[].name is the SDK name; columns[].originalName is the underlying", "//     database column (or your own SQL alias).");
     lines.push("//");
     lines.push("// SQL guidelines:");
     lines.push("//   - Use SDK names for tables (PascalCase) and fields (camelCase)");
@@ -341,16 +449,18 @@ export function generateDbTs(schema) {
     lines.push(...buildLinkTableComments(schema));
     lines.push("import { createTableClient, createSqlClient, createNotificationsClient, createAuthClient } from 'zitejs/runtime';");
     lines.push("");
+    lines.push(...ATTACHMENT_TYPES);
     for (const table of tables) {
         const className = toPascalCase(table.sdkName);
         const recordType = `${className}RecordType`;
+        lines.push(`/** A ${table.sdkName} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
             if (field.sdkName === "id")
                 continue;
             const tsType = tsTypeForSchemaField(field.definition);
-            const jsdoc = fieldJsdoc(field, table);
+            const jsdoc = fieldJsdoc(field, table, schema);
             if (jsdoc) {
                 lines.push(`  /** ${jsdoc} */`);
             }
@@ -358,12 +468,24 @@ export function generateDbTs(schema) {
         }
         lines.push("};");
         lines.push("");
+        // The write shape is a separate type, not `Partial<RecordType>`: computed
+        // fields can't be written at all, and several field types accept looser
+        // input than they store (an attachments field takes a URL string; a linked
+        // record takes one id or many).
+        const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_FIELD_TYPES.has(f.definition.type));
+        lines.push(`/** What you may write when creating or updating a ${table.sdkName}. */`);
+        lines.push(`export type ${className}RecordInput = {`);
+        for (const field of writableFields) {
+            lines.push(`  ${field.sdkName}: ${tsTypeForSchemaField(field.definition, "write")};`);
+        }
+        lines.push("};");
+        lines.push("");
     }
     lines.push(...generateSentinelSdkTypes());
     lines.push("export const zite = {");
     for (const table of tables) {
         const className = toPascalCase(table.sdkName);
-        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType>('${className}'),`);
+        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType, ${className}RecordInput>('${className}'),`);
     }
     lines.push(`  sql: createSqlClient(),`);
     lines.push(`  notifications: createNotificationsClient(),`);
@@ -372,47 +494,136 @@ export function generateDbTs(schema) {
     lines.push("");
     return lines.join("\n");
 }
-function detectStreamEnabled(source) {
+const NOT_AN_ENDPOINT = {
+    isEndpoint: false,
+    hasDefaultExport: false,
+    stream: false,
+};
+/** `createEndpoint(...)` anywhere in the expression, through wrappers. */
+function callsCreateEndpoint(node) {
+    if (!node || typeof node !== "object")
+        return false;
+    const n = node;
+    if (n.type === "CallExpression" &&
+        n.callee?.name ===
+            "createEndpoint") {
+        return true;
+    }
+    return Object.values(n).some((v) => Array.isArray(v) ? v.some(callsCreateEndpoint) : callsCreateEndpoint(v));
+}
+/** Unwrap `x satisfies T` / `x as const` to the expression underneath. */
+function unwrapExpression(node) {
+    let current = node;
+    while ((current?.type === "TSAsExpression" ||
+        current?.type === "TSSatisfiesExpression" ||
+        current?.type === "TSNonNullExpression" ||
+        current?.type === "ParenthesizedExpression") &&
+        current.expression) {
+        current = current.expression;
+    }
+    return current;
+}
+function inspectEndpointFile(source) {
+    let ast;
     try {
-        const ast = parse(source, {
-            sourceType: "module",
-            plugins: ["typescript"],
-        });
-        const defaultExport = ast.program.body.find((n) => n.type === "ExportDefaultDeclaration" &&
-            n.declaration.type === "CallExpression");
-        if (!defaultExport || defaultExport.type !== "ExportDefaultDeclaration")
-            return false;
-        const call = defaultExport.declaration;
-        if (call.type !== "CallExpression" || call.arguments.length === 0)
-            return false;
-        const arg = call.arguments[0];
-        if (arg.type !== "ObjectExpression")
-            return false;
-        const streamProp = arg.properties.find((p) => p.type === "ObjectProperty" &&
-            ((p.key.type === "Identifier" && p.key.name === "stream") ||
-                (p.key.type === "StringLiteral" && p.key.value === "stream")));
-        if (!streamProp || streamProp.type !== "ObjectProperty")
-            return false;
-        return (streamProp.value.type === "BooleanLiteral" &&
-            streamProp.value.value === true);
+        ast = parse(source, { sourceType: "module", plugins: ["typescript"] });
     }
     catch {
-        return false;
+        // Unparseable with a TS-only plugin set — most likely TSX, which is still
+        // a real endpoint file. Assume yes and let the app's own typecheck judge
+        // it, rather than dropping a route the bundler will deploy regardless.
+        return { isEndpoint: true, hasDefaultExport: true, stream: false };
     }
+    const body = ast.program.body;
+    const hasDefaultExport = body.some((n) => n.type === "ExportDefaultDeclaration" ||
+        (n.type === "ExportNamedDeclaration" &&
+            n.specifiers?.some((spec) => spec.type === "ExportSpecifier" &&
+                (spec.exported.type === "Identifier"
+                    ? spec.exported.name
+                    : spec.exported.value) === "default")));
+    const isEndpoint = hasDefaultExport || body.some(callsCreateEndpoint);
+    if (!isEndpoint)
+        return NOT_AN_ENDPOINT;
+    // Stream detection is best-effort on the literal config: it is the only
+    // shape we can read `stream: true` out of statically.
+    const defaultExport = body.find((n) => n.type === "ExportDefaultDeclaration");
+    const call = defaultExport
+        ? unwrapExpression(defaultExport.declaration)
+        : undefined;
+    const arg = call?.type === "CallExpression"
+        ? unwrapExpression(call.arguments?.[0] ?? {})
+        : undefined;
+    if (arg?.type !== "ObjectExpression") {
+        return { isEndpoint, hasDefaultExport, stream: false };
+    }
+    const streamProp = arg.properties.find((prop) => prop.type === "ObjectProperty" &&
+        ((prop.key?.type === "Identifier" && prop.key.name === "stream") ||
+            (prop.key?.type === "StringLiteral" && prop.key.value === "stream")));
+    const stream = streamProp?.value?.type === "BooleanLiteral" &&
+        streamProp.value.value === true;
+    return { isEndpoint, hasDefaultExport, stream };
 }
+/**
+ * Reserved words can't be `const` names. The route is the filename either way,
+ * so only the generated identifier needs escaping — `default.ts` becomes
+ * `export const _default`, still reachable as `api.default` because reserved
+ * words are legal object keys.
+ */
+const RESERVED_IDENTIFIERS = new Set([
+    "await", "break", "case", "catch", "class", "const", "continue", "debugger",
+    "default", "delete", "do", "else", "enum", "export", "extends", "false",
+    "finally", "for", "function", "if", "implements", "import", "in",
+    "instanceof", "interface", "let", "new", "null", "package", "private",
+    "protected", "public", "return", "static", "super", "switch", "this",
+    "throw", "true", "try", "typeof", "var", "void", "while", "with", "yield",
+]);
+const toSafeIdentifier = (camelName) => RESERVED_IDENTIFIERS.has(camelName) ? `_${camelName}` : camelName;
 export function generateApiTs(endpointFiles) {
     if (!endpointFiles || endpointFiles.length === 0)
         return null;
     const endpoints = [];
+    const seenIdents = new Set();
+    const skipped = [];
     for (const file of endpointFiles) {
         const fileName = typeof file === "string" ? file : file.fileName;
         const content = typeof file === "string" ? undefined : file.content;
-        const name = fileName.replace(/\.(ts|js)$/, "");
-        const camelName = toCamelCase(name);
-        const pascal = toPascalCase(camelName);
-        const stream = content ? detectStreamEnabled(content) : false;
-        endpoints.push({ camelName, pascal, stream });
+        // `foo.d.ts` -> baseName `foo.d`, which imports nothing and camelCases to
+        // `fooD`. Declaration files are never endpoints.
+        if (fileName.endsWith(".d.ts"))
+            continue;
+        // Callers that pass bare filenames can't be filtered — every in-tree caller
+        // passes content, and so does the backend's migration assembler.
+        const shape = content ? inspectEndpointFile(content) : undefined;
+        if (shape && !shape.isEndpoint) {
+            skipped.push(fileName);
+            continue;
+        }
+        const baseName = fileName.replace(/\.(ts|js)$/, "");
+        const key = toCamelCase(baseName);
+        const ident = toSafeIdentifier(key);
+        // Distinct files can collide on one identifier (`send-email.ts` and
+        // `send_email.ts` both camelCase to `sendEmail`), which used to emit the
+        // same `export const` twice. First-wins, which is stable because every
+        // caller sorts its input before calling — the two in this package and
+        // `generateApiClient` in the backend's migration assembler.
+        if (seenIdents.has(ident)) {
+            skipped.push(`${fileName} (name collides with '${ident}')`);
+            continue;
+        }
+        seenIdents.add(ident);
+        endpoints.push({
+            baseName,
+            key,
+            ident,
+            pascal: toPascalCase(key),
+            stream: shape?.stream ?? false,
+            // No content to inspect means a bare-filename caller, which historically
+            // assumed a default export — keep that assumption.
+            typed: shape ? shape.hasDefaultExport : true,
+        });
     }
+    if (endpoints.length === 0)
+        return null;
     const hasStreaming = endpoints.some((e) => e.stream);
     const lines = [
         "// Auto-generated by zitejs generate. Do not edit manually.",
@@ -422,30 +633,52 @@ export function generateApiTs(endpointFiles) {
             : "import { createCaller } from 'zitejs/caller';",
         "",
     ];
-    for (const { pascal, camelName } of endpoints) {
-        const name = camelName.replace(/([A-Z])/g, "-$1").toLowerCase();
-        const rawName = endpointFiles[endpoints.findIndex((e) => e.camelName === camelName)];
-        const fileName = typeof rawName === "string" ? rawName : rawName.fileName;
-        const baseName = fileName.replace(/\.(ts|js)$/, "");
+    if (skipped.length > 0) {
+        lines.push("// Not endpoints, so no callers were generated for them:");
+        for (const name of skipped)
+            lines.push(`//   ${name}`);
+        lines.push("");
+    }
+    for (const { pascal, baseName, typed } of endpoints) {
+        if (!typed)
+            continue;
         lines.push(`import type { default as _${pascal}Ep } from '../src/api/${baseName}';`);
     }
     lines.push("");
-    for (const { camelName, pascal, stream } of endpoints) {
+    for (const { baseName, ident, pascal, stream, typed } of endpoints) {
+        if (!typed) {
+            // Declared with `export const x = createEndpoint(...)` — the 1.0 shape.
+            // The route is real and the bundler deploys it, so the caller has to
+            // exist; there is just no default export to read its types from.
+            lines.push(`// '${baseName}' has no default export, so its input/output are untyped.`);
+            lines.push(`export type ${pascal}InputType = unknown;`);
+            lines.push(`export type ${pascal}OutputType = unknown;`);
+            lines.push(`export const ${ident} = ${stream ? "createStreamingCaller" : "createCaller"}<${pascal}InputType, ${pascal}OutputType>('${baseName}');`);
+            lines.push("");
+            continue;
+        }
         lines.push(`type _${pascal}Cfg = typeof _${pascal}Ep;`);
-        lines.push(`export type ${pascal}InputType = Parameters<_${pascal}Cfg['execute']>[0]['input'];`);
+        // A caller sends the schema's INPUT type, not its output: a field with a
+        // `.default()` or a transform is optional to send and guaranteed on the
+        // other side. Reading it off `execute` gave the output type, so callers
+        // were forced to pass values the schema exists to supply. `NonNullable`
+        // because `inputSchema` is optional — without it the conditional always
+        // took the fallback branch.
+        lines.push(`export type ${pascal}InputType = NonNullable<_${pascal}Cfg['inputSchema']> extends { _input: infer I } ? I : Parameters<_${pascal}Cfg['execute']>[0]['input'];`);
         lines.push(`export type ${pascal}OutputType = Awaited<ReturnType<_${pascal}Cfg['execute']>>;`);
-        if (stream) {
-            lines.push(`export const ${camelName} = createStreamingCaller<${pascal}InputType, ${pascal}OutputType>('${camelName}');`);
-        }
-        else {
-            lines.push(`export const ${camelName} = createCaller<${pascal}InputType, ${pascal}OutputType>('${camelName}');`);
-        }
+        // The route is the filename, not the camelCased identifier: the bundler
+        // keys endpoints by filename base and the runner looks up `/api/:name`
+        // against those keys, so `send-email.ts` is reachable at `/api/send-email`.
+        // Calling it `sendEmail` here made every hyphenated or snake_cased endpoint
+        // a 404.
+        const caller = stream ? "createStreamingCaller" : "createCaller";
+        lines.push(`export const ${ident} = ${caller}<${pascal}InputType, ${pascal}OutputType>('${baseName}');`);
         lines.push("");
     }
     lines.push("");
     lines.push("export const api = {");
-    for (const { camelName } of endpoints) {
-        lines.push(`  ${camelName},`);
+    for (const { key, ident } of endpoints) {
+        lines.push(key === ident ? `  ${ident},` : `  ${key}: ${ident},`);
     }
     lines.push("};");
     lines.push("");
@@ -475,8 +708,8 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     dateTime: "string",
     singleSelect: "string",
     multipleSelects: "string[]",
-    multipleAttachments: "Array<{ url: string; filename?: string }>",
-    multipleRecordLinks: "string | string[]",
+    multipleAttachments: "AirtableAttachment[]",
+    multipleRecordLinks: "string[]",
     singleCollaborator: "{ id: string; email: string; name?: string }",
     multipleCollaborators: "Array<{ id: string; email: string; name?: string }>",
     // Read-only fields
@@ -493,7 +726,49 @@ const AIRTABLE_FIELD_TYPE_MAP = {
     externalSyncSource: "unknown",
     aiText: "string",
 };
-function airtableTsType(field, lock, depth) {
+/**
+ * Field types whose WRITE shape is looser than what Airtable returns.
+ * Attachments come back as full `AirtableAttachment` objects but are written as
+ * `{ url, filename? }`; a link field returns an array but accepts one id.
+ */
+const AIRTABLE_FIELD_INPUT_TYPE_MAP = {
+    multipleAttachments: "Array<{ url: string; filename?: string }>",
+    multipleRecordLinks: "string | string[]",
+    singleCollaborator: "{ id: string } | { email: string }",
+    multipleCollaborators: "Array<{ id: string } | { email: string }>",
+};
+/** Mirrors `airtable/lib/attachment.d.ts`. Every property but `thumbnails` is present on a read. */
+const AIRTABLE_ATTACHMENT_TYPE = [
+    "export type AirtableAttachment = {",
+    "  id: string;",
+    "  url: string;",
+    "  filename: string;",
+    "  /** Size in bytes. */",
+    "  size: number;",
+    "  /** MIME type. */",
+    "  type: string;",
+    "  thumbnails?: {",
+    "    small: { url: string; width: number; height: number };",
+    "    large: { url: string; width: number; height: number };",
+    "    full: { url: string; width: number; height: number };",
+    "  };",
+    "};",
+    "",
+];
+function airtableTsType(field, lock, depth, variant = "read") {
+    if (variant === "write" && AIRTABLE_FIELD_INPUT_TYPE_MAP[field.type]) {
+        return AIRTABLE_FIELD_INPUT_TYPE_MAP[field.type];
+    }
+    // A formula or rollup's cell type is whatever its expression produces, and
+    // Airtable reports that in the field's `result`. Reading it turns `unknown`
+    // — which forces a cast at every use — into the actual type.
+    if ((field.type === "formula" || field.type === "rollup") &&
+        (depth ?? 0) < 5) {
+        const result = field.config?.result;
+        if (result?.type && result.type !== field.type) {
+            return airtableTsType({ ...field, type: result.type, config: undefined }, lock, (depth ?? 0) + 1, variant);
+        }
+    }
     const choices = field.config?.choices;
     if ((field.type === "singleSelect" || field.type === "multipleSelects") &&
         choices &&
@@ -540,7 +815,7 @@ const READ_ONLY_AIRTABLE_FIELDS = new Set([
     "externalSyncSource",
     "aiText",
 ]);
-function airtableFieldJsdoc(field, table) {
+function airtableFieldJsdoc(field, table, lock) {
     const parts = [];
     if (table.primaryFieldId === field.id)
         parts.push("Primary field");
@@ -548,8 +823,10 @@ function airtableFieldJsdoc(field, table) {
         parts.push("Read-only; do not write");
     if (field.type === "multipleRecordLinks") {
         const linkedTableId = field.config?.linkedTableId;
-        if (linkedTableId)
-            parts.push(`Links to table ${linkedTableId}`);
+        if (linkedTableId) {
+            const linked = lock?.tables.find((t) => t.id === linkedTableId);
+            parts.push(`Links to ${linked ? linked.sdkName : linkedTableId}`);
+        }
         if (field.config?.prefersSingleRecordLink)
             parts.push("Single record only");
     }
@@ -616,32 +893,64 @@ export function generateAirtableTs(lock) {
         "//   update({ id, record }) => { id: string, fields: T } | undefined",
         "//   delete({ id }) => { id: string }",
         "//",
+        "// Reading these types:",
+        "//   Every field is OPTIONAL. Airtable omits an empty cell from the response",
+        "//   entirely rather than sending null, so any field can be undefined on any row.",
+        "//   SDK names are stable identifiers and do not change when a field is renamed —",
+        '//   each carries its current user-facing name in quotes (// "Task Name"), which is',
+        "//   the source of truth for what it means.",
+        "//   Values are RAW; format them for display using each field's comment.",
+        "//   Fields marked \"Links to X\" hold Airtable record ids (rec...) from",
+        "//   findOne/findAll — never invent one.",
+        "//   Read-only fields are absent from the *RecordInput types: Airtable rejects a",
+        "//   write to a computed one (formula, rollup, lookup, autonumber, the created/",
+        "//   modified metadata, button, aiText) with a 422.",
+        "//",
         "// Usage tips:",
         "//   - Airtable has a strict rate limit of 5 requests/second per base",
-        "//   - Use bulkCreate() instead of calling create() in a loop",
-        "//   - findAll() offsets are opaque strings from previous calls, NOT numbers",
+        "//   - Use bulkCreate() instead of calling create() in a loop, but chunk it",
+        "//     yourself: Airtable rejects more than 10 records in one create request",
+        "//     with a 422, and not every runtime path batches for you",
+        "//   - findAll() offsets are opaque cursor strings from a previous call, NOT row",
+        "//     counts (unlike zite.<table>.findAll, whose offset IS a number)",
         "//   - Always destructure record properties individually in create/update calls",
         "",
         "import { createAirtableClient } from 'zitejs/runtime';",
         "",
     ];
+    lines.push(...AIRTABLE_ATTACHMENT_TYPE);
     for (const table of lock.tables) {
         const recordType = `${table.sdkName}RecordType`;
+        lines.push(`/** A ${table.sdkName} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
             if (field.sdkName === "id")
                 continue;
-            const jsdoc = airtableFieldJsdoc(field, table);
+            const jsdoc = airtableFieldJsdoc(field, table, lock);
             if (jsdoc) {
                 lines.push(`  /** ${jsdoc} */`);
             }
             const tsType = airtableTsType(field, lock);
-            lines.push(`  ${field.sdkName}: ${tsType};`);
+            // Optional, because Airtable omits a field from the response entirely
+            // when its cell is empty — it does not send null. Declaring these
+            // required told app code every cell was populated, and `record.notes`
+            // typed `string` is `undefined` at runtime on the first blank row.
+            lines.push(`  ${field.sdkName}?: ${tsType};`);
+        }
+        lines.push("};");
+        lines.push("");
+        // Read-only fields are omitted rather than typed: Airtable rejects a write
+        // to a formula, rollup, lookup or autonumber with a 422.
+        const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_AIRTABLE_FIELDS.has(f.type));
+        lines.push(`/** What you may write when creating or updating a ${table.sdkName}. */`);
+        lines.push(`export type ${table.sdkName}RecordInput = {`);
+        for (const field of writableFields) {
+            lines.push(`  ${field.sdkName}: ${airtableTsType(field, lock, 0, "write")};`);
         }
         lines.push("};");
         lines.push("");
-        lines.push(`export const ${table.sdkName} = createAirtableClient<${recordType}>(`);
+        lines.push(`export const ${table.sdkName} = createAirtableClient<${recordType}, ${table.sdkName}RecordInput>(`);
         lines.push(`  '${lock.integrationId}',`);
         lines.push(`  '${table.sdkName}',`);
         lines.push(`  { tableId: '${table.id}' },`);
@@ -659,45 +968,71 @@ export function generateBackendWrapperTs(envVarNames = []) {
         "// Auto-generated type-narrowing wrapper. Do not edit manually.",
         "// Re-exports createEndpoint with context.user typed to the app User.",
         "",
-        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext as _ZiteScheduledContext, ZiteSchedule, ZiteWebhook } from 'zitejs/backend/base';",
+        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStreamInterface, ZiteWebhook } from 'zitejs/backend/base';",
         "import type { User } from 'zitejs/auth';",
         "",
-        "export type { ZiteSchedule, ZiteWebhook };",
+        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStreamInterface, ZiteWebhook };",
+        // The pre-monorepo SDK put this in scope for every endpoint, so migrated
+        // code can name it. `createEndpoint` infers the same thing without it.
+        "export type InferSchemaType<T> = T extends { _output: infer U } ? U : T;",
         "",
         "export class ZiteError extends Error {",
-        "  statusCode: number;",
-        "  constructor(message: string, options?: { statusCode?: number }) {",
-        "    super(message);",
+        "  code: ZiteErrorCode;",
+        "  /** Short, non-technical message suitable for showing to an end user. */",
+        "  userFacingMessage?: string;",
+        "  // Both shapes, mirroring the worker's own class: object form preferred,",
+        "  // positional form is what pre-monorepo app code was written against.",
+        "  constructor(options: { code: ZiteErrorCode; message: string; userFacingMessage?: string });",
+        "  constructor(message: string, code?: ZiteErrorCode);",
+        "  constructor(",
+        "    optionsOrMessage: { code: ZiteErrorCode; message: string; userFacingMessage?: string } | string,",
+        "    legacyCode?: ZiteErrorCode,",
+        "  ) {",
+        "    if (typeof optionsOrMessage === 'string') {",
+        "      super(optionsOrMessage);",
+        "      this.code = legacyCode ?? 'INTERNAL_ERROR';",
+        "    } else {",
+        "      super(optionsOrMessage.message);",
+        "      this.code = optionsOrMessage.code;",
+        "      this.userFacingMessage = optionsOrMessage.userFacingMessage;",
+        "    }",
         "    this.name = 'ZiteError';",
-        "    this.statusCode = options?.statusCode ?? 500;",
         "  }",
         "}",
         "",
+        // Narrows `user` to this app's generated User. ZiteScheduledContext is
+        // re-exported unchanged — a scheduled fire has no user at all, so there is
+        // nothing to narrow.
         'export interface ZiteRequestContext extends Omit<_ZiteRequestContext, "user"> {',
         "  user: User;",
         "}",
         "",
-        'export interface ZiteScheduledContext extends Omit<_ZiteScheduledContext, "user"> {',
-        "  user: User;",
-        "  scheduledAt: string;",
-        "}",
-        "",
-        "type SchemaLike<T> = { _output: T; parse: (data: unknown) => T };",
+        "type SchemaLike<TOut, TIn = TOut> = { _output: TOut; _input: TIn; parse: (data: unknown) => TOut };",
         "",
-        "export interface EndpointConfig<TInput = unknown, TOutput = unknown> {",
+        // TStream mirrors zitejs/backend/base. Without it `stream: true` endpoints
+        // get no `stream` argument here — and this wrapper, not the base module, is
+        // what `zitejs/backend` resolves to in every app.
+        "export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput> {",
         "  description?: string;",
-        "  inputSchema?: SchemaLike<TInput>;",
+        "  inputSchema?: SchemaLike<TInput, TRawInput>;",
         "  outputSchema?: SchemaLike<TOutput>;",
-        "  stream?: boolean;",
+        "  stream?: TStream;",
         "  authenticated?: boolean;",
-        "  schedule?: ZiteSchedule;",
-        "  webhook?: ZiteWebhook;",
-        "  execute: (params: { input: TInput; context: ZiteRequestContext | ZiteScheduledContext }) => Promise<TOutput> | TOutput;",
+        "  /** When set, the endpoint also fires on this cron schedule. It stays request-callable — declaring one widens `context`, so `context.user` must be null-checked. */",
+        "  schedule?: TSchedule;",
+        "  /** When set, an inbound webhook can also trigger this endpoint. Like `schedule`, it widens `context` — a webhook fire has no session. */",
+        "  webhook?: TWebhook;",
+        "  execute: (",
+        "    params: {",
+        "      input: TInput;",
+        "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
+        "    } & (TStream extends true ? { stream: ZiteStreamInterface } : {}),",
+        "  ) => Promise<TOutput> | TOutput;",
         "}",
         "",
-        "export function createEndpoint<TInput = unknown, TOutput = unknown>(",
-        "  config: EndpointConfig<TInput, TOutput>,",
-        "): EndpointConfig<TInput, TOutput> {",
+        "export function createEndpoint<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput>(",
+        "  config: EndpointConfig<TInput, TOutput, TStream, TSchedule, TWebhook, TRawInput>,",
+        "): EndpointConfig<TInput, TOutput, TStream, TSchedule, TWebhook, TRawInput> {",
         "  return config;",
         "}",
         "",