@octaviaflow/flow-rules 0.1.0

package/dist/catalog/types.js

@@ -0,0 +1,135 @@
+/**
+ * Action System Type Definitions
+ *
+ * Complete type definitions for the action system including enums, interfaces, and utilities
+ */
+// ============================================
+// ENUMS
+// ============================================
+export var ActionCategory;
+(function (ActionCategory) {
+    // Core workflow
+    ActionCategory["Trigger"] = "trigger";
+    ActionCategory["Action"] = "action";
+    ActionCategory["Logic"] = "logic";
+    ActionCategory["Transform"] = "transform";
+    // AI-specific
+    ActionCategory["AI"] = "ai";
+    // Data operations
+    ActionCategory["Database"] = "database";
+    ActionCategory["API"] = "api";
+    ActionCategory["Storage"] = "storage";
+    ActionCategory["FileStorage"] = "file_storage";
+    // Communication
+    ActionCategory["Communication"] = "communication";
+    // Integrations
+    ActionCategory["CRM"] = "crm";
+    ActionCategory["Ecommerce"] = "ecommerce";
+    ActionCategory["Marketing"] = "marketing";
+    ActionCategory["Analytics"] = "analytics";
+    ActionCategory["Productivity"] = "productivity";
+    // Advanced
+    ActionCategory["Custom"] = "custom";
+    ActionCategory["Utility"] = "utility";
+})(ActionCategory || (ActionCategory = {}));
+export var ActionType;
+(function (ActionType) {
+    // Triggers
+    ActionType["Schedule"] = "schedule";
+    ActionType["Webhook"] = "webhook";
+    ActionType["Manual"] = "manual";
+    ActionType["DataChange"] = "data_change";
+    ActionType["Event"] = "event";
+    // Data Actions
+    ActionType["Read"] = "read";
+    ActionType["Write"] = "write";
+    ActionType["Update"] = "update";
+    ActionType["Delete"] = "delete";
+    ActionType["Query"] = "query";
+    // API Actions
+    ActionType["HTTPRequest"] = "http_request";
+    ActionType["GraphQLQuery"] = "graphql_query";
+    // Logic Actions
+    ActionType["Condition"] = "condition";
+    ActionType["ForEach"] = "for_each";
+    ActionType["Group"] = "group";
+    // Transform Actions
+    ActionType["Format"] = "format";
+    // AI Actions
+    ActionType["AIAgent"] = "ai_agent";
+    ActionType["Embedding"] = "embedding";
+    ActionType["VectorSearch"] = "vector_search";
+    ActionType["ImageGeneration"] = "image_generation";
+    ActionType["ImageAnalysis"] = "image_analysis";
+    ActionType["SpeechToText"] = "speech_to_text";
+    ActionType["TextToSpeech"] = "text_to_speech";
+    // General Actions
+    ActionType["Transform"] = "transform";
+    // Storage Actions
+    ActionType["FileOperation"] = "file_operation";
+    ActionType["FileAction"] = "file_action";
+    ActionType["CsvAction"] = "csv_action";
+    ActionType["JsonAction"] = "json_action";
+    ActionType["XmlAction"] = "xml_action";
+    ActionType["ExcelAction"] = "excel_action";
+    ActionType["S3Action"] = "s3_action";
+    ActionType["FtpAction"] = "ftp_action";
+    ActionType["GoogleDriveAction"] = "google_drive_action";
+    ActionType["DropboxAction"] = "dropbox_action";
+    ActionType["OneDriveAction"] = "onedrive_action";
+    ActionType["StorageAction"] = "storage_action";
+    // Communication Actions
+    ActionType["EmailSend"] = "email_send";
+    ActionType["SlackMessage"] = "slack_message";
+    ActionType["WhatsappSend"] = "whatsapp_send";
+    ActionType["TeamsMessage"] = "teams_message";
+    ActionType["GoogleChat"] = "google_chat";
+    ActionType["WebhookCall"] = "webhook_call";
+    // Utility Actions
+    ActionType["Delay"] = "delay";
+    ActionType["Wait"] = "wait";
+    ActionType["Console"] = "console";
+    ActionType["Debug"] = "debug";
+    ActionType["Error"] = "error";
+    // Custom
+    ActionType["CustomCode"] = "custom_code";
+    ActionType["CustomAction"] = "custom_action";
+    // IDP — engine-driven sync extraction. Replaces the legacy
+    // idp_wait_for_job poll loop; the engine resolves the LLM connector at
+    // execution time and extracts once per source file.
+    ActionType["IdpExtract"] = "idp_extract";
+})(ActionType || (ActionType = {}));
+export var ActionStatus;
+(function (ActionStatus) {
+    ActionStatus["Stable"] = "stable";
+    ActionStatus["Beta"] = "beta";
+    ActionStatus["Alpha"] = "alpha";
+    ActionStatus["Experimental"] = "experimental";
+    ActionStatus["Deprecated"] = "deprecated";
+})(ActionStatus || (ActionStatus = {}));
+export var FieldType;
+(function (FieldType) {
+    FieldType["String"] = "string";
+    FieldType["Number"] = "number";
+    FieldType["Boolean"] = "boolean";
+    FieldType["Date"] = "date";
+    FieldType["DateTime"] = "datetime";
+    FieldType["Array"] = "array";
+    FieldType["Object"] = "object";
+    FieldType["JSON"] = "json";
+    FieldType["File"] = "file";
+    FieldType["Image"] = "image";
+    FieldType["Select"] = "select";
+    FieldType["MultiSelect"] = "multi_select";
+    FieldType["Code"] = "code";
+    FieldType["Expression"] = "expression";
+    FieldType["Mapping"] = "mapping";
+    FieldType["Connection"] = "connection";
+    FieldType["Secret"] = "secret";
+    FieldType["Color"] = "color";
+    FieldType["URL"] = "url";
+    FieldType["Email"] = "email";
+    FieldType["Phone"] = "phone";
+    FieldType["RichText"] = "rich_text";
+    FieldType["Markdown"] = "markdown";
+})(FieldType || (FieldType = {}));

