primitive-admin 1.1.0-alpha.73 → 1.1.0-alpha.74

package/dist/src/lib/function-triggers.js

@@ -0,0 +1,223 @@
+/**
+ * `[function.triggers.*]`, read and checked locally (#3181).
+ *
+ * The SERVER is the authority: it derives the declaration from the TOML bytes
+ * inside the version envelope and validates it there, so a direct API push
+ * cannot ship a trigger the authored file does not declare (D3181-005). What
+ * this file buys is the other half of the `entry` dual-validation shape #3179
+ * established — an author who mistypes a key hears about it against their own
+ * file, by name, before a request is made.
+ *
+ * It is deliberately a VENDORED copy of the shape rules in
+ * `src/server-functions/trigger-declaration.ts` rather than an import: the CLI
+ * compiles with `rootDir: "."` and cannot reach the worker sources, which is
+ * the same constraint that made `generated-config-surfaces.ts` a vendored
+ * artifact. `cli/tests/unit/function-triggers-3181.test.ts` drives both copies
+ * from one fixture list so they cannot drift apart silently.
+ *
+ * Everything that needs the APP's state stays on the server: whether a
+ * referenced secret exists, whether the scheme-specific config is valid under
+ * this environment's JWKS policy, whether the app is at its webhook or cron
+ * cap, whether a standalone webhook holds the key. A local copy of those would
+ * be a preflight that can give a false all-clear.
+ */
+export const MAX_CRON_TRIGGERS_PER_FUNCTION = 10;
+const CRON_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+const WEBHOOK_KEYS = [
+    "verificationScheme",
+    "signingSecret",
+    "toleranceSeconds",
+    "deduplicationEnabled",
+    "deduplicationWindowMs",
+    "maxBodyBytes",
+    "secretGracePeriodMs",
+    "verification",
+];
+const CRON_KEYS = ["name", "cron", "timezone", "overlapPolicy", "rootInput"];
+const VALID_OVERLAP_POLICIES = ["skip", "allow"];
+export class TriggerDeclarationError extends Error {
+}
+/**
+ * Normalize (and check) the `triggers` table of a parsed `[function]` table.
+ * Returns null when nothing is declared, so a caller can skip the work.
+ */
+export function normalizeFunctionTriggers(functionTable, options = {}) {
+    const triggers = functionTable?.triggers;
+    if (triggers === undefined || triggers === null)
+        return null;
+    if (typeof triggers !== "object" || Array.isArray(triggers)) {
+        throw new TriggerDeclarationError("[function.triggers] must be a table declaring `webhook` and/or `cron`");
+    }
+    for (const key of Object.keys(triggers)) {
+        if (key !== "webhook" && key !== "cron") {
+            throw new TriggerDeclarationError(`unknown trigger kind '${key}' under [function.triggers]: the kinds are ` +
+                "`webhook` and `cron`");
+        }
+    }
+    const webhook = normalizeWebhook(triggers.webhook, options);
+    const cron = normalizeCron(triggers.cron, options);
+    if (!webhook && cron.length === 0)
+        return null;
+    return { webhook, cron };
+}
+function normalizeWebhook(raw, options) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (Array.isArray(raw)) {
+        throw new TriggerDeclarationError("[function.triggers.webhook] is a single table: one webhook trigger per " +
+            'function (the intent, "Webhook trigger URL and scheme?")');
+    }
+    if (typeof raw !== "object") {
+        throw new TriggerDeclarationError("[function.triggers.webhook] must be a table");
+    }
+    const table = raw;
+    for (const key of Object.keys(table)) {
+        if (!WEBHOOK_KEYS.includes(key)) {
+            throw new TriggerDeclarationError(`unknown key '${key}' under [function.triggers.webhook]: accepted keys ` +
+                `are ${WEBHOOK_KEYS.join(", ")}`);
+        }
+    }
+    if (options.durable) {
+        throw new TriggerDeclarationError("webhook triggers require sync mode: remove `durable = true` or remove " +
+            "[function.triggers.webhook]");
+    }
+    const scheme = String(table.verificationScheme ?? "").trim();
+    if (!scheme) {
+        throw new TriggerDeclarationError("[function.triggers.webhook] verificationScheme is required");
+    }
+    if (scheme === "none") {
+        throw new TriggerDeclarationError("verification scheme 'none' is not allowed for function triggers: an " +
+            "unauthenticated caller could run the function");
+    }
+    const declaration = { verificationScheme: scheme };
+    if (table.signingSecret !== undefined) {
+        declaration.signingSecret = String(table.signingSecret);
+    }
+    for (const key of [
+        "toleranceSeconds",
+        "deduplicationWindowMs",
+        "maxBodyBytes",
+        "secretGracePeriodMs",
+    ]) {
+        if (table[key] === undefined)
+            continue;
+        const value = Number(table[key]);
+        if (!Number.isFinite(value)) {
+            throw new TriggerDeclarationError(`[function.triggers.webhook] ${key} must be a number`);
+        }
+        declaration[key] = value;
+    }
+    if (table.deduplicationEnabled !== undefined) {
+        if (typeof table.deduplicationEnabled !== "boolean") {
+            throw new TriggerDeclarationError("[function.triggers.webhook] deduplicationEnabled must be a boolean");
+        }
+        declaration.deduplicationEnabled = table.deduplicationEnabled;
+    }
+    if (table.verification !== undefined) {
+        const verification = table.verification;
+        if (verification === null ||
+            typeof verification !== "object" ||
+            Array.isArray(verification)) {
+            throw new TriggerDeclarationError("[function.triggers.webhook.verification] must be a table");
+        }
+        declaration.verification = jsonSafe(verification);
+    }
+    return declaration;
+}
+function normalizeCron(raw, options) {
+    if (raw === undefined || raw === null)
+        return [];
+    const entries = Array.isArray(raw) ? raw : [raw];
+    if (entries.length === 0)
+        return [];
+    if (options.durable) {
+        throw new TriggerDeclarationError("cron triggers require sync mode in this release: remove `durable = " +
+            "true` or remove the [[function.triggers.cron]] entries");
+    }
+    if (entries.length > MAX_CRON_TRIGGERS_PER_FUNCTION) {
+        throw new TriggerDeclarationError(`a function may declare at most ${MAX_CRON_TRIGGERS_PER_FUNCTION} cron ` +
+            `trigger entries, and this one declares ${entries.length}`);
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new TriggerDeclarationError("each [[function.triggers.cron]] entry must be a table");
+        }
+        const table = entry;
+        for (const key of Object.keys(table)) {
+            if (!CRON_KEYS.includes(key)) {
+                throw new TriggerDeclarationError(`unknown key '${key}' in a [[function.triggers.cron]] entry: accepted ` +
+                    `keys are ${CRON_KEYS.join(", ")}`);
+            }
+        }
+        const name = String(table.name ?? "").trim();
+        if (!name) {
+            throw new TriggerDeclarationError("each [[function.triggers.cron]] entry needs a `name`: it is required " +
+                "because it is half of the trigger's key, `<functionKey>:<name>`");
+        }
+        if (!CRON_NAME_PATTERN.test(name)) {
+            throw new TriggerDeclarationError(`cron trigger name '${name}' must start with a letter or digit and ` +
+                "contain only letters, digits, '-' or '_'");
+        }
+        if (seen.has(name)) {
+            throw new TriggerDeclarationError(`duplicate cron trigger name '${name}': names are the trigger's key ` +
+                "within the function, so each must appear once");
+        }
+        seen.add(name);
+        const cron = String(table.cron ?? "").trim();
+        if (!cron) {
+            throw new TriggerDeclarationError(`cron trigger '${name}' needs a \`cron\` expression`);
+        }
+        // Shape only. The full grammar is the server's `parseCron` — the CLI
+        // refuses the mistake that is obvious from the text and leaves the
+        // authority where the DO's own parser is.
+        if (cron.trim().split(/\s+/).length !== 5) {
+            throw new TriggerDeclarationError(`cron trigger '${name}': a cron expression has exactly 5 fields, and ` +
+                `'${cron}' has ${cron.trim().split(/\s+/).length}`);
+        }
+        const declaration = { name, cron };
+        if (table.timezone !== undefined) {
+            declaration.timezone = String(table.timezone);
+        }
+        if (table.overlapPolicy !== undefined) {
+            const policy = String(table.overlapPolicy);
+            if (!VALID_OVERLAP_POLICIES.includes(policy)) {
+                throw new TriggerDeclarationError(`cron trigger '${name}': overlapPolicy must be one of ` +
+                    VALID_OVERLAP_POLICIES.join(", "));
+            }
+            declaration.overlapPolicy = policy;
+        }
+        if (table.rootInput !== undefined) {
+            declaration.rootInput = jsonSafe(table.rootInput);
+        }
+        normalized.push(declaration);
+    }
+    // Sorted by name, matching the server, so `config diff` compares the same
+    // canonical shape whichever order the file lists its entries in.
+    normalized.sort((a, b) => a.name.localeCompare(b.name));
+    return normalized;
+}
+function jsonSafe(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "bigint")
+        return Number(value);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(jsonSafe);
+    if (typeof value === "object") {
+        const anyValue = value;
+        if (typeof anyValue.toISOString === "function") {
+            return String(anyValue.toISOString());
+        }
+        const out = {};
+        for (const [key, child] of Object.entries(anyValue)) {
+            out[key] = jsonSafe(child);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=function-triggers.js.map

package/dist/src/lib/function-triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-triggers.js","sourceRoot":"","sources":["../../../src/lib/function-triggers.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/generated-config-surfaces.d.ts

@@ -645,6 +645,7 @@ export declare const METADATA_CATEGORY_CONFIG_SURFACE: ConfigObjectSurface;
  * exists to end.
  */
 export declare const TRANSFORM_SURFACE: ConfigObjectSurface;
+export declare const SERVER_FUNCTION_SURFACE: ConfigObjectSurface;
 export declare const TEST_CASE_SURFACE: ConfigObjectSurface;
 export declare const APP_SETTINGS_SURFACE: ConfigObjectSurface;
 /**

package/dist/src/lib/generated-config-surfaces.js

@@ -774,6 +774,24 @@ export const RETIRED_CONFIG_KEYS = {
                 "`primitive webhooks archive` to retire the webhook (#2907).",
         },
     },
+    // #3179 — server functions are the SIXTH status-carrying type, and they take
+    // the rule at birth rather than inheriting it: a function's whole point is
+    // that it runs code on request, so a `config push` that re-enabled a function
+    // an operator had disabled would put that code back on a public endpoint as a
+    // side effect of a code change.
+    function: {
+        status: {
+            toml: "`status` is no longer authored in TOML (#2803). Availability is " +
+                "server-owned: use `primitive functions enable|disable`. Retiring the " +
+                "function is `primitive functions archive` (#2907) — the archived row " +
+                "keeps its key in the app's single key namespace. Delete the line and " +
+                "push again; pushing new code to a disabled function is allowed and " +
+                "leaves it out of service.",
+            request: "`status` is server-owned (#2803). Use " +
+                "`primitive functions enable|disable` to change availability, or " +
+                "`primitive functions archive` to retire the function (#2907).",
+        },
+    },
     // #2803 — availability is one server-owned `status`. As a TOML key it made
     // `config push` a second writer: pushing a file pulled before an operator ran
     // `workflows disable` put the workflow back in service as a side effect.
@@ -1301,13 +1319,23 @@ export const PROMPT_SURFACE = {
                 // server still runs. Update-only: create hard-codes "active" and
                 // ignores a supplied status, same statement `writableOn` makes for
                 // every create-assigned field.
+                //
+                // #3201 — emitted only when it is NOT the create default, so a pulled
+                // file says `status = "archived"` about a retired config and says
+                // nothing about the rest. `active` was information-free and actively
+                // misleading: a prompt's OBJECT-level availability is the server-owned
+                // `status` that left TOML at #2803, and a `status = "active"` line in
+                // the file reads exactly like it. `serverDefault` is what makes the
+                // omission lossless — push sends it for an absent key and `config
+                // diff` reads both spellings as one value.
                 {
                     field: "status",
                     tomlKey: "status",
                     type: "string",
-                    emit: "always",
+                    emit: "whenSet",
                     writableOn: UPDATE_ONLY,
                     validation: handledBy(PROMPT_HANDLER, "AdminAPI"),
+                    serverDefault: "active",
                 },
                 {
                     field: "description",
@@ -1774,6 +1802,25 @@ export const WEBHOOK_SURFACE = {
                     kind: "server-owned",
                     note: "ULID assigned on create; never author-authored.",
                 },
+                // #3181 — the two fields a FUNCTION-owned row carries. Neither is ever
+                // authored on a `[webhook]` table: a function declares its trigger in
+                // its own `functions/<key>.toml`, and this file's whole surface is the
+                // standalone object. A hidden row is written only by
+                // `function-trigger-reconcile.ts`.
+                functionId: {
+                    kind: "server-owned",
+                    note: "The server function whose config owns this row (#3181). Set only " +
+                        "by the trigger reconcile; a standalone webhook never has one, and " +
+                        "its presence is what every hiding filter branches on.",
+                },
+                declaredSigningSecret: {
+                    kind: "secret",
+                    note: "The authored `{{secrets.KEY}}` reference the last function-trigger " +
+                        "reconcile applied (#3181, D3181-004). Server-owned bookkeeping " +
+                        "that makes an operational `rotate-secret` survive later pushes: " +
+                        "the secret fields move only when THIS marker and the authored " +
+                        "value disagree. Never authored, and never on a standalone row.",
+                },
                 // #2803 — availability is server-owned. As a `[webhook]` key it made
                 // `config push` a second writer: a file pulled before an operator
                 // paused the webhook put the endpoint back in service on the next
@@ -1999,6 +2046,15 @@ export const CRON_TRIGGER_SURFACE = {
                 },
             ],
             notExposed: {
+                // #3181 — a function-declared cron entry creates a hidden row keyed
+                // `<functionKey>:<name>`, and this is the discriminator every standalone
+                // surface hides on. Never authored on a `[cronTrigger]` table: the
+                // declaration lives in the function's own file.
+                functionId: {
+                    kind: "server-owned",
+                    note: "The server function whose config owns this row (#3181). Written " +
+                        "only by the trigger reconcile; a standalone trigger never has one.",
+                },
                 // #2803 — the ONE availability control, server-owned. Written only by
                 // `cron-triggers enable|disable`, the delete flow (the `archived`
                 // tombstone) and the alarm's error-pause path. `server-owned` keeps it
@@ -3093,6 +3149,194 @@ export const TRANSFORM_SURFACE = {
             "(`transforms/<name>.tests/`) are the separate `test-case` surface.",
     },
 };
+// ── src/config-surface/server-function.ts ────────────────────────────────
+/**
+ * The `function` configuration object's definition (#3179, project
+ * `server-functions`).
+ *
+ * `functions/<key>.toml` carries a single `[function]` table, and the TypeScript
+ * the function runs lives beside it in the same tree — the file names its
+ * `entry` and `config push` builds the bundle from there.
+ *
+ * ── One table, two models ────────────────────────────────────────────────
+ *
+ * The authored surface spans the header (`ServerFunction`) and the immutable
+ * config version (`ServerFunctionConfig`), but it is ONE table in the file: an
+ * author does not write a version, they write a function and push it. The
+ * definition therefore declares the header's field surface and lists the
+ * version-carried keys (`entry`, `durable`, `limits`) in `tomlOnlyKeys` beside
+ * `key` — they are authored, they are not fields of the header model, and they
+ * travel on the config-version route rather than in the header body. Declaring
+ * a second table over `ServerFunctionConfig` at the same `tomlPath` is not
+ * possible (a table is addressed by its path) and would in any case claim the
+ * version is a table an author writes, which is exactly what F-002 removed.
+ *
+ * ── The phase-1 key set is narrower than the models ──────────────────────
+ *
+ * `capabilities` (#3182/#3183) is declared on the models now so that child
+ * touches only the surface, and is deliberately NOT accepted here: a file
+ * carrying it today is rejected as an unknown key rather than accepted and
+ * dropped, which is the silent-200 failure the whole registry exists to end.
+ *
+ * The trigger blocks joined the accepted set with #3181. They are `structural`
+ * for the same reason `entry` is: they are authored, they are not fields of
+ * the header model, and they travel inside the version envelope's TOML bytes
+ * rather than as a payload field of their own.
+ *
+ * ── `status` ─────────────────────────────────────────────────────────────
+ *
+ * A server function is the SIXTH status-carrying type. `status` is server-owned
+ * (#2803): only creation initializes it, the verbs are the only writers, and a
+ * push to a disabled function takes the code without putting it back in
+ * service. Its retired-key guidance lives in `retired-keys.ts` under this
+ * table's prefix.
+ */
+const FUNCTION_HANDLER = "src/admin-api/controllers/server-functions-controller.ts";
+export const SERVER_FUNCTION_SURFACE = {
+    label: "function",
+    tables: [
+        {
+            tomlPath: ["function"],
+            repeated: false,
+            model: "ServerFunction",
+            fields: [
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "runAs",
+                    tomlKey: "runAs",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // `caller | system` — the identity the function's own API calls run
+                    // as (the intent, "Who may invoke a function, and as whom?").
+                    validation: handledBy(FUNCTION_HANDLER, "ServerFunctionsController"),
+                },
+                {
+                    field: "access",
+                    tomlKey: "access",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    // A CEL expression, and REQUIRED before code can be pushed: a
+                    // function with no gate fails closed at invoke, so accepting a bundle
+                    // for one would report a successful push of something that can never
+                    // run.
+                    validation: handledBy(FUNCTION_HANDLER, "ServerFunctionsController"),
+                },
+                {
+                    field: "inputSchema",
+                    tomlKey: "inputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(FUNCTION_HANDLER, "ServerFunctionsController"),
+                },
+                {
+                    field: "outputSchema",
+                    tomlKey: "outputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(FUNCTION_HANDLER, "ServerFunctionsController"),
+                },
+            ],
+            notExposed: {
+                functionId: {
+                    kind: "server-owned",
+                    note: "ULID assigned on create; never author-authored.",
+                },
+                appId: {
+                    kind: "server-owned",
+                    note: "Tenant scope, taken from the route; never on the wire.",
+                },
+                functionKey: {
+                    kind: "structural",
+                    // Create carries it in the body; update does not — the key is the
+                    // function's identity in the single per-app key namespace, and the
+                    // URL already names the row.
+                    requestModes: ["create"],
+                    note: "The function's identity, and its claim on the app's single key " +
+                        "namespace (workflows, functions, scripts and webhooks share it). " +
+                        "Comes from the TOML file name and is attached by the caller; its " +
+                        "TOML spelling is declared in tomlOnlyKeys as `key`.",
+                },
+                status: {
+                    kind: "server-owned",
+                    note: "#2803 — availability is server-owned on all six carrying types. " +
+                        "Only creation initializes `active`; `primitive functions " +
+                        "enable|disable` and `archive` are the only writers, so a push to " +
+                        "a disabled function takes the code and stays out of service.",
+                },
+                activeConfigId: {
+                    kind: "server-owned",
+                    note: "Points at the immutable ServerFunctionConfig the function runs. " +
+                        "Repointed by a config-version push; versions are nameless, so " +
+                        "there is no `activeConfigName` for an author to write.",
+                },
+                createdBy: {
+                    kind: "server-owned",
+                    note: "Admin who created the function; assigned server-side.",
+                },
+                createdAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+                modifiedAt: {
+                    kind: "server-owned",
+                    note: "Timestamp, assigned server-side.",
+                },
+            },
+            tomlOnlyKeys: {
+                key: {
+                    kind: "structural",
+                    note: "The function key. `config pull` writes it for readability; push " +
+                        "takes the identity from the file name and attaches `functionKey` " +
+                        "itself.",
+                },
+                entry: {
+                    kind: "structural",
+                    note: "The TypeScript entry point, relative to the config tree root. A " +
+                        "field of the immutable ServerFunctionConfig, not of the header: " +
+                        "it travels on the config-version push together with the built " +
+                        "bundle and the authored sources.",
+                },
+                durable: {
+                    kind: "structural",
+                    note: "Whether this version runs durably (#3186). Stored on the config " +
+                        "version and pushed with it, so it is versioned with the code it " +
+                        "describes rather than mutable on the header.",
+                },
+                limits: {
+                    kind: "structural",
+                    note: "`[function.limits]` — per-version ceilings, stored as JSON on the " +
+                        "config version. Free-form inside the table (the server validates " +
+                        "the members it knows), and pushed with the version.",
+                },
+                triggers: {
+                    kind: "structural",
+                    note: "`[function.triggers.webhook]` and `[[function.triggers.cron]]` " +
+                        "(#3181) — what fires this function besides an HTTP call. " +
+                        "Validated by dedicated code on both sides, and carried by NO " +
+                        "payload field: the server derives the declaration from the " +
+                        "authored TOML bytes inside the version envelope, so trigger " +
+                        "behavior is covered by `envelopeHash` and cannot disagree with " +
+                        "the file even for a direct API caller (D3181-005).",
+                },
+            },
+            responseOnlyKeys: {},
+        },
+    ],
+    // The file is the `[function]` table and nothing else. The function's code is
+    // in the source files `entry` reaches, not in a TOML table.
+    tomlDocumentKeys: {},
+};
 // ── src/config-surface/test-case.ts ──────────────────────────────────────
 /**
  * The `test-case` configuration object's definition (issue #2644, phase 3).
@@ -3419,6 +3663,20 @@ export const APP_SETTINGS_SURFACE = {
                     // `validateTestAccountBaseEmails`.
                     validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
                 },
+                {
+                    field: "largeDocumentWindowDays",
+                    tomlKey: "largeDocumentWindowDays",
+                    type: "number",
+                    // Whenever the app set one. An app on the deployment's window must
+                    // not grow a key that pins it to whatever that window is today
+                    // (#2816).
+                    emit: "whenSet",
+                    writableOn: UPDATE_ONLY,
+                    // Refused rather than clamped: answering 200 to a 30-day window the
+                    // server does not keep would have the caller plan a month of
+                    // offline work around it (`parseLargeDocumentWindowSetting`).
+                    validation: handledBy(SETTINGS_HANDLER, "SettingsController"),
+                },
             ],
             notExposed: {
                 appId: {
@@ -3756,6 +4014,7 @@ export const CONFIG_SURFACES = [
     COLLECTION_TYPE_CONFIG_SURFACE,
     METADATA_CATEGORY_CONFIG_SURFACE,
     TRANSFORM_SURFACE,
+    SERVER_FUNCTION_SURFACE,
     TEST_CASE_SURFACE,
     APP_SETTINGS_SURFACE,
 ];
@@ -3825,6 +4084,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "directLlmEnabled",
         "memberInvitationsEnabled",
         "memberInvitationLimit",
+        "largeDocumentWindowDays",
         "createdAt",
         "modifiedAt",
     ],
@@ -3900,6 +4160,8 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "signingSecret",
         "previousSigningSecret",
         "secretRotatedAt",
+        "functionId",
+        "declaredSigningSecret",
         "secretGracePeriodMs",
         "toleranceSeconds",
         "deduplicationEnabled",
@@ -3969,6 +4231,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "cron",
         "timezone",
         "workflowKey",
+        "functionId",
         "overlapPolicy",
         "rootInput",
         "inputMapping",
@@ -4039,6 +4302,21 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "modifiedAt",
         "createdBy",
     ],
+    "ServerFunction": [
+        "functionId",
+        "appId",
+        "functionKey",
+        "description",
+        "status",
+        "activeConfigId",
+        "runAs",
+        "access",
+        "inputSchema",
+        "outputSchema",
+        "createdBy",
+        "createdAt",
+        "modifiedAt",
+    ],
     "WorkflowDefinition": [
         "workflowId",
         "appId",