@dforge-core/metadata 0.0.43 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/metadata",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
   "license": "MIT",
   "author": "dForge",

package/schemas/entity.schema.json

@@ -108,10 +108,20 @@
 		},
 		"traits": {
 			"type": "array",
-			"description": "Entity traits expanded during module install (authoring shortcut). Trait definitions loaded from DB (seeded by metadata module).",
+			"description": "Entity traits expanded during module install (authoring shortcut): a platform trait, or one the module declares in its own traits.json. Pack and install refuse a name that is neither; the schema cannot see traits.json, so it accepts any trait-shaped name and lists only the platform traits.",
 			"items": {
-				"type": "string",
-				"enum": ["identity", "audit", "audit-full", "soft-delete", "sorting", "postable", "accumulation", "ledger", "period", "file-library"]
+				"anyOf": [
+					{
+						"type": "string",
+						"enum": ["identity", "audit", "audit-full", "soft-delete", "sorting", "postable", "accumulation", "ledger", "period", "file-library"],
+						"description": "Platform trait."
+					},
+					{
+						"type": "string",
+						"pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
+						"description": "A trait declared in the module's own traits.json."
+					}
+				]
 			},
 			"uniqueItems": true
 		},
@@ -418,7 +428,7 @@
 				"fieldTypeCd": {
 					"type": "string",
 					"enum": [
-						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent",
+						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent", "filesize",
 						"checkbox", "date", "datetime", "time",
 						"dropdown", "flags", "tags", "json", "hidden", "color", "image", "file",
 						"markdown", "richtext", "lookup", "user", "grid", "list", "entitylink", "code"

package/schemas/reports.schema.json

@@ -401,9 +401,13 @@
 
 		"columnDef": {
 			"type": "object",
+			"description": "Override of one column the dataset already projects (from the entity, the stored procedure's result columns, or the register). Name only what differs: each key replaces the projected value. A label here is a literal and wins over a translated header.",
 			"properties": {
-				"label": { "type": "string" },
-				"visible": { "type": "boolean" },
+				"label": { "type": "string", "description": "Column header. Not translated: leave it out to keep the entity's or the procedure's translated header." },
+				"fieldTypeCd": { "type": "string", "description": "Control the value renders with, replacing the projected one." },
+				"format": { "type": "string", "description": "Display format, replacing the column's display format." },
+				"baseDatatypeCd": { "type": "string", "description": "Read only where the dataset projects no columns of its own (a stored procedure with no result columns), when columnsDef is the column list. Ignored as an override: the projected column's datatype stands." },
+				"visible": { "type": "boolean", "description": "Accepted, but neither report.run nor the client reads it: it has no effect." },
 				"width": { "type": "integer", "minimum": 1 }
 			},
 			"additionalProperties": false

package/schemas/translations.schema.json

@@ -84,6 +84,23 @@
 				"$ref": "#/$defs/report"
 			}
 		},
+		"storedProcedures": {
+			"type": "object",
+			"description": "Stored-procedure code (logic/stored_procedures.json) → result-column headers. A header belongs to the procedure, not to a report: every dataset bound to the procedure shows the same translation. A dataset's columnsDef label overrides it with a literal, so leave the label out of columnsDef to keep the column translated. Required, per declared column, by `module pack` / `module validate` for each non-English supported locale; install only warns.",
+			"additionalProperties": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"columns": {
+						"type": "object",
+						"description": "Result column code → header.",
+						"additionalProperties": {
+							"$ref": "#/$defs/labelOnly"
+						}
+					}
+				}
+			}
+		},
 		"actions": {
 			"type": "object",
 			"description": "Action code (ui/actions.json) → label, tooltip and parameter labels.",
@@ -248,6 +265,10 @@
 				"label": {
 					"$ref": "#/$defs/label"
 				},
+				"desc": {
+					"type": "string",
+					"description": "Translated report description."
+				},
 				"datasets": {
 					"type": "object",
 					"description": "Dataset code → caption.",

package/src/actions.ts

@@ -60,6 +60,25 @@ export interface ActionDef {
 	 * "Run in Background". A parameterless `isAsync` action is queued directly.
 	 */
 	isAsync?: boolean;
+	/**
+	 * Code of a print template of the action's entity. The run dialog renders it as a PDF beside the params when the
+	 * action is opened on one record, so the user sees the document the action sends before it goes.
+	 */
+	previewTemplate?: string;
+	/**
+	 * Saved parameter sets the module ships for this action, keyed by set name. They install as shared sets owned by
+	 * the module: read-only for users and refreshed on every install, and a user can save a set of their own under the
+	 * same name, which wins for them. Each `values` key must be a param the action declares; a string starting with `=`
+	 * is a formula. Needs the action to declare params.
+	 */
+	paramSets?: Record<string, ActionParamSetDef>;
+}
+
+/** One shipped parameter set of an action. */
+export interface ActionParamSetDef {
+	description?: string;
+	/** Value by param code. */
+	values: Record<string, unknown>;
 }
 
 /** A `ui/actions.json` file: action code → definition. */

package/src/derive.ts

@@ -24,6 +24,7 @@ const TEXT_BACKED = new Set(["textarea", "markdown", "richtext", "code"]);
 const DB_DATATYPE_OVERRIDE: Record<string, string> = {
 	file: "jsonb",
 	image: "jsonb",
+	filesize: "int8",
 };
 
 export interface DeriveOptions {

package/src/dsl/builtins.ts

@@ -149,9 +149,9 @@ export const BUILTINS: Builtin[] = [
 	},
 	{
 		name: "sendEmail",
-		signature: "sendEmail(to, subjectOrTemplate, dataOrBody?)",
+		signature: "sendEmail(to, subjectOrTemplate, dataOrBody?, attachments?)",
 		returns: "void",
-		doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>…</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code — so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. There is no fourth argument.",
+		doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>…</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code — so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()`, `attachText()` or `attachBase64()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). A `printPdf()` file can be attached only by the user who generated it (or a workspace admin) and not in a scheduled job; a file built with `attachText()` / `attachBase64()` has no owner and works everywhere, a scheduled job included. At most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action.",
 	},
 
 	// External calls
@@ -192,7 +192,31 @@ export const BUILTINS: Builtin[] = [
 		name: "download",
 		signature: "download(url, fileName?)",
 		returns: "void",
-		doc: "Set a download URL on the action result; the browser opens it when the action returns. It fetches nothing and stores nothing — the URL must already serve the bytes, e.g. the `/api/temp-file/{token}` a service handed back. To put a remote file INTO storage, fetch it with `callApi()` and write it to a file column.",
+		doc: "Set a download URL on the action result; the browser opens it when the action returns. It fetches nothing and stores nothing — the URL must already serve the bytes, e.g. the `/api/temp-file/{token}` a service handed back. To hand over a file the script builds, use `downloadText()` / `downloadBase64()`. To put a remote file INTO storage, fetch it with `callApi()` and write it to a file column.",
+	},
+	{
+		name: "downloadText",
+		signature: "downloadText(content, fileName, encoding?, mimeType?)",
+		returns: "string",
+		doc: "Hand the user a text file the script built: encodes `content` in `encoding` (`utf-8` by default; `windows-1251`, `cp866`, `koi8-u`… also work), stores it in temp storage and sets it as the action's download. Line endings are written as given (join with `'\\r\\n'` for CR LF), no BOM. Returns the signed `/api/temp-file/{token}` URL, valid for an hour (`FileStorage:TempTokenExpirationMinutes`). An action has one download: a later call replaces the earlier. In a background or scheduled run nobody receives the download, so pass the URL on in `notify()`. Max 10 MB per file, 10 files per run.",
+	},
+	{
+		name: "downloadBase64",
+		signature: "downloadBase64(base64, fileName, mimeType?)",
+		returns: "string",
+		doc: "`downloadText()` for bytes: decodes `base64` and hands it to the user as `fileName` (`application/octet-stream` unless `mimeType` says otherwise). Returns the signed download URL.",
+	},
+	{
+		name: "attachText",
+		signature: "attachText(content, fileName, encoding?, mimeType?)",
+		returns: "object",
+		doc: "Build a text file to attach to an email: encodes `content` in `encoding` (`utf-8` by default) and returns a descriptor for `sendEmail()`'s fourth argument, e.g. `sendEmail(to, 'Interview', body, attachText(ics, 'invite.ics', 'utf-8', 'text/calendar'))`. The file keeps `mimeType` (`text/plain` by default). It is the script's own output, so no user's rights are involved and it works in a scheduled job. Only the emails of this run can name it. Max 10 MB per file and 10 files per run, shared with `downloadText()` / `downloadBase64()`.",
+	},
+	{
+		name: "attachBase64",
+		signature: "attachBase64(base64, fileName, mimeType?)",
+		returns: "object",
+		doc: "`attachText()` for bytes given as base64 (`application/octet-stream` unless `mimeType` says otherwise).",
 	},
 	{
 		name: "getSetting",
@@ -247,6 +271,13 @@ export const BUILTINS: Builtin[] = [
 		entityArg: 0,
 		doc: "Build a clickable link to a record, for an `entitylink` column. Always pass a **qualified** code — `entity_cd` is only unique per module.",
 	},
+	{
+		name: "printPdf",
+		signature: "printPdf(entityCd, key, templateCd)",
+		returns: "object",
+		entityArg: 0,
+		doc: "Render a print template to a PDF **as the current user** and return the stored file as `{ fileId, fileName, mimeType, size, checksum }` — a descriptor, never the bytes. `key` is the record's `{ column: value }` key (or a scalar for a single-column key); `templateCd` is the template's code on that entity. The record is read under the user's rights and the folder's row filter, as the Generate PDF button reads it. Always pass a **qualified** entity code. Not available in a scheduled job or a background action (no signed-in user), refused in a computing-only run, and limited to 10 per execution; each render holds the action's transaction open while it works.",
+	},
 ];
 
 export const BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.name, b]));