package/dist/catalog/utility/debug/config.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Debug Action — Config Types
+ *
+ * Mirrors the engine's `DebugConfig` shape so UI and engine agree on
+ * serialization with no translation layer. See:
+ *   Octaviaflow-Engine/src/services/debugExecutor.ts
+ */
+export type DebugMode = 'log' | 'snapshot' | 'watch' | 'assert' | 'profile';
+export type DebugSamplingStrategy = 'head' | 'tail' | 'every-nth' | 'random';
+export interface DebugSampling {
+    strategy: DebugSamplingStrategy;
+    n: number;
+    threshold?: number;
+}
+export interface LogModeConfig {
+    level: 'debug' | 'info' | 'warning' | 'error';
+    message: string;
+    includeInputData?: boolean;
+}
+export interface SnapshotModeConfig {
+    paths?: string[];
+    schemaDiff?: boolean;
+    redactPaths?: string[];
+}
+export interface WatchExpression {
+    label: string;
+    expression: string;
+}
+export interface WatchModeConfig {
+    expressions: WatchExpression[];
+}
+export interface AssertModeConfig {
+    predicate: string;
+    failureMessage: string;
+    failureCode?: string;
+}
+export interface ProfileModeConfig {
+    scope: 'step' | 'since-last-debug';
+    memory?: boolean;
+}
+export interface DebugConfigType {
+    mode: DebugMode;
+    label: string;
+    pinned?: boolean;
+    condition?: string;
+    sampling?: DebugSampling;
+    log?: LogModeConfig;
+    snapshot?: SnapshotModeConfig;
+    watch?: WatchModeConfig;
+    assert?: AssertModeConfig;
+    profile?: ProfileModeConfig;
+}
+export declare const DebugConfig: {
+    defaults: DebugConfigType;
+    /**
+     * Pre-flight validation. Surfaces mode-specific missing-field errors.
+     */
+    validate(config: Partial<DebugConfigType>): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * One-time migration of the legacy `{ label, value }` stub config to
+     * the new `{ mode: 'log', label, log: {...} }` shape. Returns the
+     * config unchanged when it's already in the new shape.
+     */
+    migrateLegacyStub(config: Partial<DebugConfigType> & {
+        value?: unknown;
+    }): DebugConfigType;
+    merge(userConfig: Partial<DebugConfigType>): DebugConfigType;
+    getLabel(config: DebugConfigType): string;
+};

