@octaviaflow/flow-rules 0.10.0 → 0.11.0

package/dist/catalog/ai/ai-agent/config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * AI Agent Action Configuration
+ *
+ * What AIAgentActionPanel / AIAgentConfigureModal write and the Engine's
+ * ai_agent case forwards to the Backend (`POST /internal/ai-agent/execute`).
+ *
+ * The editor also keeps `_dataRefs` (short prompt tokens → step bindings),
+ * `_outputSchema`, `_outputSchemaHash` and `_lastPreviewAt` beside these. They
+ * are the editor's own (`isEditorPrivateKey`) and are not part of the contract.
+ */
+export type AiAgentReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high';
+export type AiAgentVerbosity = 'low' | 'medium' | 'high';
+/** Per-step overrides of the saved agent, sent as `body.overrides` as-is. */
+export interface AiAgentOverrides {
+    /** Model id; empty means the agent's own. */
+    model?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    reasoningEffort?: AiAgentReasoningEffort;
+    verbosity?: AiAgentVerbosity;
+    /** Rows per call on the ETL path (integer ≥ 1). */
+    batchSize?: number;
+    /** Extra instructions; `instructionsMode` says whether they append or replace. */
+    instructions?: string;
+    instructionsMode?: 'append' | 'replace';
+    /** JSON Schema the agent must answer in; the Engine derives one from downstream bindings when absent. */
+    expectedSchema?: Record<string, unknown>;
+    /** Set by the Engine on the ETL path — the typed prompt with `{{row.<field>}}` refs. */
+    userPromptTemplate?: string;
+}
+export interface AiAgentConfigType {
+    /** Public id of a saved agent (`agt_…`). */
+    agentId: string;
+    /**
+     * The prompt. May carry short `{{slug.path}}` tokens (bound through the
+     * editor's `_dataRefs`) or `{{ods://…}}` refs. When empty, the first
+     * upstream output is the input.
+     */
+    input?: string;
+    overrides?: AiAgentOverrides;
+}
+export declare const AiAgentConfig: {
+    defaults: AiAgentConfigType;
+    schema: {
+        agentId: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        input: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        overrides: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<AiAgentConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<AiAgentConfigType>) => AiAgentConfigType;
+    getLabel: (config: AiAgentConfigType) => string;
+};