package/src/field-types.ts

@@ -20,6 +20,7 @@ export const fieldTypes = [
 	{ cd: "number", name: "Number", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "currency", name: "Currency", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: 2, useStringInFilter: false },
 	{ cd: "percent", name: "Percent", columnType: "D", baseDatatypeCd: "number", supportedAgg: "CAM", maxLen: null, precision: 2, useStringInFilter: false },
+	{ cd: "filesize", name: "File Size", columnType: "D", baseDatatypeCd: "number", supportedAgg: "SCAM", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "checkbox", name: "Checkbox", columnType: "D", baseDatatypeCd: "bool", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "date", name: "Date", columnType: "D", baseDatatypeCd: "date", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },
 	{ cd: "datetime", name: "Date & Time", columnType: "D", baseDatatypeCd: "timestamp", supportedAgg: "CM", maxLen: null, precision: null, useStringInFilter: false },

package/src/index.ts

@@ -185,7 +185,7 @@ export type {
 	TabGroupSection,
 } from "./card-layouts";
 export type { SeedDataFile, SeedDataRepeat } from "./seed-data";
-export type { ActionsFile, ActionDef, ActionExecutionMode } from "./actions";
+export type { ActionsFile, ActionDef, ActionParamSetDef, ActionExecutionMode } from "./actions";
 
 // Flag catalog — the only letters valid on an authored column, at field level and
 // on a per-view override alike (both `flags` patterns in entity.schema.json are

package/src/reports.ts

@@ -115,7 +115,11 @@ export interface ReportQuery {
 
 /** Per-column metadata override on a dataset. */
 export interface ColumnDef {
+	/** A literal header: wins over the entity's or the procedure's translated one. */
 	label?: string;
+	fieldTypeCd?: string;
+	format?: string;
+	/** Accepted, but read by nothing. */
 	visible?: boolean;
 	width?: number;
 }

package/src/types.ts

@@ -50,6 +50,7 @@ export type FieldTypeCd =
 	| "number"
 	| "currency"
 	| "percent"
+	| "filesize"
 	| "checkbox"
 	| "date"
 	| "datetime"