@rippling/rippling-sdk 0.2.0-alpha.104 → 0.2.0-alpha.106

package/src/lib/charts/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Chart rule vocabulary — shared types.
+ *
+ * A rule is a small, serializable tree of nodes discriminated by `kind`. The
+ * agent builds it with the helpers in `builders.ts`, which emit it wrapped in a
+ * `{$rule}` placeholder — the same idea as the `{$fn}` placeholders a chart
+ * already emits. The renderer resolves it with `evaluate`; the settings panel
+ * reads it with `describe`. All three agree because a node can only ever be one
+ * of the kinds defined here — the closed set the `chartRuleSchema` describes.
+ *
+ * v1 is scoped to conditional formatting: compare this datum's `value` against a
+ * constant, and (optionally) pick between two values. Richer pieces — aggregates,
+ * logic, more refs — are the documented roadmap in the README.
+ */
+
+export const CHART_RULE_CONTRACT_VERSION = 'chart_rule.v1' as const;
+export type ChartRuleContractVersion = typeof CHART_RULE_CONTRACT_VERSION;
+
+/** A leaf value a rule can carry or resolve to. */
+export type Scalar = number | string | boolean | null;
+
+/* -------------------------------------------------------------------------- */
+/* Nodes — the closed set, discriminated by `kind`. Each appears in every face. */
+/* -------------------------------------------------------------------------- */
+
+/** Reads a value out of the evaluation context — this datum's plotted value. */
+export type RefNode = { kind: 'value' };
+
+export interface LiteralNode {
+  kind: 'literal';
+  value: Scalar;
+}
+
+export type ComparisonKind =
+  | 'equals'
+  | 'isNot'
+  | 'lessThan'
+  | 'greaterThan'
+  | 'lessOrEqual'
+  | 'greaterOrEqual';
+export interface ComparisonNode {
+  kind: ComparisonKind;
+  left: RuleNode;
+  right: RuleNode;
+}
+
+/** The conditional-value form produced by `when(cond, then, else)`. */
+export interface IfElseNode {
+  kind: 'ifElse';
+  cond: RuleNode;
+  then: RuleNode;
+  else: RuleNode;
+}
+
+/** Any node of a rule tree. */
+export type RuleNode = RefNode | LiteralNode | ComparisonNode | IfElseNode;
+
+/* -------------------------------------------------------------------------- */
+/* The placeholder — how a rule is embedded in a chart option (like {$fn}).     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The chart channel a rule drives. v1 supports colour only — a rule decides the
+ * colour of a series/datum. Other channels (opacity, label visibility, …) are
+ * the documented roadmap and would be added here.
+ */
+export type RuleChannel = 'color';
+
+/**
+ * What a builder returns: a rule tree, marked so the renderer can find it, and
+ * tagged with the channel it targets. `channel: 'color'` says this resolves to a
+ * colour — so a reader sees the target without inferring it from where it sits.
+ */
+export interface RulePlaceholder {
+  $rule: RuleNode;
+  channel: RuleChannel;
+}
+
+/** A placeholder, or the bare tree — what `evaluate` and `describe` accept. */
+export type Rule = RulePlaceholder | RuleNode;
+
+/* -------------------------------------------------------------------------- */
+/* Evaluation                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** What a rule is evaluated against: the current datum's value. */
+export interface RuleContext {
+  value: number;
+}
+
+/** The result of evaluating a node. */
+export type RuleValue = Scalar;
+
+/**
+ * The deepest a rule may nest before `evaluate`/`describe` refuse it. Real rules
+ * are a handful of levels; this only stops a pathological deserialized tree from
+ * overflowing the stack. Far below the JS call-stack limit.
+ */
+export const MAX_RULE_DEPTH = 256;
+
+/* -------------------------------------------------------------------------- */
+/* Description — what the settings panel renders                                */
+/* -------------------------------------------------------------------------- */
+
+export type ControlRole = 'rule' | 'comparison' | 'ref' | 'literal';
+
+/** A node as the panel should show it: a label, its editable value, its parts. */
+export interface Control {
+  role: ControlRole;
+  label: string;
+  value?: Scalar;
+  parts?: Control[];
+}