package/dist/catalog/utility/debug/config.js

@@ -0,0 +1,90 @@
+/**
+ * Debug Action — Config Types
+ *
+ * Mirrors the engine's `DebugConfig` shape so UI and engine agree on
+ * serialization with no translation layer. See:
+ *   Octaviaflow-Engine/src/services/debugExecutor.ts
+ */
+export const DebugConfig = {
+    defaults: {
+        mode: 'log',
+        label: '',
+        log: { level: 'info', message: '' },
+    },
+    /**
+     * Pre-flight validation. Surfaces mode-specific missing-field errors.
+     */
+    validate(config) {
+        const errors = [];
+        if (!config.mode)
+            errors.push('Mode is required.');
+        if (!config.label?.trim())
+            errors.push('Label is required.');
+        switch (config.mode) {
+            case 'log':
+                if (!config.log?.message?.trim())
+                    errors.push('Log mode: message is required.');
+                if (!config.log?.level)
+                    errors.push('Log mode: level is required.');
+                break;
+            case 'snapshot':
+                // No required fields — paths is optional, schemaDiff is optional.
+                break;
+            case 'watch':
+                if (!config.watch?.expressions?.length) {
+                    errors.push('Watch mode: add at least one expression.');
+                }
+                else {
+                    for (const e of config.watch.expressions) {
+                        if (!e.label?.trim())
+                            errors.push('Watch mode: each expression needs a label.');
+                        if (!e.expression?.trim())
+                            errors.push('Watch mode: each expression needs an expression string.');
+                    }
+                }
+                break;
+            case 'assert':
+                if (!config.assert?.predicate?.trim())
+                    errors.push('Assert mode: predicate is required.');
+                if (!config.assert?.failureMessage?.trim())
+                    errors.push('Assert mode: failure message is required.');
+                break;
+            case 'profile':
+                if (!config.profile?.scope)
+                    errors.push('Profile mode: scope is required.');
+                break;
+        }
+        return { valid: errors.length === 0, errors };
+    },
+    /**
+     * One-time migration of the legacy `{ label, value }` stub config to
+     * the new `{ mode: 'log', label, log: {...} }` shape. Returns the
+     * config unchanged when it's already in the new shape.
+     */
+    migrateLegacyStub(config) {
+        if (config.mode) {
+            // Already migrated — strip stub-only `value` field if it lingers.
+            const { value: _stub, ...rest } = config;
+            return { ...DebugConfig.defaults, ...rest };
+        }
+        // Stub shape: { label, value }. Convert to log mode with the label
+        // doubled as the message (the most useful default given no other
+        // signal). The unused `value` is dropped — its content was always
+        // the upstream input which `includeInputData: true` now captures.
+        return {
+            mode: 'log',
+            label: config.label ?? 'Debug',
+            log: {
+                level: 'info',
+                message: config.label ?? 'Debug',
+                includeInputData: true,
+            },
+        };
+    },
+    merge(userConfig) {
+        return { ...DebugConfig.defaults, ...userConfig };
+    },
+    getLabel(config) {
+        return `Debug [${config.mode}]: ${config.label}`;
+    },
+};

