Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import type { TermId } from "@carbon/content/glossary";
import {
type EventMatch,
integrationAppLabelKey,
isMultiSelect,
type LinksDeclaration,
type OptionsSource,
type RequiredPermission
} from "../definition/catalog";
import { t, type ValueType } from "../definition/types";
import type {
ActionDeclarationLike,
IntegrationDeclarationLike
} from "./actions";
import type { OperationDeclarationLike } from "./operations";
/** The slice of `swagger-docs-schema.ts` the builder reads. */
export interface SwaggerProperty {
type?: string;
format?: string;
enum?: readonly string[];
description?: string;
items?: { type?: string; format?: string };
}
export interface SwaggerSchema {
definitions: Record<
string,
{
required?: readonly string[];
properties: Record<string, SwaggerProperty | undefined>;
}
>;
}
export interface WatchedColumnLike {
label: string;
/** Registry entity this column points at; needed only when the schema has no fk note. */
ref?: string;
}
export interface WritableColumnLike {
label: string;
/** Registry entity this column points at; needed only when the schema has no fk note. */
ref?: string;
/** Glossary term whose definition explains this field. Rendered as the ⓘ hover. */
help?: TermId;
}
export interface RegistryEntry {
table: string;
label: string;
/** Glossary term for the entity itself. Reused for every field that IS this record. */
help?: TermId;
/** Lowercase permission module; must be an existing family. */
permission: string;
/** Overrides the derived "A"/"An" where the vowel test gets it wrong. */
article?: "A" | "An";
/** Present => triggerable; absent => reference-only, no events generated. */
watch?: Record<string, WatchedColumnLike | undefined>;
/** Inert columns a workflow may set. Unrelated to `watch`; the default is excluded. */
write?: Record<string, WritableColumnLike | undefined>;
/** Plain-English explanation per column, surfaced as a tooltip in the variable picker.
* Any column in the entity may have one; not restricted to watched or writable columns. */
describe?: Record<string, string>;
/** Columns that spell this record's name, best first. Read at run time by the catalog,
* not by the generator, so adding one needs no regeneration. */
display?: readonly string[];
}
export interface MomentDeclarationLike {
label: string;
permission: string;
outputs: Record<string, ValueType>;
}
export interface BuiltEvent {
outputs: Record<string, ValueType>;
permission: string;
match: EventMatch;
}
export interface BuiltActionInput {
type: ValueType;
required: boolean;
choices?: readonly string[];
/** What the builder seeds a new node with. Nothing reads it at run time. */
defaultValue?: string | number | boolean | readonly string[];
/** Vendor prose for the ⓘ tooltip; rendered through the label catalog. */
description?: string;
template?: boolean;
/** The input is a moment, not a calendar day: the builder renders a date AND
* time picker and stores a full ISO instant. Set from a vendor's `DATE_TIME`
* property. Never set on a Carbon business date (`dueDate`, `orderDate`,
* `postingDate`), which is a day on the company's calendar and has no time. */
precision?: "datetime";
/** Prose a person reads: a record dropped in renders as a link when the caller
* supplies a resolver. Not set on webhook bodies. */
links?: LinksDeclaration;
/** Table a non-entity foreign key points at, so the update executor can scope the
* value to the company. Resolved here so a dropped fk note fails CI rather than
* silently disabling that check at run time. */
scopeTable?: string;
/** The column rejects null, so an input resolving to nothing is skipped, not written. */
notNull?: boolean;
/** The value is a set of name/value rows. */
pairs?: boolean;
/** Only shown, and only required, while `input` holds one of `equals`. */
showWhen?: { input: string; equals: readonly string[] };
/** Choices are fetched while editing, from a registered options provider. */
options?: OptionsSource;
}
export interface BuiltAction {
inputs: Record<string, BuiltActionInput>;
outputs: Record<string, ValueType>;
batchable: boolean;
permission: RequiredPermission;
requireOneOf?: string[][];
call?: string;
update?: { entity: string };
}
/**
* A step run by a third-party integration. Deliberately NOT a `BuiltAction`: the
* action path has no notion of a vendor, so the two cannot be confused at a call
* site or routed through the same dispatcher.
*/
export interface BuiltIntegration
extends Omit<BuiltAction, "call" | "update" | "requireOneOf"> {
/** Which piece, and which of its actions. The app's display name lives in the
* label map instead, so it is not repeated on every step. */
piece: { name: string; action: string };
/** Hidden inputs, rendered only under the node's Advanced section. */
advancedInputs?: Record<string, BuiltActionInput>;
/** See `CatalogIntegration.batchable`. */
batchable: false;
}
export interface BuiltOperation {
entity: string;
inputs: Record<string, BuiltActionInput>;
output: ValueType;
permission: RequiredPermission;
}
export interface BuiltCatalog {
events: Record<string, BuiltEvent>;
/** English label text per event, action and operation id; the generator wraps these in msg``. */
labels: Record<string, string>;
/** Glossary term id per input key, for the builder's ⓘ hover. Same key shape as `labels`. */
help: Record<string, string>;
entities: Record<string, Record<string, ValueType>>;
/** Allowed values per entity + property, only for enum columns. */
enums: Record<string, Record<string, readonly string[]>>;
actions: Record<string, BuiltAction>;
integrations: Record<string, BuiltIntegration>;
operations: Record<string, BuiltOperation>;
}
/** A hand-written action with neither of these has no way to run. */
const BUILT_IN_ACTIONS = new Set(["notify", "webhook"]);
/** Declared inputs → built inputs. Shared by actions and integration steps: they
* describe their inputs identically, and only differ in how the step is run. */
function buildDeclaredInputs(
id: string,
declaration: ActionDeclarationLike,
registry: Record<string, RegistryEntry>,
schema: SwaggerSchema
): Record<string, BuiltActionInput> {
const inputs: Record<string, BuiltActionInput> = {};
for (const [input, spec] of Object.entries(declaration.inputs)) {
inputs[input] = {
type: spec.type,
required: spec.required,
...(spec.choices ? { choices: spec.choices } : {}),
// `!== undefined`, never truthiness: `false` and `0` are real defaults.
...(spec.defaultValue !== undefined
? { defaultValue: spec.defaultValue }
: {}),
...(spec.description !== undefined
? { description: spec.description }
: {}),
...(spec.template ? { template: true } : {}),
...(spec.precision ? { precision: spec.precision } : {}),
...(spec.links ? { links: spec.links } : {}),
...(spec.pairs ? { pairs: true } : {}),
...(spec.showWhen ? { showWhen: spec.showWhen } : {}),
...(spec.options ? { options: spec.options } : {})
};
// An `<entity>.<verb>` id inherits its entity's enum columns; an integration
// id has no registry entry, so this simply does not fire for one.
const [entityPrefix] = id.split(".");
const table =
entityPrefix !== undefined ? registry[entityPrefix]?.table : undefined;
if (table !== undefined) {
const values = enumFor(schema, table, input);
if (values !== undefined && values.length > 0) {
inputs[input].choices = values;
}
}
}
return inputs;
}
/** The English label for a declaration and each of its inputs. Key shape is shared
* with actions so one lookup serves both kinds in the builder. */
function labelDeclaration(
id: string,
declaration: ActionDeclarationLike,
labels: Record<string, string>,
help: Record<string, string>
): void {
assertLabelIsSafe(id, declaration.label);
labels[id] = declaration.label;
for (const [input, spec] of Object.entries(declaration.inputs)) {
const key = `action.${id}.input.${input}`;
const label = spec.label.charAt(0).toUpperCase() + spec.label.slice(1);
assertLabelIsSafe(key, label);
labels[key] = label;
if (spec.help !== undefined) help[key] = spec.help;
// The tooltip rides the label catalog so it is translated like the label.
if (spec.description !== undefined) {
assertLabelIsSafe(`${key}.description`, spec.description);
labels[`${key}.description`] = spec.description;
}
}
}
/** Tenancy, extensibility and audit columns, hidden from every entity. */
const DROPPED_COLUMNS = new Set([
"companyId",
"customFields",
"embedding",
"updatedAt",
"updatedBy"
]);
/** Identity and audit columns a workflow may never set. */
const UNWRITABLE_COLUMNS = new Set([
"id",
"companyId",
"createdBy",
"createdAt",
"updatedBy",
"updatedAt"
]);
/** Only single-column foreign keys carry this note; composite keys have none. */
const FK_TARGET = /<fk table='([^']+)'/;
/** Lowercase only the first character, so "Purchase order" reads mid-sentence. */
function lowerFirst(label: string): string {
return label.charAt(0).toLowerCase() + label.slice(1);
}
/** `nonConformanceTypeId` -> `Non conformance type`. */
function humanizeColumn(column: string): string {
const withoutId = column.replace(/Id$/, "");
const spaced = withoutId.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
return spaced.charAt(0).toUpperCase() + spaced.slice(1);
}
/** One label per column, shared by `entity.<name>.<column>` and `<name>.update`'s inputs. */
function columnLabel(entry: RegistryEntry, column: string): string {
const rawLabel = entry.watch?.[column]?.label ?? entry.write?.[column]?.label;
return rawLabel === undefined
? humanizeColumn(column)
: rawLabel.charAt(0).toUpperCase() + rawLabel.slice(1);
}
/** Labels are spliced verbatim into a msg`` template literal, so these would
* break the emit or change the text: a backtick, `${`, or a backslash that is not
* itself escaped (`\\` reads back as one backslash, a lone one starts an escape). */
function assertLabelIsSafe(key: string, label: string): void {
if (
label.includes("`") ||
label.includes("${") ||
label.replaceAll("\\\\", "").includes("\\")
) {
throw new Error(
`Label for ${key} contains a backtick, a template literal or a lone backslash: "${label}"`
);
}
}
/** The vowel test is wrong for u-words ("a user"), so an entry can override it. */
function article(label: string, override: string | undefined): string {
return override ?? (/^[aeiou]/i.test(label) ? "An" : "A");
}
/** Table name -> registry key, so a foreign key can name a registry entity. */
function indexByTable(
registry: Record<string, RegistryEntry>
): Map<string, string> {
return new Map(
Object.entries(registry).map(([name, entry]) => [entry.table, name])
);
}
function primitiveFor(type: string | undefined): ValueType {
if (type === "boolean") return t.boolean;
if (type === "integer" || type === "number") return t.number;
return t.string;
}
function propertyType(
property: SwaggerProperty,
entityRef: string | undefined
): ValueType {
if (entityRef !== undefined) return t.entity(entityRef);
if (property.type === "array") {
const item = primitiveFor(property.items?.type);
return t.list(item.kind === "primitive" ? item : t.string);
}
const format = property.format ?? "";
if (format === "date" || format.startsWith("timestamp")) return t.date;
return primitiveFor(property.type);
}
/** The table a column's foreign key points at, whether or not it is a registry entity. */
function fkTableOf(property: SwaggerProperty): string | undefined {
return FK_TARGET.exec(property.description ?? "")?.[1];
}
/** The registry entity a column resolves to, if any. */
function refFor(
property: SwaggerProperty,
declaredRef: string | undefined,
byTable: Map<string, string>
): string | undefined {
if (declaredRef !== undefined) return declaredRef;
const fkTable = fkTableOf(property);
return fkTable === undefined ? undefined : byTable.get(fkTable);
}
/** A foreign key the update executor can scope to the company: one whose target is a
* real table carrying its own `companyId`, and which is not already a registry entity
* (those are scoped through the entity path). */
function scopeTableFor(
schema: SwaggerSchema,
property: SwaggerProperty,
entityRef: string | undefined
): string | undefined {
if (entityRef !== undefined) return undefined;
const target = fkTableOf(property);
if (target === undefined) return undefined;
return schema.definitions[target]?.properties?.companyId === undefined
? undefined
: target;
}
/** Collects every problem rather than throwing on the first. */
export function validateCatalogInputs(
registry: Record<string, RegistryEntry>,
moments: Record<string, MomentDeclarationLike>,
actions: Record<string, ActionDeclarationLike>,
operations: Record<string, OperationDeclarationLike>,
schema: SwaggerSchema,
integrations: Record<string, IntegrationDeclarationLike> = {}
): string[] {
const problems: string[] = [];
const byTable = indexByTable(registry);
for (const [name, entry] of Object.entries(registry)) {
const definition = schema.definitions[entry.table];
if (definition === undefined) {
problems.push(
`Entity "${name}" names table "${entry.table}", which is not in the database schema.`
);
continue;
}
for (const [column, watched] of Object.entries(entry.watch ?? {})) {
if (watched === undefined) continue;
const property = definition.properties[column];
if (property === undefined) {
problems.push(
`Entity "${name}" watches column "${column}", which does not exist on table "${entry.table}". A live customer workflow on "${name}.${column}.changed" would stop firing.`
);
continue;
}
if (DROPPED_COLUMNS.has(column)) {
problems.push(
`Entity "${name}" watches column "${column}", which is dropped from every entity's properties — the event's field would not resolve.`
);
}
if (watched.ref === undefined) continue;
if (registry[watched.ref] === undefined) {
problems.push(
`Entity "${name}" declares ref "${watched.ref}" on column "${column}", which is not a registry entity.`
);
}
const fkTable = FK_TARGET.exec(property.description ?? "")?.[1];
const fkTarget = fkTable === undefined ? undefined : byTable.get(fkTable);
if (fkTarget !== undefined && watched.ref !== fkTarget) {
problems.push(
`Entity "${name}" declares ref "${watched.ref}" on column "${column}", but its foreign key points at "${fkTable}".`
);
}
}
for (const [column, writable] of Object.entries(entry.write ?? {})) {
if (writable === undefined) continue;
const property = definition.properties[column];
if (property === undefined) {
problems.push(
`Entity "${name}" declares writable column "${column}", which does not exist on table "${entry.table}".`
);
continue;
}
if (DROPPED_COLUMNS.has(column) || UNWRITABLE_COLUMNS.has(column)) {
problems.push(
`Entity "${name}" declares writable column "${column}", which a workflow may never set.`
);
}
if (writable.ref === undefined) continue;
if (registry[writable.ref] === undefined) {
problems.push(
`Entity "${name}" declares ref "${writable.ref}" on writable column "${column}", which is not a registry entity.`
);
}
const writeFkTable = FK_TARGET.exec(property.description ?? "")?.[1];
const writeFkTarget =
writeFkTable === undefined ? undefined : byTable.get(writeFkTable);
if (writeFkTarget !== undefined && writable.ref !== writeFkTarget) {
problems.push(
`Entity "${name}" declares ref "${writable.ref}" on writable column "${column}", but its foreign key points at "${writeFkTable}".`
);
}
}
}
for (const [key, moment] of Object.entries(moments)) {
if (moment.label.trim().length === 0) {
problems.push(`Moment "${key}" has no label.`);
}
for (const [output, type] of Object.entries(moment.outputs)) {
if (type.kind === "entity" && registry[type.of] === undefined) {
problems.push(
`Moment "${key}" output "${output}" names entity "${type.of}", which is not in the registry.`
);
}
}
}
const checkEntityType = (
what: string,
where: string,
type: ValueType
): void => {
const named =
type.kind === "entity"
? type.of
: type.kind === "list" && type.of.kind === "entity"
? type.of.of
: undefined;
if (named !== undefined && registry[named] === undefined) {
problems.push(
`${what} ${where} names entity "${named}", which is not in the registry.`
);
}
};
// Actions and integration steps declare their inputs identically, so the same
// rules apply to both — only how each one is RUN differs.
const declarations: [string, string, ActionDeclarationLike][] = [
...Object.entries(actions).map(
([id, declaration]) =>
["Action", id, declaration] as [string, string, ActionDeclarationLike]
),
...Object.entries(integrations).map(
([id, declaration]) =>
["Integration step", id, declaration] as [
string,
string,
ActionDeclarationLike
]
)
];
for (const [kind, id, declaration] of declarations) {
if (declaration.label.trim().length === 0) {
problems.push(`${kind} "${id}" has no label.`);
}
if (
kind === "Action" &&
declaration.call === undefined &&
!BUILT_IN_ACTIONS.has(id)
) {
problems.push(`Action "${id}" has no implementation route.`);
}
// Advanced inputs are hidden in the form but land in the same `inputs` bag at
// run time, so they get every structural check the visible ones get. Only the
// required/`requireOneOf` rules are inapplicable — and this loop has none.
const declaredInputs: Record<
string,
ActionDeclarationLike["inputs"][string]
> = {
...declaration.inputs,
...(declaration as IntegrationDeclarationLike).advancedInputs
};
for (const [input, spec] of Object.entries(declaredInputs)) {
checkEntityType(`${kind} "${id}"`, `input "${input}"`, spec.type);
// An object is a step's OUTPUT, never something a person fills in: there is
// no field that could edit one, and no literal that could hold one. Refusing
// it here is what keeps every existing form, template and condition free of
// a record case.
if (
spec.type.kind === "record" ||
(spec.type.kind === "list" && spec.type.of.kind === "record")
) {
problems.push(
`${id}.${input} is an object, which cannot be filled in by a person.`
);
}
if (
spec.template === true &&
!(spec.type.kind === "primitive" && spec.type.of === "string")
) {
problems.push(`${id}.${input} is a template but is not a string.`);
}
if (
spec.precision !== undefined &&
!(spec.type.kind === "primitive" && spec.type.of === "date")
) {
problems.push(`${id}.${input} declares precision but is not a date.`);
}
if (spec.links !== undefined) {
if (!(spec.type.kind === "primitive" && spec.type.of === "string")) {
problems.push(`${id}.${input} declares links but is not a string.`);
}
const gate = spec.links.when;
if (gate !== undefined && declaredInputs[gate.input] === undefined) {
problems.push(
`${id}.${input} gates links on "${gate.input}", which the step does not have.`
);
}
}
// A fixed set of values on a list is what MAKES it a multi-select (`isMultiSelect`),
// so a list of anything else has no reading in the builder.
if (
spec.choices !== undefined &&
spec.type.kind === "list" &&
!(spec.type.of.kind === "primitive" && spec.type.of.of === "string")
) {
problems.push(
`${id}.${input} offers a fixed set of values but is not a list of text.`
);
}
if (spec.defaultValue !== undefined && spec.choices !== undefined) {
// One default or a set of them — a multi-select seeds several at once.
// A boolean or number default has no choices to be a member of.
const defaults =
typeof spec.defaultValue === "string"
? [spec.defaultValue]
: Array.isArray(spec.defaultValue)
? spec.defaultValue
: [];
for (const value of defaults) {
if (spec.choices.includes(value)) continue;
problems.push(
`${id}.${input} defaults to "${value}", which is not one of its values.`
);
}
}
if (Array.isArray(spec.defaultValue) && spec.type.kind !== "list") {
problems.push(
`${id}.${input} defaults to a set of values but only holds one.`
);
}
if (typeof spec.defaultValue === "string" && spec.type.kind === "list") {
problems.push(
`${id}.${input} defaults to one value but holds a set of them.`
);
}
// A fetched list and a fixed one are two answers to the same question.
if (spec.options !== undefined && spec.choices !== undefined) {
problems.push(
`${id}.${input} both fetches its values and lists them; it can only do one.`
);
}
for (const dependency of spec.options?.dependsOn ?? []) {
if (declaredInputs[dependency] !== undefined) continue;
problems.push(
`${id}.${input} fetches its values using "${dependency}", which is not an input of "${id}".`
);
}
const gate = spec.showWhen;
if (gate !== undefined) {
const target = declaredInputs[gate.input];
if (target === undefined) {
problems.push(
`${id}.${input} is shown when "${gate.input}" is set, but that is not an input of "${id}".`
);
} else if (target.choices === undefined) {
// A gate against an open set cannot be reasoned about at build time.
problems.push(
`${id}.${input} is gated on "${gate.input}", which has no fixed set of values.`
);
} else if (isMultiSelect(target)) {
// The gate reads one literal string; a set has no single value to match.
problems.push(
`${id}.${input} is gated on "${gate.input}", which holds a set of values.`
);
} else {
for (const value of gate.equals) {
if (!target.choices.includes(value)) {
problems.push(
`${id}.${input} is gated on "${gate.input}" being "${value}", which is not one of its values.`
);
}
}
}
}
}
for (const [output, type] of Object.entries(declaration.outputs)) {
checkEntityType(`${kind} "${id}"`, `output "${output}"`, type);
}
}
for (const [id, declaration] of Object.entries(operations)) {
if (declaration.label.trim().length === 0) {
problems.push(`Operation "${id}" has no label.`);
}
if (registry[declaration.entity] === undefined) {
problems.push(
`Operation "${id}" names entity "${declaration.entity}", which is not in the registry.`
);
}
for (const [input, spec] of Object.entries(declaration.inputs)) {
checkEntityType(`Operation "${id}"`, `input "${input}"`, spec.type);
}
checkEntityType(`Operation "${id}"`, "output", declaration.output);
}
return problems;
}
/** The enum a column declares, or undefined. `SwaggerProperty.enum` already exists. */
function enumFor(
schema: SwaggerSchema,
table: string,
column: string
): readonly string[] | undefined {
return schema.definitions[table]?.properties?.[column]?.enum;
}
function entityProperties(
entry: RegistryEntry,
definition: SwaggerSchema["definitions"][string],
byTable: Map<string, string>
): Record<string, ValueType> {
const properties: Record<string, ValueType> = {};
for (const [column, property] of Object.entries(definition.properties)) {
if (property === undefined || DROPPED_COLUMNS.has(column)) continue;
properties[column] = propertyType(
property,
refFor(property, entry.watch?.[column]?.ref, byTable)
);
}
return properties;
}
/** The schema is injected, not imported, to keep `@carbon/database` out of the runtime graph. */
export function buildCatalog(
registry: Record<string, RegistryEntry>,
moments: Record<string, MomentDeclarationLike>,
handWrittenActions: Record<string, ActionDeclarationLike>,
handWrittenOperations: Record<string, OperationDeclarationLike>,
schema: SwaggerSchema,
integrationSteps: Record<string, IntegrationDeclarationLike> = {}
): BuiltCatalog {
const problems = validateCatalogInputs(
registry,
moments,
handWrittenActions,
handWrittenOperations,
schema,
integrationSteps
);
if (problems.length > 0) throw new Error(problems.join("\n"));
const byTable = indexByTable(registry);
const events: Record<string, BuiltEvent> = {};
const labels: Record<string, string> = {};
const help: Record<string, string> = {};
const entities: Record<string, Record<string, ValueType>> = {};
const enums: Record<string, Record<string, readonly string[]>> = {};
const actions: Record<string, BuiltAction> = {};
const integrations: Record<string, BuiltIntegration> = {};
const operations: Record<string, BuiltOperation> = {};
for (const [name, entry] of Object.entries(registry)) {
const definition = schema.definitions[entry.table];
if (definition === undefined) continue;
entities[name] = entityProperties(entry, definition, byTable);
// Collect enum values for any column that declares them.
const entityEnumMap: Record<string, readonly string[]> = {};
for (const [column, property] of Object.entries(definition.properties)) {
if (
property?.enum &&
property.enum.length > 0 &&
!DROPPED_COLUMNS.has(column)
) {
entityEnumMap[column] = property.enum;
}
}
if (Object.keys(entityEnumMap).length > 0) enums[name] = entityEnumMap;
// entity.<name> label
labels[`entity.${name}`] = entry.label;
// entity.<name>.<column> labels for all non-dropped properties
for (const [column] of Object.entries(definition.properties)) {
if (DROPPED_COLUMNS.has(column)) continue;
const key = `entity.${name}.${column}`;
const label = columnLabel(entry, column);
assertLabelIsSafe(key, label);
labels[key] = label;
}
const writable = Object.entries(entry.write ?? {}).filter(
([, column]) => column !== undefined
);
if (writable.length > 0) {
const id = `${name}.update`;
// The input keyed by the entity name is the record; the rest are the fields.
const inputs: Record<string, BuiltActionInput> = {
[name]: { type: t.entity(name), required: true }
};
const notNullColumns = new Set(
schema.definitions[entry.table]?.required ?? []
);
for (const [column, spec] of writable) {
const property = definition.properties[column];
if (property === undefined) continue;
const entityRef = refFor(property, spec?.ref, byTable);
const scopeTable = scopeTableFor(schema, property, entityRef);
inputs[column] = {
type: propertyType(property, entityRef),
required: false,
...(scopeTable === undefined ? {} : { scopeTable }),
...(notNullColumns.has(column) ? { notNull: true } : {})
};
const enumValues = enumFor(schema, entry.table, column);
if (enumValues !== undefined && enumValues.length > 0) {
inputs[column].choices = enumValues;
}
}
actions[id] = {
inputs,
outputs: { record: t.entity(name) },
batchable: true,
permission: { module: entry.permission, action: "update" },
update: { entity: name }
};
labels[id] =
`Update ${article(lowerFirst(entry.label), entry.article).toLowerCase()} ${lowerFirst(entry.label)}`;
// Without these the builder falls back to the raw column name (`accountManagerId`).
labels[`action.${id}.input.${name}`] = entry.label;
if (entry.help !== undefined)
help[`action.${id}.input.${name}`] = entry.help;
for (const [column, spec] of writable) {
if (definition.properties[column] === undefined) continue;
const key = `action.${id}.input.${column}`;
const label = columnLabel(entry, column);
assertLabelIsSafe(key, label);
labels[key] = label;
if (spec?.help !== undefined) help[key] = spec.help;
}
}
if (entry.watch === undefined) continue;
const noun = lowerFirst(entry.label);
const determiner = article(noun, entry.article);
const record = t.entity(name);
events[`${name}.created`] = {
outputs: { record },
permission: entry.permission,
match: { table: entry.table, operation: "INSERT" }
};
labels[`${name}.created`] = `${determiner} ${noun} is created`;
events[`${name}.deleted`] = {
outputs: { record },
permission: entry.permission,
match: { table: entry.table, operation: "DELETE" }
};
labels[`${name}.deleted`] = `${determiner} ${noun} is deleted`;
for (const [column, watched] of Object.entries(entry.watch)) {
if (watched === undefined) continue;
const id = `${name}.${column}.changed`;
events[id] = {
outputs: { record, before: record, after: record },
permission: entry.permission,
match: { table: entry.table, operation: "UPDATE", field: column }
};
labels[id] = `${determiner} ${noun}'s ${watched.label} changes`;
}
}
for (const [key, moment] of Object.entries(moments)) {
events[key] = {
outputs: moment.outputs,
permission: moment.permission,
match: { moment: key }
};
labels[key] = moment.label;
}
for (const [id, declaration] of Object.entries(handWrittenActions)) {
if (actions[id] !== undefined) {
throw new Error(
`Action "${id}" is declared by hand and also generated from the entity registry.`
);
}
const inputs = buildDeclaredInputs(id, declaration, registry, schema);
actions[id] = {
inputs,
outputs: declaration.outputs,
batchable: declaration.batchable,
permission: declaration.permission,
...(declaration.requireOneOf === undefined
? {}
: { requireOneOf: declaration.requireOneOf }),
...(declaration.call === undefined ? {} : { call: declaration.call })
};
labelDeclaration(id, declaration, labels, help);
}
// Same input handling, a different map: an integration step never reaches the
// action dispatcher, and an action never carries a piece.
for (const [id, declaration] of Object.entries(integrationSteps)) {
if (actions[id] !== undefined) {
throw new Error(
`"${id}" is declared as both an action and an integration step.`
);
}
const { name, action, label: appLabel } = declaration.piece;
integrations[id] = {
inputs: buildDeclaredInputs(id, declaration, registry, schema),
...(declaration.advancedInputs === undefined
? {}
: {
advancedInputs: buildDeclaredInputs(
id,
{ ...declaration, inputs: declaration.advancedInputs },
registry,
schema
)
}),
outputs: declaration.outputs,
batchable: declaration.batchable,
permission: declaration.permission,
piece: { name, action }
};
// Advanced inputs need the same labels and tooltips: the builder lists them
// under Advanced, and without these it fell back to the raw prop names.
labelDeclaration(
id,
{
...declaration,
inputs: { ...declaration.inputs, ...declaration.advancedInputs }
},
labels,
help
);
// Written once per step of the app, to the same key — the builder needs the app's
// own name to offer it before any step has been picked.
const appKey = integrationAppLabelKey(name);
assertLabelIsSafe(appKey, appLabel);
labels[appKey] = appLabel;
}
for (const [id, declaration] of Object.entries(handWrittenOperations)) {
const inputs: Record<string, BuiltActionInput> = {};
for (const [input, spec] of Object.entries(declaration.inputs)) {
inputs[input] = { type: spec.type, required: spec.required };
}
operations[id] = {
entity: declaration.entity,
inputs,
output: declaration.output,
permission: declaration.permission
};
labels[id] = declaration.label;
for (const [input, spec] of Object.entries(declaration.inputs)) {
const key = `operation.${id}.input.${input}`;
const label = spec.label.charAt(0).toUpperCase() + spec.label.slice(1);
assertLabelIsSafe(key, label);
labels[key] = label;
if (spec.help !== undefined) {
help[key] = spec.help;
} else if (input === declaration.entity) {
// Every operation's one input is the entity record itself (see the
// `operation()` helper), so it inherits that entity's term.
const entityHelp = registry[declaration.entity]?.help;
if (entityHelp !== undefined) help[key] = entityHelp;
}
}
}
return {
events,
labels,
help,
entities,
enums,
actions,
integrations,
operations
};
}