package/src/lib/charts.ts

@@ -0,0 +1,43 @@
+export {
+  color,
+  equals,
+  greaterOrEqual,
+  greaterThan,
+  isNot,
+  isRulePlaceholder,
+  lessOrEqual,
+  lessThan,
+  literal,
+  value,
+  when,
+  type Operand,
+} from './charts/builders';
+export { evaluate } from './charts/evaluate';
+export { describe } from './charts/describe';
+export { chartRuleSchema, CHART_RULE_SCHEMA_ID } from './charts/schema';
+export {
+  ChartRuleError,
+  MalformedRuleError,
+  RuleDepthError,
+  RuleTypeError,
+  UnknownNodeError,
+} from './charts/errors';
+export {
+  CHART_RULE_CONTRACT_VERSION,
+  MAX_RULE_DEPTH,
+  type ChartRuleContractVersion,
+  type ComparisonKind,
+  type ComparisonNode,
+  type Control,
+  type ControlRole,
+  type IfElseNode,
+  type LiteralNode,
+  type RefNode,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RulePlaceholder,
+  type RuleValue,
+  type Scalar,
+} from './charts/types';

package/src/lib/manifest/_existing-component-fields.ts

@@ -13,6 +13,8 @@ function labelComponent(componentType: string, component: Record<string, any>):
     component['source_agent_id'] ??
     component['field_api_name'] ??
     component['section_id'] ??
+    component['definition_id'] ??
+    component['obj_id'] ??
     'unknown';
   return `${componentType}:${String(id)}`;
 }

package/src/lib/manifest/existing-manifest-context.ts

@@ -16,6 +16,7 @@ import { ManifestFunction } from './manifest-function';
 import { Rule } from './rule';
 import { SduiPage } from './sdui-page';
 import { Validation } from './validation';