package/dist/catalog/utility/debug/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Debug Action
+ *
+ * Multi-mode workflow-author observability primitive: log / snapshot /
+ * watch / assert / profile. Plus condition gating, sampling, schema-
+ * diff classification, and a deploy-mode flag.
+ *
+ * See:
+ */
+import { ActionDefinition } from '../../types';
+export declare const debugDefinition: ActionDefinition;

package/dist/catalog/utility/debug/index.js

@@ -0,0 +1,38 @@
+/**
+ * Debug Action
+ *
+ * Multi-mode workflow-author observability primitive: log / snapshot /
+ * watch / assert / profile. Plus condition gating, sampling, schema-
+ * diff classification, and a deploy-mode flag.
+ *
+ * See:
+ */
+import { ActionCategory, ActionType, ActionStatus } from '../../types';
+export const debugDefinition = {
+    id: 'debug',
+    name: 'Debug',
+    description: 'Inspect, assert, watch, profile, or log workflow data at any point. Supports condition gating, sampling, and schema-drift detection.',
+    category: ActionCategory.Utility,
+    type: ActionType.Debug,
+    tags: ['utility', 'debug', 'observability', 'assert', 'snapshot', 'profile', 'built-in'],
+    status: ActionStatus.Stable,
+    icon: 'Debug',
+    color: '#6929C4',
+    // Custom panel handles all input — no generic field list.
+    inputSchema: { fields: [] },
+    // Output is intentionally minimal — Debug is observation, not data
+    // production. Captures live in the per-execution debug record.
+    outputSchema: {
+        type: 'object',
+        properties: [],
+        sampleOutput: { debugged: true, mode: 'log' },
+    },
+    // Bumping major version triggers the workflow migration that converts
+    // the legacy `{ label, value }` stub config to `{ mode: 'log', ... }`.
+    version: '2.0.0',
+    createdAt: '2025-01-01T00:00:00Z',
+    updatedAt: '2026-05-02T00:00:00Z',
+    createdBy: 'system',
+    isOfficial: true,
+    testable: false,
+};

package/dist/catalog/utility/error/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error Configuration
+ */
+export interface ErrorConfigType {
+    message: string;
+    code?: string;
+}
+export declare const ErrorConfig: {
+    defaults: ErrorConfigType;
+    schema: {
+        message: {
+            type: string;
+            required: boolean;
+        };
+        code: {
+            type: string;
+            required: boolean;
+        };
+    };
+    validate: (config: Partial<ErrorConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<ErrorConfigType>) => ErrorConfigType;
+    getLabel: (config: ErrorConfigType) => string;
+};

package/dist/catalog/utility/error/config.js

@@ -0,0 +1,25 @@
+/**
+ * Error Configuration
+ */
+export const ErrorConfig = {
+    defaults: {
+        message: '',
+        code: undefined,
+    },
+    schema: {
+        message: { type: 'string', required: true },
+        code: { type: 'string', required: false },
+    },
+    validate: (config) => {
+        const errors = [];
+        if (!config.message)
+            errors.push('Error message is required');
+        return { valid: errors.length === 0, errors };
+    },
+    merge: (userConfig) => {
+        return { ...ErrorConfig.defaults, ...userConfig };
+    },
+    getLabel: (config) => {
+        return `Error: ${config.message}`;
+    },
+};

package/dist/catalog/utility/error/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Action
+ *
+ * Throw an error to stop workflow execution
+ */
+import { ActionDefinition } from '../../types';
+export declare const errorDefinition: ActionDefinition;

package/dist/catalog/utility/error/index.js

