@opencxh/domain 1.266.0 → 1.274.0

package/dist/entities/rule/condition-flat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/rule/condition.d.ts

@@ -0,0 +1,52 @@
+/**
+ * JSONLogic as a tree a person can edit, and back again.
+ *
+ * In `domain` and not in an app because there are now two builders on the same language: the
+ * playbook's condition field and the rule editor. Two parsers for one expression language is two
+ * places for "what does `!` on a variable mean" to be answered differently — and a condition that
+ * round-trips through one and not the other silently changes what a rule does.
+ *
+ * Pure, no dependencies: the evaluator itself (json-logic-js) lives with the executor.
+ */
+export type ComparisonOp = "==" | "!=" | ">" | "<" | ">=" | "<=";
+/**
+ * Truth tests with no right-hand side. Needed because an `extract` step yields `null` for a
+ * field that was not in the message: "is not equal to empty string" is then true, and a gate
+ * that trusts that lets exactly the empty cases through. There is no literal you can put
+ * beside `==` to catch that, so this is its own operator.
+ */
+export type UnaryOp = "filled" | "empty";
+export type Op = ComparisonOp | "in" | UnaryOp;
+export type Literal = string | number | boolean;
+export declare const UNARY_OPS: ReadonlySet<Op>;
+export interface GroupNode {
+    kind: "group";
+    op: "and" | "or";
+    children: BuilderNode[];
+}
+export interface ConditionLeaf {
+    kind: "rule";
+    op: Op;
+    varPath: string;
+    value: Literal;
+}
+export interface NotNode {
+    kind: "not";
+    child: BuilderNode;
+}
+export type BuilderNode = GroupNode | ConditionLeaf | NotNode;
+export declare function emptyConditionLeaf(): ConditionLeaf;
+/** Parse a JSONLogic expression into the BuilderNode tree; null if unmodelable (raw fallback). */
+export declare function parse(expr: unknown): GroupNode | null;
+/** Serialize a BuilderNode tree back to JSONLogic (inverse of parse). */
+export declare function serialize(node: BuilderNode): unknown;
+/**
+ * The rule as one readable expression, for the summary on a step card.
+ * `null` if the expression cannot be modelled (then the card shows nothing
+ * instead of a half-truth).
+ *
+ * Deliberately in **operators**, not words: `$a >= 0.7` is the same in every
+ * language, so this rule need not go through i18n — and `OP_LABELS` (which is
+ * Dutch) does not belong on a card everyone reads.
+ */
+export declare function describeExpression(expr: unknown): string | null;

package/dist/entities/rule/condition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/rule/index.d.ts

@@ -1,2 +1,4 @@
+export * from './condition';
 export * from './match';
+export * from './trigger-source';
 export * from './types';

package/dist/entities/rule/trigger-source.d.ts