package/dist/catalog/ai/idp-extract/config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * IDP Extract Action Configuration
+ *
+ * What IdpExtractConfigPanel writes and the Engine's idp_extract case reads.
+ * The Backend adds `_resolvedLlmConnection` (the connector's credentials) at
+ * dispatch; the files come from the upstream step's output, not from config.
+ */
+export type IdpExtractStrategy = 'vision-direct' | 'auto';
+export declare const IDP_EXTRACT_STRATEGIES: readonly IdpExtractStrategy[];
+export interface IdpExtractConfigType {
+    /** The AI connector instance whose key and model run the extraction. */
+    llmConnectorId: string;
+    /** Model id offered by that connector. */
+    model: string;
+    /** JSON Schema of the fields to extract — as an object or a JSON string. Empty extracts every field. */
+    expectedSchema?: Record<string, unknown> | string;
+    systemPromptOverride?: string;
+    /** `vision-direct` (default) or `auto`. */
+    strategy?: IdpExtractStrategy;
+}
+export declare const IdpExtractConfig: {
+    defaults: IdpExtractConfigType;
+    schema: {
+        llmConnectorId: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        model: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        expectedSchema: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        systemPromptOverride: {
+            type: string;
+            required: boolean;
+        };
+        strategy: {
+            type: string;
+            required: boolean;
+            options: readonly IdpExtractStrategy[];
+        };
+    };
+    validate: (config: Partial<IdpExtractConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<IdpExtractConfigType>) => IdpExtractConfigType;
+    getLabel: (config: IdpExtractConfigType) => string;
+};

package/dist/catalog/logic/group/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Group Configuration
+ *
+ * A group has no configuration of its own: the editor shows only a Metadata
+ * tab (`description` and `disabled` are top-level step fields, not config),
+ * and the Engine flattens the group's `branches` before running and executes
+ * the group step itself as a no-op. The contract is therefore empty — which
+ * is a statement, not an omission: every key under a group's `config` is
+ * undeclared.
+ */
+export type GroupConfigType = Record<string, never>;
+export declare const GroupConfig: {
+    defaults: GroupConfigType;
+    schema: {};
+    validate: (_config: Partial<GroupConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (_userConfig: Partial<GroupConfigType>) => GroupConfigType;
+    getLabel: () => string;
+};

package/dist/catalog/storage/csv-action/config.d.ts

@@ -0,0 +1,136 @@
+/**
+ * CSV Action Configuration
+ *
+ * What CsvConfigPanel writes and the Engine's csv_action case reads.
+ */
+import { type FileEditConfigType, type FileFormatOperation } from '../fileEditContract';
+export interface CsvActionConfigType extends FileEditConfigType {
+    /** `parse` (default when absent) | `generate` | `edit`. */
+    operation: FileFormatOperation;
+    /** Legacy alias for `operation` — the Engine reads `operation || mode`. */
+    mode?: string;
+    /** CSV text, or an FX token from an upstream step. */
+    content?: string;
+    /** Legacy alias for `content` — the Engine reads `content || inlineContent`. */
+    inlineContent?: string;
+    delimiter?: ',' | ';' | '\t' | '|';
+    /** 1-based row that holds the column headers. */
+    headerRow?: number;
+    encoding?: string;
+    /** `generate`: write the header row (true unless exactly false). */
+    includeHeader?: boolean;
+    /** `generate`: name of the produced file. */
+    fileName?: string;
+}
+export declare const CsvActionConfig: {
+    defaults: CsvActionConfigType;
+    schema: {
+        editOperation: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditOperation[];
+            readonly description: "How the file is edited: append rows, update rows by key, upsert, or set fields on matching rows";
+        };
+        keyField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Match key column for update / upsert";
+        };
+        mergeUpdate: {
+            readonly type: "boolean";
+            readonly required: false;
+            readonly description: "false replaces the whole matched row; default merges";
+        };
+        matchField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: column the row filter reads";
+        };
+        matchOp: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditMatchOp[];
+            readonly description: "set_fields: comparison; \"=\" by default";
+        };
+        matchValue: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: value compared against";
+        };
+        setFields: {
+            readonly type: "object";
+            readonly required: false;
+            readonly description: "set_fields: { column: newValue } applied to matching rows";
+        };
+        destination: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditDestination[];
+            readonly description: "\"new\" writes an edited copy (default); \"in_place\" overwrites an S3 source";
+        };
+        outputFileName: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Name of the edited copy when destination is \"new\"";
+        };
+        source: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditSource[];
+            readonly description: "Where the file to edit comes from; inferred from content when absent";
+        };
+        s3Key: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "source \"s3\": platform-bucket key of the file to edit";
+        };
+        url: {
+            readonly type: "url";
+            readonly required: false;
+            readonly description: "source \"url\": the file to edit is fetched from here";
+        };
+        operation: {
+            type: string;
+            required: boolean;
+            options: readonly FileFormatOperation[];
+            description: string;
+        };
+        content: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        delimiter: {
+            type: string;
+            required: boolean;
+            options: string[];
+        };
+        headerRow: {
+            type: string;
+            required: boolean;
+            min: number;
+            description: string;
+        };
+        encoding: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        includeHeader: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        fileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<CsvActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<CsvActionConfigType>) => CsvActionConfigType;
+    getLabel: (config: CsvActionConfigType) => string;
+};

package/dist/catalog/storage/dropbox-action/config.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dropbox Action Configuration (deprecated — `storage_action` replaces it)
+ *
+ * What DropboxConfigPanel writes and the Engine's `runDropbox` reads. The
+ * Backend adds `_resolvedStorageCredentials` from `connector` at dispatch.
+ */
+export type DropboxOperation = 'list' | 'download' | 'upload' | 'delete' | 'move' | 'copy';
+export declare const DROPBOX_OPERATIONS: readonly DropboxOperation[];
+export interface DropboxActionConfigType {
+    /** The Dropbox connector instance (a connection id). */
+    connector: string;
+    /** `download` when absent. */
+    operation?: DropboxOperation;
+    /** File path, or the folder to list (root when empty). */
+    path?: string;
+    /** upload: the body. */
+    content?: string;
+    /** upload: name when `path` is a folder. */
+    fileName?: string;
+    /** move / copy: the destination path. */
+    destPath?: string;
+    /** upload: Dropbox write mode — `overwrite` (default) or `add` (keep both). */
+    mode?: 'overwrite' | 'add';
+    /** list: keep only these extensions. */
+    fileTypes?: string[];
+    /** list: keep only names matching this glob. */
+    filePattern?: string;
+}
+export declare const DropboxActionConfig: {
+    defaults: DropboxActionConfigType;
+    schema: {
+        connector: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        operation: {
+            type: string;
+            required: boolean;
+            options: readonly DropboxOperation[];
+        };
+        path: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        content: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        fileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        destPath: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        mode: {
+            type: string;
+            required: boolean;
+            options: string[];
+            description: string;
+        };
+        fileTypes: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        filePattern: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<DropboxActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<DropboxActionConfigType>) => DropboxActionConfigType;
+    getLabel: (config: DropboxActionConfigType) => string;
+};

