@dforge-core/metadata 0.0.1 → 0.0.3

package/schemas/traits.schema.json

@@ -0,0 +1,99 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/traits.schema.json",
+	"title": "dForge Trait Definitions",
+	"description": "Defines entity traits that expand into fields, references, and constraints during module install. Shipped as traits.json at module root.",
+	"type": "object",
+	"additionalProperties": {
+		"$ref": "#/$defs/traitDefinition"
+	},
+	"$defs": {
+		"traitDefinition": {
+			"type": "object",
+			"description": "A single trait definition",
+			"properties": {
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of the trait"
+				},
+				"includes": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Other trait names to include (inherit fields from). Expanded recursively with circular reference protection."
+				},
+				"fields": {
+					"type": "object",
+					"description": "Field definitions to add to entities using this trait. Keys support {entity}/{Entity} placeholders for parametric names.",
+					"additionalProperties": {
+						"$ref": "#/$defs/traitField"
+					}
+				},
+				"references": {
+					"type": "object",
+					"description": "FK reference definitions to add. Keys support {Entity} placeholder.",
+					"additionalProperties": {
+						"$ref": "#/$defs/traitReference"
+					}
+				},
+				"constraints": {
+					"type": "object",
+					"description": "Constraint definitions to add. Keys support {Entity} placeholder (e.g. 'UQ_{Entity}_period_key')."
+				}
+			},
+			"additionalProperties": false
+		},
+		"traitField": {
+			"type": "object",
+			"description": "Field definition within a trait. Same shape as entity field definitions.",
+			"properties": {
+				"dbDatatype": { "type": "string" },
+				"columnType": { "type": "string" },
+				"fieldTypeCd": { "type": "string" },
+				"flags": { "type": "string" },
+				"isPk": { "type": "boolean" },
+				"isIdentity": { "type": "boolean" },
+				"isNullable": { "type": "boolean" },
+				"formula": { "type": "string" },
+				"orderNum": { "type": "integer" },
+				"description": { "type": "string", "description": "Supports {entity}/{Entity} placeholders" },
+				"maxLen": { "type": "integer" },
+				"link": {
+					"type": "object",
+					"properties": {
+						"entity": { "type": "string" },
+						"thisKey": { "type": "string" },
+						"otherKey": { "type": "string" }
+					},
+					"required": ["entity", "thisKey", "otherKey"],
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
+		"traitReference": {
+			"type": "object",
+			"description": "FK reference definition within a trait",
+			"required": ["from", "to"],
+			"properties": {
+				"from": {
+					"type": "object",
+					"required": ["field"],
+					"properties": {
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
+				"to": {
+					"type": "object",
+					"required": ["entity", "field"],
+					"properties": {
+						"entity": { "type": "string" },
+						"field": { "type": "string" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/triggers.schema.json

@@ -0,0 +1,59 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/triggers.schema.json",
+	"title": "dForge Module Triggers",
+	"description": "Trigger definitions for a dForge module (logic/triggers.json). A trigger watches an entity for an event (insert/update/delete/status_change/any), evaluates an optional formula condition using `[field]` syntax, and fires an action if true. Different from scheduled jobs (cron-driven) and webhooks (outbound HTTP) — triggers are intra-tenant DB-event-driven action invocations.",
+	"type": "object",
+	"required": ["triggers"],
+	"properties": {
+		"triggers": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/trigger" }
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"trigger": {
+			"type": "object",
+			"required": ["code", "entity", "event", "action"],
+			"properties": {
+				"code": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9_]*$",
+					"description": "Trigger code, unique within the module."
+				},
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of what the trigger does and when."
+				},
+				"entity": {
+					"type": "string",
+					"description": "Entity whose events this trigger watches. May be cross-module via dot notation (e.g. 'fin.invoice')."
+				},
+				"event": {
+					"type": "string",
+					"enum": ["insert", "update", "delete", "status_change", "any"],
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+				},
+				"condition": {
+					"type": "string",
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+				},
+				"action": {
+					"type": "string",
+					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+				},
+				"params": {
+					"type": "object",
+					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+				},
+				"async": {
+					"type": "boolean",
+					"default": false,
+					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls). When false, the action runs in the same transaction; failures roll back the original DB change."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

package/schemas/webhooks.schema.json

@@ -0,0 +1,73 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Webhooks",
+	"description": "Webhook subscription definitions for a dForge module package (webhooks.json)",
+	"type": "object",
+	"required": ["subscriptions"],
+	"properties": {
+		"subscriptions": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["code", "description", "entity", "event"],
+				"properties": {
+					"code": {
+						"type": "string",
+						"maxLength": 100,
+						"pattern": "^[a-z][a-z0-9_]*$",
+						"description": "Unique identifier within the module"
+					},
+					"description": {
+						"type": "string",
+						"description": "Human-readable description"
+					},
+					"entity": {
+						"type": "string",
+						"description": "Entity code that triggers this webhook"
+					},
+					"event": {
+						"type": "string",
+						"enum": ["insert", "update", "delete", "status_change", "any"],
+						"description": "Event type that fires this webhook"
+					},
+					"condition": {
+						"type": "string",
+						"description": "Formula evaluated against the record. Webhook fires only if true."
+					},
+					"endpointUrl": {
+						"type": "string",
+						"format": "uri",
+						"description": "Default endpoint URL. Integration modules ship with this pre-configured; admin can override."
+					},
+					"secretCd": {
+						"type": "string",
+						"description": "Secret code for API key (from dforge.secret table, admin-configured)"
+					},
+					"payload": {
+						"type": "object",
+						"properties": {
+							"include": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Field codes to include. If omitted, include all visible fields."
+							},
+							"includeOld": {
+								"type": "boolean",
+								"default": false,
+								"description": "Include previous field values on update/status_change events"
+							}
+						},
+						"additionalProperties": false
+					},
+					"enabled": {
+						"type": "boolean",
+						"default": true,
+						"description": "Can be set to false to disable without removing"
+					}
+				},
+				"additionalProperties": false
+			}
+		}
+	},
+	"additionalProperties": false
+}

package/src/entity-meta.ts

@@ -0,0 +1,48 @@
+// Entity introspection helpers — derive the projections clients commonly need
+// (primary keys, identity-trait keys, reference links) from a raw EntityDef.
+// Shared so the editor, web app and CLI compute these the same way instead of
+// each reimplementing the rules.
+
+import type { EntityDef } from "./entity";
+import { expandTrait } from "./traits";
+
+/** `{ field, target }` for each Reference (R) column that declares a link. */
+export function getLinks(entity: EntityDef): Array<{ field: string; target: string }> {
+	const links: Array<{ field: string; target: string }> = [];
+	for (const [code, field] of Object.entries(entity.fields ?? {})) {
+		if (field.columnType === "R" && field.link?.entity) {
+			links.push({ field: code, target: field.link.entity });
+		}
+	}
+	return links;
+}
+
+/**
+ * Identity-trait primary-key column codes for `entityCode` (e.g. `invoice_id`),
+ * excluding any the author already declared explicitly. Empty unless the entity
+ * carries the `identity` trait.
+ */
+export function getIdentityKeys(entity: EntityDef, entityCode: string): string[] {
+	if (!entity.traits?.includes("identity")) return [];
+	const explicit = new Set(Object.keys(entity.fields ?? {}));
+	return Object.keys(expandTrait("identity", entityCode)).filter((key) => !explicit.has(key));
+}
+
+/**
+ * All primary-key column codes: fields flagged `isPk`, plus identity-trait keys.
+ * Order is explicit-first, then identity keys; duplicates removed.
+ */
+export function getPrimaryKeys(entity: EntityDef, entityCode: string): string[] {
+	const explicit = Object.entries(entity.fields ?? {})
+		.filter(([, field]) => field.isPk)
+		.map(([code]) => code);
+	const seen = new Set(explicit);
+	const result = [...explicit];
+	for (const key of getIdentityKeys(entity, entityCode)) {
+		if (!seen.has(key)) {
+			seen.add(key);
+			result.push(key);
+		}
+	}
+	return result;
+}

package/src/field-types.ts

@@ -34,6 +34,7 @@ export const fieldTypes = [
 	{ cd: "lookup", name: "Lookup", columnType: "R", baseDatatypeCd: "guid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
 	{ cd: "user", name: "User Picker", columnType: "D", baseDatatypeCd: "cuid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "grid", name: "Detail Grid", columnType: "S", baseDatatypeCd: "set", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
+	{ cd: "list", name: "Detail List", columnType: "S", baseDatatypeCd: "set", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "tags", name: "Tags", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
 	{ cd: "entitylink", name: "Entity Link", columnType: "D", baseDatatypeCd: "json", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "code", name: "Code Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },

package/src/index.ts

@@ -57,6 +57,9 @@ export type {
 	TraitCd,
 } from "./entity";
 
+// Entity introspection helpers (primary keys, identity keys, reference links).
+export { getLinks, getIdentityKeys, getPrimaryKeys } from "./entity-meta";
+
 export {
 	dataViewKinds,
 	type DataViewsFile,

package/src/types.ts

@@ -63,6 +63,7 @@ export type FieldTypeCd =
 	| "lookup"
 	| "user"
 	| "grid"
+	| "list"
 	| "tags"
 	| "entitylink"
 	| "code";