@@ -0,0 +1,137 @@
+import { ToolCatalogEntry } from '../../platform/ai-tools';
+/**
+ * What kind of value sits at a field, so the builder knows which widget to draw and the
+ * comparison operators that make sense.
+ *
+ * No `object`: a rule compares a leaf. Offering a whole object as the left-hand side of `==`
+ * produces a condition that is never true and reads as if it should be.
+ *
+ * `string[]` is here for the same reason rather than being folded into `string`. Tags, labels and
+ * party keys are the most obvious things to write a rule about, and on an array only `in` means
+ * anything — `==` against one is the silent never-matches this whole seam exists to prevent.
+ */
+export type EventFieldType = "string" | "string[]" | "number" | "boolean" | "date";
+/** Operators that mean something for this kind of value. The builder offers no others. */
+export declare function opsForFieldType(type: EventFieldType): readonly string[];
+/** One choice for a field with a fixed or looked-up set of values. */
+export interface EventFieldOption {
+    value: string;
+    /**
+     * The label as the server could build it. For something an admin typed (a project status, an
+     * inbox) that is the text itself; for one of ours it is the already-resolved fallback.
+     */
+    label: string;
+    /**
+     * Translation key, for a value that is *ours* and therefore translatable.
+     *
+     * Same split as `ActivityPreview.snippet`/`snippetKey`, and for the same reason: the list is
+     * built once on a server that has no user language, while every reader has their own. The
+     * builder prefers this and falls back to `label`.
+     */
+    labelKey?: string;
+}
+/**
+ * One thing a rule can test, declared by the app that writes the row.
+ *
+ * **Why declared and not listed centrally.** A hand-written table of fields drifts from the
+ * payload it describes, and the drift is silent: a rule on a path that yields `undefined` never
+ * fires and says nothing about why. That already happened here once — `TRIGGER_VARS` exists
+ * because the picker offered `trigger.fromEmail` and `trigger.channel`, neither of which the
+ * engine ever filled. A central list for comms, work and sales would be that same table with
+ * three apps to drift from instead of one.
+ */
+export interface EventField {
+    /**
+     * Path under `subject`, dot-notated: `"priority"`, `"lastActivityPreview.text"`.
+     *
+     * Relative, because `subject` is where the owning app's row lands in the condition context
+     * (`matchRules` builds `{ event, subject }`) and repeating that prefix in every declaration is
+     * an invitation to get it wrong in one of them. {@link fieldVarPath} adds it, once.
+     */
+    path: string;
+    type: EventFieldType;
+    /** What a person calls this. The builder shows this; the path is never on screen. */
+    label: string;
+    /**
+     * A fixed set of values — the builder offers a dropdown instead of a free text field.
+     *
+     * For what the *app* defines (a priority, a direction, a status category). What the
+     * *organisation* defines goes through {@link lookup}, because it is data and not vocabulary.
+     */
+    values?: EventFieldOption[];
+    /**
+     * The values are organisation data: ask the declaring app via `/provider/triggers/options`.
+     *
+     * This exists so the builder needs no per-field knowledge. Today `ConditionBuilder` has a
+     * `topicOptions()` that recognises a topic *by field name* — one hard-coded exception, and
+     * the second one (inboxes, users, statuses, pipelines) makes it a pattern.
+     */
+    lookup?: string;
+}
+/**
+ * One event an app publishes, and what a rule can ask about its subject.
+ *
+ * `fields` is per event and not per app on purpose: the subject differs even within one app —
+ * comms hands over the interaction, work the item, sales the transaction.
+ */
+export interface EventDescriptor {
+    /** As the bus delivers it, app-prefixed: `"communication:activities:created"`. */
+    name: string;
+    /** What this event is, in the author's language: "Er komt een bericht binnen". */
+    label: string;
+    /**
+     * What the subject is. Also the key the undo reader uses to fetch current state, so a new
+     * subject kind needs a reader there before its runs can be undone.
+     */
+    subjectKind: string;
+    fields: EventField[];
+}
+/** What a `trigger-source` returns on `GET /provider/triggers/describe`. */
+export interface TriggerSourceDescription {
+    events: EventDescriptor[];
+}
+/** An event plus the app that answered for it — the merged catalog a builder reads. */
+export interface VocabularyEvent extends EventDescriptor {
+    /**
+     * From the runtime, never from a field inside the payload: that would let one app claim
+     * another's events. Same rule the rest of the fan-out helpers hold.
+     */
+    app: string;
+}
+/**
+ * Everything a builder needs to write a rule: what it can react to, and what it can do.
+ *
+ * Both halves in one answer because they are one question — "what is possible here" — and because
+ * they are read together on every builder render. The action half is the tool federation with the
+ * model taken out from in front; it is filtered to what a rule may actually use, so the builder
+ * never has to show something it would refuse to save.
+ */
+export interface RuleVocabulary {
+    events: VocabularyEvent[];
+    /** The actions a rule may use. Outward ones are absent, not disabled — see `validateActions`. */
+    actions: ToolCatalogEntry[];
+    /** Apps that declare the role but answered nothing. Silence is named, not hidden. */
+    degradedApps: string[];
+}
+/**
+ * The JSONLogic variable for a field: `subject.<path>`.
+ *
+ * One function so the builder, the templates and the declaration tests cannot disagree about the
+ * prefix. `matchRules` evaluates against `{ event, subject }`, and a condition written against
+ * the bare path silently compares `undefined`.
+ */
+export declare function fieldVarPath(field: Pick<EventField, "path">): string;
+/** The event with this name, or `undefined`. */
+export declare function findEvent(vocabulary: Pick<RuleVocabulary, "events">, name: string): VocabularyEvent | undefined;
+/**
+ * Which declared paths the real subject does not have.
+ *
+ * **This is the point of declaring fields near the code that writes them.** A declaration is only
+ * worth more than a central list if something holds it against reality, and this is that
+ * something: each app's test feeds a real row through and asserts the answer is empty.
+ *
+ * A path is "missing" when it resolves to `undefined` — absent, or running through a `null`.
+ * `null` itself counts as present: a cleared assignee is a value a rule can meaningfully test
+ * for, and treating it as missing would make every declaration fail on an empty row.
+ */
+export declare function missingFieldPaths(fields: readonly EventField[], subject: unknown): string[];

package/dist/entities/rule/trigger-source.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/rule/types.d.ts

@@ -60,6 +60,8 @@ export interface Rule {
     organizationId: string;
     ownerScope: OwnerScope;
     name: string;
+    /** What this rule is for, in the author's own words. */
+    description?: string;
     enabled: boolean;
     /**
      * Only `event` runs today. The other arms exist because the vocabulary is shared; a rule on a