package/dist/catalog/storage/excel-action/config.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Excel Action Configuration
+ *
+ * What ExcelConfigPanel writes and the Engine's excel_action case reads.
+ */
+import { type FileEditConfigType, type FileFormatOperation } from '../fileEditContract';
+export interface ExcelActionConfigType extends FileEditConfigType {
+    /** `parse` (default when absent) | `generate` | `edit`. */
+    operation: FileFormatOperation;
+    /** Legacy alias for `operation`. */
+    mode?: string;
+    /**
+     * The workbook: a platform-bucket key (contains `/` or ends .xlsx/.xls),
+     * base64 bytes, or an FX token from an upstream step.
+     */
+    content?: string;
+    /** Legacy alias for `content`. */
+    inlineContent?: string;
+    /** Sheet to read; the first sheet when absent. */
+    sheetName?: string;
+    /** 1-based row that holds the column headers. */
+    headerRow?: number;
+    /** `generate`: name of the produced file. */
+    fileName?: string;
+}
+export declare const ExcelActionConfig: {
+    defaults: ExcelActionConfigType;
+    schema: {
+        editOperation: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditOperation[];
+            readonly description: "How the file is edited: append rows, update rows by key, upsert, or set fields on matching rows";
+        };
+        keyField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Match key column for update / upsert";
+        };
+        mergeUpdate: {
+            readonly type: "boolean";
+            readonly required: false;
+            readonly description: "false replaces the whole matched row; default merges";
+        };
+        matchField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: column the row filter reads";
+        };
+        matchOp: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditMatchOp[];
+            readonly description: "set_fields: comparison; \"=\" by default";
+        };
+        matchValue: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: value compared against";
+        };
+        setFields: {
+            readonly type: "object";
+            readonly required: false;
+            readonly description: "set_fields: { column: newValue } applied to matching rows";
+        };
+        destination: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditDestination[];
+            readonly description: "\"new\" writes an edited copy (default); \"in_place\" overwrites an S3 source";
+        };
+        outputFileName: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Name of the edited copy when destination is \"new\"";
+        };
+        source: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditSource[];
+            readonly description: "Where the file to edit comes from; inferred from content when absent";
+        };
+        s3Key: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "source \"s3\": platform-bucket key of the file to edit";
+        };
+        url: {
+            readonly type: "url";
+            readonly required: false;
+            readonly description: "source \"url\": the file to edit is fetched from here";
+        };
+        operation: {
+            type: string;
+            required: boolean;
+            options: readonly FileFormatOperation[];
+            description: string;
+        };
+        content: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        headerRow: {
+            type: string;
+            required: boolean;
+            min: number;
+            description: string;
+        };
+        fileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+    };
+    validate: (config: Partial<ExcelActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<ExcelActionConfigType>) => ExcelActionConfigType;
+    getLabel: (config: ExcelActionConfigType) => string;
+};

package/dist/catalog/storage/file-action/config.d.ts