+import { Workflow } from './workflow';
 import {
   optionalStringComponentField,
   requireObjectComponentField,
@@ -92,6 +93,8 @@ function componentLabel(component: Record<string, any>): string {
     component['source_skill_id'] ??
     component['field_api_name'] ??
     component['section_id'] ??
+    component['definition_id'] ??
+    component['obj_id'] ??
     'unknown';
   return `${type}:${id}`;
 }
@@ -355,6 +358,15 @@ export class ExistingManifestContext {
     return this.loadACPAgentComponent(component);
   }
 
+  loadWorkflow(definitionId: string): Workflow {
+    const component = this.findUnique(
+      'WORKFLOW_DEFINITION',
+      (candidate) => candidate['definition_id'] === definitionId,
+      `WORKFLOW_DEFINITION ${definitionId}`,
+    );
+    return this.loadWorkflowComponent(component);
+  }
+
   private loadComponent(component: Record<string, any>): unknown {
     switch (component['type']) {
       case 'AGENT':
@@ -391,6 +403,8 @@ export class ExistingManifestContext {
         return this.loadSduiPageComponent(component);
       case 'CUSTOM_APP':
         return this.loadAppComponent(component);
+      case 'WORKFLOW_DEFINITION':
+        return this.loadWorkflowComponent(component);
       default:
         return this.loadRawComponent(component);
     }
@@ -626,6 +640,14 @@ export class ExistingManifestContext {
     );
   }
 
+  private loadWorkflowComponent(component: Record<string, any>): Workflow {
+    const definitionId = requireStringComponentField(component, 'definition_id', Workflow.componentType);
+    const cacheKey = this.cacheKey('WORKFLOW_DEFINITION', definitionId);
+    return this.getOrLoad(cacheKey, () =>
+      Workflow._fromExistingComponent(this.getManifestBuilder(), component),
+    );
+  }
+
   private loadRawComponent(component: Record<string, any>): ExistingRawComponent {
     const index = this.componentIndexes.get(component) ?? -1;
     const cacheKey = this.cacheKey('RAW', `${index}:${componentLabel(component)}`);

package/src/lib/manifest/workflow/index.ts

@@ -1,5 +1,10 @@
 import { generateId } from '../_helpers';
 import type { BusinessEventKey } from '../business-event';
+import { requireObjectComponentField, requireStringComponentField } from '../_existing-component-fields';
+import {
+  getExistingManifestContext,
+  type ExistingManifestContextOptions,
+} from '../existing-manifest-context';
 import type { ManifestFunction } from '../manifest-function';
 import type { ManifestComponentDeletion, ManifestScope } from '../manifest-builder';
 import type { WorkflowActionPayloads } from './actions';
@@ -473,6 +478,11 @@ export interface WorkflowProps {
   categories?: WorkflowCategory[];
 }
 
+function cloneJson<T>(value: T): T {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
 function assertNonEmptyString(value: unknown, path: string): void {
   if (typeof value !== 'string' || !value.trim()) throw new Error(`${path} is required.`);
 }
@@ -882,6 +892,60 @@ export class Workflow {
     scope._register(this);
   }
 
+  static loadFromExisting(definitionId: string, options: ExistingManifestContextOptions = {}): Workflow {
+    return getExistingManifestContext(options).loadWorkflow(definitionId);
+  }
+
+  /** @internal Hydrates a workflow from existing manifest wire JSON. */
+  static _fromExistingComponent(scope: ManifestScope, component: Record<string, any>): Workflow {
+    const workflowMeta = requireObjectComponentField(component, 'workflow_meta', Workflow.componentType);
+    const definitionId = requireStringComponentField(component, 'definition_id', Workflow.componentType);
+    const props: WorkflowProps = {
+      definitionId,
+      title: requireStringComponentField(
+        { definition_id: definitionId, name: workflowMeta['name'] },
+        'name',
+        Workflow.componentType,
+      ),
+      trigger: cloneJson(
+        requireObjectComponentField(component, 'trigger', Workflow.componentType),
+      ) as WorkflowTrigger,
+    };
+    if (typeof workflowMeta['description'] === 'string') props.description = workflowMeta['description'];
+    if (typeof workflowMeta['recipe_id'] === 'string') props.recipeId = workflowMeta['recipe_id'];
+    if (typeof component['function_api_name'] === 'string') {
+      props.function = component['function_api_name'];
+    }
+    if (typeof component['version_status'] === 'string') {
+      props.versionStatus = component['version_status'] as WorkflowVersionStatus;
+    }
+    if (typeof component['trigger_status'] === 'string') {
+      props.triggerStatus = component['trigger_status'] as WorkflowTriggerStatus;
+    }
+    if (component['graph'] != null) {
+      props.graph = cloneJson(component['graph']) as WorkflowGraph;
+    }
+    if (component['functions_inferred_graph'] != null) {
+      props.functionsInferredGraph = cloneJson(component['functions_inferred_graph']) as WorkflowGraph;
+    }
+    if (component['custom_variables'] != null) {
+      props.customVariables = cloneJson(component['custom_variables']) as Record<
+        string,
+        WorkflowCustomVariable
+      >;
+    }
+    if (component['function_api_names_by_old_id'] != null) {
+      props.functionApiNamesByOldId = cloneJson(component['function_api_names_by_old_id']) as Record<
+        string,
+        string
+      >;
+    }
+    if (component['categories'] != null) {
+      props.categories = cloneJson(component['categories']) as WorkflowCategory[];
+    }
+    return new Workflow(scope, props);
+  }
+
   private _validate(): void {
     assertNonEmptyString(this._title, 'Workflow.workflow_meta.name');
     if (this._props.function !== undefined)