@dforge-core/metadata 0.0.1

package/src/types.ts

@@ -0,0 +1,177 @@
+// Shared types for the dForge authoring registries.
+//
+// These describe the *authoring* surface (what a module author / visual editor
+// works with), mirrored from the platform metadata seed data. Keep them free of
+// any runtime dependency so this package stays import-safe everywhere.
+
+/** A `{ cd, name }` pair for friendly pickers (view kinds, viz types, …). */
+export interface NamedKind {
+	cd: string;
+	name: string;
+}
+
+/** Horizontal alignment for a column's display (authored via `params.align`). */
+export type AlignType = "left" | "right" | "center";
+
+/** Column kind letter as stored in entity JSON / the `column` metadata table. */
+export type ColumnTypeCd = "D" | "R" | "S" | "F" | "A" | "L" | "G";
+
+/** Abstract data type code from the `base_datatype` table. */
+export type BaseDatatypeCd =
+	| "binary"
+	| "bool"
+	| "culture"
+	| "cuid"
+	| "date"
+	| "guid"
+	| "json"
+	| "link"
+	| "number"
+	| "project"
+	| "ref"
+	| "set"
+	| "string"
+	| "time"
+	| "timestamp"
+	| "xml";
+
+/** Display flags string characters. V=Visible I=Identity E=Editable M=Mandatory H=Hidden. */
+export type FlagCd = "V" | "I" | "E" | "M" | "H";
+
+/** Known field type codes from the field_type seed. */
+export type FieldTypeCd =
+	| "text"
+	| "email"
+	| "phone"
+	| "url"
+	| "textarea"
+	| "number"
+	| "currency"
+	| "percent"
+	| "checkbox"
+	| "date"
+	| "datetime"
+	| "time"
+	| "dropdown"
+	| "flags"
+	| "json"
+	| "hidden"
+	| "color"
+	| "image"
+	| "file"
+	| "richtext"
+	| "lookup"
+	| "user"
+	| "grid"
+	| "tags"
+	| "entitylink"
+	| "code";
+
+/**
+ * A UI field type from the `field_type` table. The author picks one of these;
+ * the physical `dbDatatype` and `baseDatatypeCd` are derived from it.
+ */
+export interface FieldTypeDef {
+	/** Stable code stored as `fieldTypeCd` on a field. */
+	cd: FieldTypeCd;
+	/** Human label for pickers. */
+	name: string;
+	/** Default column kind this field type implies (D / R / S). */
+	columnType: ColumnTypeCd;
+	/** Abstract datatype used for platform semantics. */
+	baseDatatypeCd: BaseDatatypeCd;
+	/** Aggregations this type supports: S=sum C=count A=avg M=min/max (letters). */
+	supportedAgg: string | null;
+	/** Default maximum length for string-backed types (e.g. color = 20). */
+	maxLen: number | null;
+	/** Default numeric scale for number-backed types (e.g. currency = 2). */
+	precision: number | null;
+	/** Whether the value participates in text filters. */
+	useStringInFilter: boolean;
+	/** Default field-type params merged into `params` when the field is created. */
+	defParams?: Record<string, unknown>;
+}
+
+/** Relationship link for Reference (R) and Set (S) columns. */
+export interface FieldLink {
+	/** Target entity code (the entity being referenced or collected). */
+	entity: string;
+	/** Column(s) in this entity (comma-separated for compound keys). */
+	thisKey: string;
+	/** Column(s) in the target entity (comma-separated for compound keys). */
+	otherKey: string;
+}
+
+/** A dropdown/flags option in `params.options` (rich form). */
+export interface FieldOption {
+	value: string;
+	label: string;
+	icon?: string;
+	color?: string;
+}
+
+/**
+ * A field/column definition as it appears under an entity's `fields` map.
+ * Mirrors the `field` $def in entity.schema.json. Trait fields are a subset of
+ * this shape, so the same type covers both. The open index signature keeps it
+ * tolerant of forward-compatible / type-specific extras (e.g. A/L register
+ * config under `params`).
+ */
+export interface FieldDef {
+	/** PostgreSQL data type (e.g. uuid, varchar, int4, numeric, timestamptz). */
+	dbDatatype?: string;
+	/** Abstract base datatype; required on Formula (F) columns. */
+	baseDatatypeCd?: BaseDatatypeCd;
+	/** UI field type code. */
+	fieldTypeCd?: FieldTypeCd;
+	/** Column kind (defaults to D when omitted). */
+	columnType?: ColumnTypeCd;
+	/** Display flags string (subset of V/I/E/M/H). */
+	flags?: string;
+	isPk?: boolean;
+	isNullable?: boolean;
+	isIdentity?: boolean;
+	/** Formula expression (F/G columns) or SQL default value. */
+	formula?: string;
+	orderNum?: number;
+	description?: string;
+	maxLen?: number;
+	precision?: number;
+	/** Input mask pattern for editing. */
+	editMask?: string;
+	/** Display format pattern. */
+	displayFmt?: string;
+	/** Relationship link for R and S columns. */
+	link?: FieldLink;
+	/**
+	 * On a self-referencing R column, set true to ALLOW parent/child cycles.
+	 * Absent ⇒ treated as an acyclic hierarchy guarded at the DB level.
+	 */
+	cyclic?: boolean;
+	/** Filter criteria for reference lookups. */
+	refFilter?: unknown;
+	/** Field-type-specific configuration (dropdown options, register config, …). */
+	params?: { options?: (string | FieldOption)[] } & Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+/** A reusable trait that expands into a set of fields (and optional references). */
+export interface TraitDef {
+	cd: string;
+	description: string;
+	/** Other traits this one includes (expanded first). */
+	includes?: string[];
+	/** Fields injected, keyed by column code. `{entity}` / `{Entity}` are templated. */
+	fields: Record<string, FieldDef>;
+	/** Foreign-key references injected (legacy `references` block). */
+	references?: Record<string, unknown>;
+}
+
+/** Description of a column kind for friendly pickers. */
+export interface ColumnTypeDef {
+	cd: ColumnTypeCd;
+	/** Author-facing label. */
+	name: string;
+	/** One-line explanation. */
+	description: string;
+}

package/src/webhooks.ts

@@ -0,0 +1,35 @@
+// Webhooks — authoring shape of `webhooks.json`. Mirror of webhooks.schema.json.
+
+import type { EntityEvent } from "./triggers";
+
+/** Outbound payload shaping for a webhook subscription. */
+export interface WebhookPayload {
+	/** Field codes to include. If omitted, all visible fields are included. */
+	include?: string[];
+	/** Include previous field values on update/status_change events. */
+	includeOld?: boolean;
+}
+
+/** A single webhook subscription. */
+export interface WebhookSubscription {
+	/** Unique identifier within the module. */
+	code: string;
+	description: string;
+	/** Entity code that triggers this webhook. */
+	entity: string;
+	event: EntityEvent;
+	/** Formula evaluated against the record; webhook fires only if true. */
+	condition?: string;
+	/** Default endpoint URL (admin can override). */
+	endpointUrl?: string;
+	/** Secret code for the API key (from `dforge.secret`). */
+	secretCd?: string;
+	payload?: WebhookPayload;
+	/** Enabled (default true). */
+	enabled?: boolean;
+}
+
+/** A `webhooks.json` file. */
+export interface WebhooksFile {
+	subscriptions: WebhookSubscription[];
+}