@lovrabet/rabetbase-cli 2.5.2 → 2.5.3-beta.2

package/lib/core/flow-config.d.ts

@@ -0,0 +1,628 @@
+/** Supported node types in the current simple approval-flow DSL. */
+export type FlowNodeType = "START" | "END" | "APPROVAL" | "CONDITION" | "SCRIPT" | "NOTIFICATION";
+/** Supported approval modes in the current simple approval-flow DSL. */
+export type ApprovalMode = "SINGLE" | "ALL" | "ANY";
+/** Supported user-task modes. Missing values keep the historical APPROVAL behavior. */
+export type ApprovalTaskMode = "APPROVAL" | "HANDLE";
+/** Supported units for retry and approval timeout durations. */
+export type FlowTimeUnit = "SECONDS" | "MINUTES" | "HOURS" | "DAYS";
+/** Supported approval timeout actions. */
+export type ApprovalTimeoutAction = "AUTO_APPROVE" | "AUTO_REJECT" | "EXECUTE_BFF";
+/** Supported edge conditions in the current simple approval-flow DSL. */
+export type FlowConditionType = "ALWAYS" | "APPROVED" | "REJECTED" | "EXPRESSION";
+/** Supported design-time flow types. */
+export type FlowType = "FORM_FLOW" | "INDEPENDENT_FLOW";
+/** Page rendering mode for an independent workflow. */
+export type FlowPageMode = "CUSTOM_PAGE" | "PLATFORM_FORM";
+/** JSON object used by the flow DSL. */
+export interface FlowJsonObject {
+    [key: string]: unknown;
+}
+/** A notification card fact row. */
+export interface FlowNotificationFact extends FlowJsonObject {
+    label: string;
+    value: string;
+}
+/** A notification card action. */
+export interface FlowNotificationAction extends FlowJsonObject {
+    text: string;
+    url: string;
+}
+/** An explicit notification recipient. */
+export interface FlowNotificationRecipient extends FlowJsonObject {
+    type: "USER" | "ROLE" | "EMAIL";
+    value: string;
+    role?: "TO" | "CC" | "BCC";
+}
+/** Stable v1 notification node configuration. */
+export interface FlowNotificationConfig extends FlowJsonObject {
+    version?: "v1";
+    configCode: string;
+    failurePolicy?: "CONTINUE" | "FAIL";
+    template: {
+        title: string;
+        summary: string;
+        facts?: FlowNotificationFact[];
+        detailMarkdown?: string;
+        actions?: FlowNotificationAction[];
+        [key: string]: unknown;
+    };
+    recipients?: FlowNotificationRecipient[];
+}
+/** A positive duration used by async retry and approval timeout settings. */
+export interface FlowTimeAmount extends FlowJsonObject {
+    value: number;
+    unit: FlowTimeUnit;
+}
+/** SCRIPT node asynchronous execution and persistent retry settings. */
+export interface FlowAsyncExecution extends FlowJsonObject {
+    enabled?: boolean;
+    retryCount?: number;
+    retryInterval?: FlowTimeAmount;
+}
+/** APPROVAL node timeout settings. */
+export interface FlowApprovalTimeout extends FlowJsonObject {
+    enabled?: boolean;
+    duration?: FlowTimeAmount;
+    action?: ApprovalTimeoutAction;
+    interrupting?: boolean;
+    scriptName?: string;
+    resultVariable?: string;
+}
+/** APPROVAL / END node default copy recipients. Custom-form readSources are unsupported. */
+export interface FlowCcConfig extends FlowJsonObject {
+    recipientUserIds: string[];
+    visible?: string[];
+}
+/** A flow node. Additional DSL fields are preserved for forward compatibility. */
+export interface FlowNode extends FlowJsonObject {
+    id: string;
+    type: FlowNodeType;
+    name: string;
+    /** Optional custom-page navigation target for this user task. */
+    pageId?: number;
+    position: {
+        x: number;
+        y: number;
+        [key: string]: unknown;
+    };
+    approvalMode?: ApprovalMode;
+    taskMode?: ApprovalTaskMode;
+    assignee?: FlowJsonObject;
+    transferCandidates?: FlowJsonObject;
+    sequential?: boolean;
+    result?: string;
+    scriptName?: string;
+    resultVariable?: string;
+    async?: FlowAsyncExecution;
+    timeout?: FlowApprovalTimeout;
+    cc?: FlowCcConfig;
+    config?: FlowNotificationConfig;
+}
+/** A directed flow edge. */
+export interface FlowEdge extends FlowJsonObject {
+    id?: string;
+    source?: string;
+    target?: string;
+    sourceNodeId?: string;
+    targetNodeId?: string;
+    conditionType?: FlowConditionType;
+    expression?: string;
+    defaultFlow?: boolean;
+    name?: string;
+    waypoints?: Array<{
+        x: number;
+        y: number;
+        [key: string]: unknown;
+    }>;
+}
+/** The minimal graph portion of a locally stored flow configuration. */
+export interface FlowJson extends FlowJsonObject {
+    /** Only applies to INDEPENDENT_FLOW; missing values default to CUSTOM_PAGE. */
+    pageMode?: FlowPageMode;
+    /** Optional custom-page navigation target used before starting a workflow. */
+    startPageId?: number;
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}
+/** Local flow manifest metadata and its minimal graph DSL. */
+export interface FlowConfig extends FlowJsonObject {
+    flowName: string;
+    flowDesc?: string;
+    flowType: FlowType;
+    datasetCode?: string;
+    pageId?: number;
+    flowJson: FlowJson;
+}
+/** A normalization warning for a removed or migrated field. */
+export interface FlowConfigWarning {
+    code: "legacy_field_removed" | "empty_metadata_removed";
+    path: string;
+    message: string;
+}
+/** Normalized manifest returned by {@link normalizeFlowConfig}. */
+export interface NormalizedFlowConfig {
+    config: FlowConfig;
+    warnings: FlowConfigWarning[];
+    removedPaths: string[];
+}
+/** A single local validation error. */
+export interface FlowConfigIssue {
+    path: string;
+    message: string;
+}
+/** Result returned by {@link validateFlowConfig}. */
+export interface FlowConfigValidationResult {
+    valid: boolean;
+    errors: FlowConfigIssue[];
+    warnings: FlowConfigWarning[];
+    normalized: FlowConfig;
+    /** In-memory compiler-shaped copy; never write this object to disk. */
+    validationConfig: FlowConfig;
+}
+/** JSON Schema metadata for tools that want to inspect the local manifest shape. */
+export declare const FLOW_CONFIG_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://lovrabet.com/schema/rabetbase-flow-config.json";
+    readonly title: "Rabetbase FlowConfig";
+    readonly type: "object";
+    readonly required: readonly ["flowName", "flowType", "flowJson"];
+    readonly $defs: {
+        readonly userId: {
+            readonly anyOf: readonly [{
+                readonly type: "string";
+                readonly minLength: 1;
+            }, {
+                readonly type: "integer";
+                readonly minimum: 1;
+            }];
+        };
+        readonly position: {
+            readonly type: "object";
+            readonly required: readonly ["x", "y"];
+            readonly properties: {
+                readonly x: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly y: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly timeAmount: {
+            readonly type: "object";
+            readonly required: readonly ["value", "unit"];
+            readonly properties: {
+                readonly value: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly unit: {
+                    readonly enum: readonly ["SECONDS", "MINUTES", "HOURS", "DAYS"];
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly flowNode: {
+            readonly type: "object";
+            readonly required: readonly ["id", "type", "name", "position"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                };
+                readonly type: {
+                    readonly enum: readonly ["START", "END", "APPROVAL", "CONDITION", "SCRIPT", "NOTIFICATION"];
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly pageId: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly position: {
+                    readonly $ref: "#/$defs/position";
+                };
+                readonly approvalMode: {
+                    readonly enum: readonly ["SINGLE", "ALL", "ANY"];
+                };
+                readonly taskMode: {
+                    readonly enum: readonly ["APPROVAL", "HANDLE"];
+                };
+                readonly assignee: {
+                    readonly type: "object";
+                    readonly required: readonly ["strategy"];
+                    readonly properties: {
+                        readonly strategy: {
+                            readonly enum: readonly ["FIXED", "ROLE"];
+                        };
+                        readonly userIds: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly $ref: "#/$defs/userId";
+                            };
+                        };
+                        readonly roleId: {
+                            readonly anyOf: readonly [{
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                            }, {
+                                readonly type: "string";
+                                readonly pattern: "^[1-9][0-9]*$";
+                            }];
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly transferCandidates: {
+                    readonly type: "object";
+                    readonly required: readonly ["strategy", "userIds"];
+                    readonly properties: {
+                        readonly strategy: {
+                            readonly const: "FIXED";
+                        };
+                        readonly userIds: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly $ref: "#/$defs/userId";
+                            };
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly sequential: {
+                    readonly type: "boolean";
+                };
+                readonly result: {
+                    readonly enum: readonly ["APPROVED", "REJECTED"];
+                };
+                readonly scriptName: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly resultVariable: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                };
+                readonly async: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly enabled: {
+                            readonly type: "boolean";
+                        };
+                        readonly retryCount: {
+                            readonly type: "integer";
+                            readonly minimum: 1;
+                            readonly maximum: 10;
+                        };
+                        readonly retryInterval: {
+                            readonly $ref: "#/$defs/timeAmount";
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly timeout: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly enabled: {
+                            readonly type: "boolean";
+                        };
+                        readonly duration: {
+                            readonly $ref: "#/$defs/timeAmount";
+                        };
+                        readonly action: {
+                            readonly enum: readonly ["AUTO_APPROVE", "AUTO_REJECT", "EXECUTE_BFF"];
+                        };
+                        readonly interrupting: {
+                            readonly type: "boolean";
+                        };
+                        readonly scriptName: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly resultVariable: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly cc: {
+                    readonly type: "object";
+                    readonly required: readonly ["recipientUserIds"];
+                    readonly properties: {
+                        readonly recipientUserIds: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly maxItems: 100;
+                            readonly uniqueItems: true;
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                        readonly visible: {
+                            readonly type: "array";
+                            readonly uniqueItems: true;
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                        readonly readSources: false;
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly config: {
+                    readonly type: "object";
+                    readonly required: readonly ["configCode", "template"];
+                    readonly properties: {
+                        readonly version: {
+                            readonly enum: readonly ["v1"];
+                        };
+                        readonly configCode: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly failurePolicy: {
+                            readonly enum: readonly ["CONTINUE", "FAIL"];
+                        };
+                        readonly template: {
+                            readonly type: "object";
+                            readonly required: readonly ["title", "summary"];
+                            readonly properties: {
+                                readonly title: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly summary: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly detailMarkdown: {
+                                    readonly type: "string";
+                                };
+                                readonly facts: {
+                                    readonly type: "array";
+                                    readonly maxItems: 8;
+                                    readonly items: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["label", "value"];
+                                        readonly properties: {
+                                            readonly label: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly value: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                        };
+                                        readonly additionalProperties: true;
+                                    };
+                                };
+                                readonly actions: {
+                                    readonly type: "array";
+                                    readonly maxItems: 2;
+                                    readonly items: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["text", "url"];
+                                        readonly properties: {
+                                            readonly text: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly url: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                        };
+                                        readonly additionalProperties: true;
+                                    };
+                                };
+                            };
+                            readonly additionalProperties: true;
+                        };
+                        readonly recipients: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly required: readonly ["type", "value"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly enum: readonly ["USER", "ROLE", "EMAIL"];
+                                    };
+                                    readonly value: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly role: {
+                                        readonly enum: readonly ["TO", "CC", "BCC"];
+                                    };
+                                };
+                                readonly additionalProperties: true;
+                            };
+                        };
+                    };
+                    readonly additionalProperties: true;
+                };
+                readonly form: false;
+                readonly formPermission: false;
+            };
+            readonly additionalProperties: true;
+        };
+        readonly flowEdge: {
+            readonly type: "object";
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                };
+                readonly source: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly target: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly sourceNodeId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly targetNodeId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly conditionType: {
+                    readonly enum: readonly ["ALWAYS", "APPROVED", "REJECTED", "EXPRESSION"];
+                };
+                readonly expression: {
+                    readonly type: "string";
+                };
+                readonly defaultFlow: {
+                    readonly type: "boolean";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly waypoints: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/position";
+                    };
+                };
+            };
+            readonly allOf: readonly [{
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["source"];
+                }, {
+                    readonly required: readonly ["sourceNodeId"];
+                }];
+            }, {
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["target"];
+                }, {
+                    readonly required: readonly ["targetNodeId"];
+                }];
+            }];
+            readonly additionalProperties: true;
+        };
+    };
+    readonly properties: {
+        readonly id: false;
+        readonly appCode: false;
+        readonly flowName: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly flowDesc: {
+            readonly type: "string";
+        };
+        readonly flowType: {
+            readonly enum: readonly ["FORM_FLOW", "INDEPENDENT_FLOW"];
+        };
+        readonly datasetCode: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly pageId: {
+            readonly type: "integer";
+        };
+        readonly templateName: false;
+        readonly flowJson: {
+            readonly type: "object";
+            readonly required: readonly ["nodes", "edges"];
+            readonly properties: {
+                readonly flowKey: false;
+                readonly flowCode: false;
+                readonly flowName: false;
+                readonly bindDatasetCode: false;
+                readonly datasetCode: false;
+                readonly appCode: false;
+                readonly pageId: false;
+                readonly templateName: false;
+                readonly schemaVersion: {
+                    readonly type: "string";
+                    readonly const: "approval.simple-flow.v1";
+                    readonly description: "Accepted as legacy input and removed during normalization; other versions are unsupported.";
+                };
+                readonly formSchema: false;
+                readonly formDefinitions: false;
+                readonly formPermissions: false;
+                readonly pageMode: {
+                    readonly const: "CUSTOM_PAGE";
+                };
+                readonly startPageId: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+                readonly nodes: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly $ref: "#/$defs/flowNode";
+                    };
+                };
+                readonly edges: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly $ref: "#/$defs/flowEdge";
+                    };
+                };
+            };
+            readonly additionalProperties: true;
+        };
+    };
+    readonly additionalProperties: true;
+};
+/**
+ * Normalizes a local flow manifest without mutating the caller's object.
+ *
+ * Context owned by the outer manifest is removed from `flowJson`; the removed
+ * paths are returned as warnings so callers can explicitly review migration.
+ *
+ * @param input - Parsed JSON value representing a flow manifest.
+ * @returns A cloned normalized manifest and migration warnings.
+ */
+export declare function normalizeFlowConfig(input: unknown): NormalizedFlowConfig;
+/**
+ * Validates a flow manifest using a temporary compiler-shaped context copy.
+ *
+ * The returned `validationConfig` contains injected `flowKey`, `flowName`,
+ * and optional `bindDatasetCode` values for parity with the server compiler.
+ * It is intentionally separate from `normalized` and must never be persisted.
+ *
+ * @param input - Parsed or typed flow manifest.
+ * @returns Validation errors, warnings, normalized data, and the in-memory copy.
+ */
+export declare function validateFlowConfig(input: unknown): FlowConfigValidationResult;
+/**
+ * Reads, validates, and atomically writes a normalized manifest.
+ *
+ * The temporary file is created beside the target and replaced with `rename`,
+ * so readers observe either the old complete file or the new complete file.
+ *
+ * @param filePath - Target manifest path.
+ * @param config - Normalized manifest to persist.
+ * @param options - Set overwrite to false to atomically refuse an existing target.
+ * @returns A promise that resolves after the atomic replacement completes.
+ */
+export declare function writeNormalizedFlowConfig(filePath: string, config: FlowConfig, options?: {
+    overwrite?: boolean;
+}): Promise<void>;
+/**
+ * Reads a JSON flow manifest from disk.
+ *
+ * @param filePath - Path to the manifest.
+ * @returns The parsed JSON value.
+ */
+export declare function readFlowConfigFile(filePath: string): Promise<unknown>;