@@ -0,0 +1,46 @@
+/**
+ * Error Action
+ *
+ * Throw an error to stop workflow execution
+ */
+import { ActionCategory, ActionType, ActionStatus, FieldType } from '../../types';
+export const errorDefinition = {
+    id: 'error',
+    name: 'Error',
+    description: 'Throw an error to stop workflow execution',
+    category: ActionCategory.Utility,
+    type: ActionType.Error,
+    tags: ['utility', 'error', 'control', 'built-in'],
+    status: ActionStatus.Stable,
+    icon: 'ErrorFilled',
+    color: '#da3742',
+    inputSchema: {
+        fields: [
+            {
+                key: 'message',
+                label: 'Error Message',
+                type: FieldType.String,
+                description: 'Error message to throw',
+                validation: { required: true },
+            },
+            {
+                key: 'code',
+                label: 'Error Code',
+                type: FieldType.String,
+                description: 'Error code',
+                validation: { required: false },
+            },
+        ],
+    },
+    outputSchema: {
+        type: 'void',
+        properties: [],
+        sampleOutput: null,
+    },
+    version: '1.0.0',
+    createdAt: '2025-01-01T00:00:00Z',
+    updatedAt: '2025-12-15T00:00:00Z',
+    createdBy: 'system',
+    isOfficial: true,
+    testable: true,
+};

package/dist/catalog/utility/variables/config.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Variables Action — Config Types
+ *
+ * Mirrors the engine's `VariableField` shape so the UI and engine
+ * agree on serialization with no translation layer.
+ */
+export type VariableType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'date';
+export type VariableSourceKind = 'literal' | 'expression' | 'prompt' | 'secret' | 'env';
+export type VariableSource = {
+    kind: 'literal';
+    value: unknown;
+} | {
+    kind: 'expression';
+    raw: string;
+} | {
+    kind: 'prompt';
+    promptKey: string;
+    defaultValue?: unknown;
+} | {
+    kind: 'secret';
+    secretRef: string;
+} | {
+    kind: 'env';
+    envKey: string;
+};
+export interface VariableField {
+    /** Output key — must match `/^[a-zA-Z_][a-zA-Z0-9_]*$/` and be unique within the step. */
+    key: string;
+    /** Display label for the row in the config panel. Defaults to `key`. */
+    label?: string;
+    type: VariableType;
+    source: VariableSource;
+    /** When true, re-evaluate on every step entry (e.g. inside ForEach).
+     *  When false (default), evaluate once and cache for the run. */
+    reactive?: boolean;
+    /** When true, raise `required_missing` if the resolved value is null /
+     *  undefined / empty string. */
+    required?: boolean;
+    validation?: {
+        pattern?: string;
+        min?: number;
+        max?: number;
+        enum?: unknown[];
+    };
+    description?: string;
+}
+export interface VariablesConfigType {
+    fields: VariableField[];
+    /** Computed at save time by the panel; used by downstream Field
+     *  Mappers / ForEach pickers without needing to re-run the workflow. */
+    _outputSchema?: {
+        type: 'object';
+        properties: Record<string, unknown>;
+    };
+}
+export declare const VariablesConfig: {
+    defaults: VariablesConfigType;
+    /**
+     * Pre-flight validation — runs at config save in the panel. Returns
+     * `valid: true` when every row passes; otherwise an array of human-
+     * readable error strings tagged with the offending key.
+     */
+    validate(config: Partial<VariablesConfigType>): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Compute the action's `_outputSchema` from a field list. Maps each
+     * field's declared type to a JSONSchema node so downstream Field
+     * Mappers see real fields without a preview run.
+     */
+    computeOutputSchema(fields: VariableField[]): {
+        type: "object";
+        properties: Record<string, unknown>;
+    };
+};

package/dist/catalog/utility/variables/config.js