@@ -0,0 +1,197 @@
+/**
+ * File Action Configuration (generic parse / generate / edit)
+ *
+ * `file_action` has no editor panel and is not in the add palette; the Engine
+ * still executes it (`executeFileAction`). This is what that executor reads.
+ * Where the same key is shared with the format-specific actions it is the
+ * shared entry from `fileEditContract`; `source` and `outputFileName` are
+ * redeclared because this action accepts more sources.
+ */
+import { type FileEditConfigType } from '../fileEditContract';
+export type FileActionMode = 'parse' | 'generate' | 'convert' | 'edit';
+export type FileActionSource = 'inline' | 's3' | 'url' | 'previous_step' | 'upload';
+export type FileActionFormat = 'auto' | 'csv' | 'tsv' | 'json' | 'jsonl' | 'xml' | 'excel';
+export type FileActionOutputFormat = 'csv' | 'json' | 'excel' | 'xml' | 'tsv';
+export declare const FILE_ACTION_MODES: readonly FileActionMode[];
+export declare const FILE_ACTION_SOURCES: readonly FileActionSource[];
+export declare const FILE_ACTION_FORMATS: readonly FileActionFormat[];
+export declare const FILE_ACTION_OUTPUT_FORMATS: readonly FileActionOutputFormat[];
+export interface FileActionConfigType extends Omit<FileEditConfigType, 'source'> {
+    /** `parse` (default) | `generate` | `convert` | `edit`. */
+    mode?: FileActionMode;
+    /** Alias the Engine reads first: `operation || mode`. */
+    operation?: FileActionMode;
+    /** Where the file comes from; `inline` by default. `upload` is not supported at run time. */
+    source?: FileActionSource;
+    /** Format of the file; detected from the name, then the content, when `auto` or absent. */
+    format?: FileActionFormat;
+    /** `source: 'inline'` — the text (base64 for Excel). */
+    inlineContent?: string;
+    /** Alias for `inlineContent`. */
+    content?: string;
+    /** `source: 's3'` — platform-bucket key. */
+    s3Key?: string;
+    /** `source: 'url'` — fetched with a 60 s timeout. */
+    url?: string;
+    /** `generate` / `convert`: format to write. */
+    outputFormat?: FileActionOutputFormat;
+    /** `generate` / `convert`: name of the produced file. */
+    outputFileName?: string;
+    /** Name used to detect the format when `format` is `auto`. */
+    fileName?: string;
+    encoding?: string;
+    delimiter?: string;
+    headerRow?: number;
+    rowElement?: string;
+    sheetName?: string;
+    includeHeader?: boolean;
+    /** Parser options (`delimiter`, `headerRow`, …) read ahead of the top-level keys. */
+    options?: Record<string, unknown>;
+}
+export declare const FileActionConfig: {
+    defaults: FileActionConfigType;
+    schema: {
+        mode: {
+            type: string;
+            required: boolean;
+            options: readonly FileActionMode[];
+            description: string;
+        };
+        operation: {
+            type: string;
+            required: boolean;
+            options: readonly FileActionMode[];
+            description: string;
+        };
+        source: {
+            type: string;
+            required: boolean;
+            options: readonly FileActionSource[];
+            description: string;
+        };
+        format: {
+            type: string;
+            required: boolean;
+            options: readonly FileActionFormat[];
+            description: string;
+        };
+        inlineContent: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        content: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        outputFormat: {
+            type: string;
+            required: boolean;
+            options: readonly FileActionOutputFormat[];
+            description: string;
+        };
+        outputFileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        fileName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        encoding: {
+            type: string;
+            required: boolean;
+        };
+        delimiter: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        headerRow: {
+            type: string;
+            required: boolean;
+            min: number;
+        };
+        rowElement: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        sheetName: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        includeHeader: {
+            type: string;
+            required: boolean;
+        };
+        options: {
+            type: string;
+            required: boolean;
+            description: string;
+        };
+        editOperation: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditOperation[];
+            readonly description: "How the file is edited: append rows, update rows by key, upsert, or set fields on matching rows";
+        };
+        keyField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "Match key column for update / upsert";
+        };
+        mergeUpdate: {
+            readonly type: "boolean";
+            readonly required: false;
+            readonly description: "false replaces the whole matched row; default merges";
+        };
+        matchField: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: column the row filter reads";
+        };
+        matchOp: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditMatchOp[];
+            readonly description: "set_fields: comparison; \"=\" by default";
+        };
+        matchValue: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "set_fields: value compared against";
+        };
+        setFields: {
+            readonly type: "object";
+            readonly required: false;
+            readonly description: "set_fields: { column: newValue } applied to matching rows";
+        };
+        destination: {
+            readonly type: "select";
+            readonly required: false;
+            readonly options: readonly import("../fileEditContract").FileEditDestination[];
+            readonly description: "\"new\" writes an edited copy (default); \"in_place\" overwrites an S3 source";
+        };
+        s3Key: {
+            readonly type: "string";
+            readonly required: false;
+            readonly description: "source \"s3\": platform-bucket key of the file to edit";
+        };
+        url: {
+            readonly type: "url";
+            readonly required: false;
+            readonly description: "source \"url\": the file to edit is fetched from here";
+        };
+    };
+    validate: (config: Partial<FileActionConfigType>) => {
+        valid: boolean;
+        errors: string[];
+    };
+    merge: (userConfig: Partial<FileActionConfigType>) => FileActionConfigType;
+    getLabel: (config: FileActionConfigType) => string;
+};