@@ -0,0 +1,70 @@
+/**
+ * Variables Action — Config Types
+ *
+ * Mirrors the engine's `VariableField` shape so the UI and engine
+ * agree on serialization with no translation layer.
+ */
+const RESERVED_KEYS = new Set(['_lineage', '_meta', '_redacted', '_error']);
+const KEY_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const VariablesConfig = {
+    defaults: {
+        fields: [],
+    },
+    /**
+     * Pre-flight validation — runs at config save in the panel. Returns
+     * `valid: true` when every row passes; otherwise an array of human-
+     * readable error strings tagged with the offending key.
+     */
+    validate(config) {
+        const errors = [];
+        const fields = config.fields ?? [];
+        const seen = new Set();
+        for (const f of fields) {
+            if (!f.key) {
+                errors.push('Each field needs a key.');
+                continue;
+            }
+            if (RESERVED_KEYS.has(f.key)) {
+                errors.push(`"${f.key}" is reserved — pick another key.`);
+                continue;
+            }
+            if (!KEY_PATTERN.test(f.key)) {
+                errors.push(`"${f.key}" is not a valid identifier (letters, digits, underscore; must not start with a digit).`);
+                continue;
+            }
+            if (seen.has(f.key)) {
+                errors.push(`Duplicate key "${f.key}".`);
+                continue;
+            }
+            seen.add(f.key);
+            if (!f.type)
+                errors.push(`"${f.key}" is missing a type.`);
+            if (!f.source)
+                errors.push(`"${f.key}" is missing a source.`);
+        }
+        return { valid: errors.length === 0, errors };
+    },
+    /**
+     * Compute the action's `_outputSchema` from a field list. Maps each
+     * field's declared type to a JSONSchema node so downstream Field
+     * Mappers see real fields without a preview run.
+     */
+    computeOutputSchema(fields) {
+        const properties = {};
+        for (const f of fields) {
+            properties[f.key] = fieldToJsonSchema(f);
+        }
+        return { type: 'object', properties };
+    },
+};
+function fieldToJsonSchema(f) {
+    const node = { type: f.type };
+    if (f.description)
+        node.description = f.description;
+    if (f.validation?.enum)
+        node.enum = f.validation.enum;
+    // For arrays we don't know the item shape from the row alone (the
+    // user picks `array` but the source value may be string, number, or
+    // object). Leave items unset — Field Mapper synthesis can handle.
+    return node;
+}

package/dist/catalog/utility/variables/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Variables Action
+ *
+ * Emit one or more typed user-defined values as a step output. Five
+ * source kinds — literal, expression, prompt, secret, env — each
+ * captured via a row in the config panel. Replaces the legacy
+ * USER_INPUT pattern with first-class typed step output.
+ *
+ * See:
+ *   (design notes live in the platform's own documentation)
+ */
+import { ActionDefinition } from '../../types';
+export declare const variablesDefinition: ActionDefinition;

package/dist/catalog/utility/variables/index.js

@@ -0,0 +1,40 @@
+/**
+ * Variables Action
+ *
+ * Emit one or more typed user-defined values as a step output. Five
+ * source kinds — literal, expression, prompt, secret, env — each
+ * captured via a row in the config panel. Replaces the legacy
+ * USER_INPUT pattern with first-class typed step output.
+ *
+ * See:
+ *   (design notes live in the platform's own documentation)
+ */
+import { ActionCategory, ActionType, ActionStatus } from '../../types';
+export const variablesDefinition = {
+    id: 'variables',
+    name: 'Variables',
+    description: 'Emit one or more typed user-defined values as a step output. Sources: literal, expression, prompt, secret, env.',
+    category: ActionCategory.Utility,
+    type: ActionType.Write,
+    tags: ['utility', 'variables', 'value', 'expression', 'built-in'],
+    status: ActionStatus.Stable,
+    icon: 'Parameter',
+    color: '#0F62FE',
+    // Custom panel handles all input editing — no generic field list.
+    inputSchema: { fields: [] },
+    // Output schema is computed at config-save time from the field rows
+    // (the panel emits `_outputSchema` into config). The static fallback
+    // here is just a placeholder so the picker shows *something* before
+    // the user defines fields.
+    outputSchema: {
+        type: 'object',
+        properties: [],
+        sampleOutput: {},
+    },
+    version: '1.0.0',
+    createdAt: '2026-05-02T00:00:00Z',
+    updatedAt: '2026-05-02T00:00:00Z',
+    createdBy: 'system',
+    isOfficial: true,
+    testable: false,
+};