@octaviaflow/flow-rules 0.18.0 → 0.19.1

package/dist/catalog/general/query/config.d.ts

@@ -1,24 +1,47 @@
 /**
- * Build Query Configuration
+ * Query step configuration — defaults, validation and the contract (DEV-533).
  *
- * Configuration utilities and validation for the Build Query action
- * Supports dual modes: Visual Builder (no-code) and SQL Editor (advanced)
+ * The Query step is built with the visual builder only. `visualConfig` is what
+ * a person or an agent writes; `sqlConfig.sql` is compiled from it by the
+ * editor or the server and is never written by hand.
+ *
+ * Contract: Octaviaflow-Docs/Engine/query/visual-query-v2-dev-533.md.
  */
-import { BuildQueryConfig, QueryMode, QueryType, QueryValidationResult, VisualQueryConfig, SQLQueryConfig } from './types';
+import { type BuildQueryConfig, type VisualConfigV2, type QueryValidationError, type QueryValidationResult, QueryMode, QueryType } from './types';
 export declare const BuildQueryConfigDefaults: {
     mode: QueryMode;
     queryType: QueryType;
     timeout: number;
     maxRows: number;
-    visualConfig: VisualQueryConfig;
-    sqlConfig: SQLQueryConfig;
+    visualConfig: VisualConfigV2;
 };
+/** Shown when `mode` is anything but `'visual'` (legacy `'sql'` included). */
+export declare const QUERY_VISUAL_ONLY_MESSAGE: string;
+/** Shown when `sqlConfig.sql` is present without a `visualConfig` to compile it from. */
+export declare const QUERY_AUTHORED_SQL_MESSAGE: string;
+type Issue = QueryValidationError;
+/**
+ * True when the step names what to read without a plain field list: every
+ * table and column (`selectAll`), an aggregate-only or GROUP BY query, or a
+ * query the editor already compiled (Google Sheets reads every column, so it
+ * saves a runnable query with no field selection). Shared by `validate` and
+ * the node status badge so the two cannot disagree.
+ */
+export declare function queryFieldsSatisfied(config: Record<string, unknown> | undefined): boolean;
+/** True when `selectAll` stands in for the table list. */
+export declare function queryTablesSatisfied(config: Record<string, unknown> | undefined): boolean;
+/**
+ * Validate the visual builder's config — the full v2 shape.
+ * `config` is the whole step config, so the compiled query can be consulted.
+ */
+export declare function validateVisualConfig(config: Record<string, unknown>): Issue[];
 /**
- * Validate Build Query configuration
+ * Validate a Query step's config. Errors mean the step cannot run as written.
  */
-export declare const validateBuildQueryConfig: (config: Partial<BuildQueryConfig>) => QueryValidationResult;
+export declare const validateBuildQueryConfig: (config: Partial<BuildQueryConfig> | Record<string, unknown>) => QueryValidationResult;
 /**
- * Merge user config with defaults
+ * Merge user config with defaults. Always a visual-builder config; a compiled
+ * `sqlConfig` already on the step is carried through untouched.
  */
 export declare const mergeBuildQueryConfig: (userConfig: Partial<BuildQueryConfig>) => BuildQueryConfig;
 /**
@@ -36,9 +59,9 @@ export declare function isQueryableConnector(connector: {
 }): boolean;
 /**
  * The contract for `configContracts.ts`. Mirrors `BuildQueryConfig` in
- * ./types — the two keys an agent most needs, `visualConfig` and `sqlConfig`,
- * were absent from `inputSchema` entirely, so `describe_action_type` never
- * mentioned them and the fence called them undeclared.
+ * ./types. `mode` and `queryType` list exactly what may be authored
+ * (`QUERY_MODES`, `QUERY_TYPES`); the legacy enum members stay in ./types for
+ * reading old steps only.
  */
 export declare const BuildQueryContractSchema: {
     readonly connectorId: {
@@ -48,22 +71,25 @@ export declare const BuildQueryContractSchema: {
     readonly mode: {
         readonly type: "select";
         readonly required: true;
-        readonly options: readonly ["visual", "sql"];
-        readonly description: "visual: the query is built from visualConfig; sql: the query is the text in sqlConfig.sql";
+        readonly options: readonly [QueryMode.Visual];
+        readonly description: "Always 'visual': the Query step is built with the visual builder and described in visualConfig. Hand-written SQL is not accepted.";
     };
     readonly queryType: {
         readonly type: "select";
         readonly required: true;
-        readonly options: readonly ["select", "insert", "update", "delete", "custom"];
-        readonly description: "Only select is a read; the write types exist for the SQL mode of database connectors";
+        readonly options: readonly [QueryType.Select];
+        readonly description: "Always 'select': the Query step reads data. Use a Transform step to write.";
     };
     readonly visualConfig: {
         readonly type: "object";
         readonly required: false;
+        readonly description: string;
     };
     readonly sqlConfig: {
         readonly type: "object";
         readonly required: false;
+        readonly derived: true;
+        readonly description: "Compiled from visualConfig by the editor or the server. Never write it — describe the query in visualConfig.";
     };
     readonly timeout: {
         readonly type: "number";
@@ -74,3 +100,4 @@ export declare const BuildQueryContractSchema: {
         readonly required: false;
     };
 };
+export {};

package/dist/catalog/general/query/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * Build Query Action
+ * Query Action
  *
- * Execute queries against connected databases, APIs, CRMs with dual mode support:
- * - Visual Builder: No-code/low-code query construction
- * - SQL Editor: Advanced SQL query writing with syntax highlighting
+ * Reads data from a connected database, app or CRM. The query is built with
+ * the visual builder only (DEV-533): `visualConfig` is what is authored, and
+ * `sqlConfig.sql` is compiled from it — see ./types and ./config.
  */
 import { ActionDefinition } from '../../types';
 export declare const queryDefinition: ActionDefinition;

package/dist/catalog/general/query/types.d.ts

@@ -1,107 +1,195 @@
 /**
- * Build Query Action Types
+ * Query step types — the shape the editor actually saves (DEV-533).
  *
- * Type definitions for the Build Query action supporting both visual builder and SQL editor modes
+ * The Query step is built with the visual builder only. `visualConfig` is the
+ * one authoring format; `sqlConfig.sql` is the compiled output the editor (or
+ * the server's compiler) writes from it, and is never written by hand.
+ *
+ * Contract: Octaviaflow-Docs/Engine/query/visual-query-v2-dev-533.md.
+ *
+ * Until 0.19.0 this file described a builder that was never shipped (filter
+ * groups keyed `filters`, `QueryField` objects, lowercase join types). Nothing
+ * outside the retired `components/BuildQuery/*` in octaviaflow-ui read those
+ * shapes; the editor saved the one below all along.
+ */
+/**
+ * `SQL` is LEGACY. It is kept so code reading an old saved step can name it;
+ * the contract refuses it (`QUERY_MODES` is `['visual']`), and the Backend's
+ * migration converts the remaining SQL steps to the visual builder.
  */
 export declare enum QueryMode {
     Visual = "visual",
+    /** @deprecated Legacy hand-written SQL. Refused by the contract since 0.19.0. */
     SQL = "sql"
 }
+/**
+ * Only `Select` is authorable — the Query step reads; writes go through
+ * Transform. The other members are kept for reading legacy saved steps.
+ */
 export declare enum QueryType {
     Select = "select",
+    /** @deprecated never authorable — use Transform to write. */
     Insert = "insert",
+    /** @deprecated never authorable — use Transform to write. */
     Update = "update",
+    /** @deprecated never authorable — use Transform to write. */
     Delete = "delete",
+    /** @deprecated never authorable. */
     Custom = "custom"
 }
-export declare enum FilterOperator {
-    Equals = "equals",
-    NotEquals = "not_equals",
-    GreaterThan = "greater_than",
-    LessThan = "less_than",
-    GreaterThanOrEqual = "greater_than_or_equal",
-    LessThanOrEqual = "less_than_or_equal",
-    Contains = "contains",
-    NotContains = "not_contains",
-    StartsWith = "starts_with",
-    EndsWith = "ends_with",
-    In = "in",
-    NotIn = "not_in",
-    IsNull = "is_null",
-    IsNotNull = "is_not_null",
-    Between = "between"
-}
-export declare enum LogicalOperator {
-    And = "and",
-    Or = "or"
-}
-export declare enum SortDirection {
-    Ascending = "asc",
-    Descending = "desc"
-}
-export declare enum JoinType {
-    Inner = "inner",
-    Left = "left",
-    Right = "right",
-    Full = "full"
-}
-export declare enum AggregateFunction {
-    Count = "count",
-    Sum = "sum",
-    Average = "avg",
-    Min = "min",
-    Max = "max",
-    CountDistinct = "count_distinct"
-}
-export interface QueryField {
-    id: string;
-    table: string;
-    column: string;
-    alias?: string;
-    aggregate?: AggregateFunction;
+/** The modes the contract accepts. */
+export declare const QUERY_MODES: readonly [QueryMode.Visual];
+/** The query types the contract accepts. */
+export declare const QUERY_TYPES: readonly [QueryType.Select];
+/**
+ * Condition operators.
+ *
+ * Two spellings are accepted. The design contract writes the comparisons as
+ * symbols (`=`, `!=`, `>`, `<`, `>=`, `<=`); the editor has always stored them
+ * by name (`equals`, `notEquals`, `greaterThan`, `lessThan`, `greaterOrEqual`,
+ * `lessOrEqual`), and every saved step on beta and prod uses the names. Both
+ * mean the same thing, and both compilers (editor and server) must treat them
+ * the same.
+ */
+export declare const QUERY_COMPARISON_OPERATORS: readonly ["=", "!=", ">", "<", ">=", "<=", "equals", "notEquals", "greaterThan", "lessThan", "greaterOrEqual", "lessOrEqual"];
+export declare const QUERY_RELATIVE_DATE_OPERATORS: readonly ["inRelative", "notInRelative"];
+export declare const QUERY_CONDITION_OPERATORS: readonly ["=", "!=", ">", "<", ">=", "<=", "equals", "notEquals", "greaterThan", "lessThan", "greaterOrEqual", "lessOrEqual", "contains", "startsWith", "endsWith", "like", "notLike", "in", "notIn", "between", "isNull", "isNotNull", "inRelative", "notInRelative"];
+export type QueryComparisonOperator = (typeof QUERY_COMPARISON_OPERATORS)[number];
+export type QueryConditionOperator = (typeof QUERY_CONDITION_OPERATORS)[number];
+export declare const RELATIVE_DATE_DIRECTIONS: readonly ["last", "next", "this"];
+export declare const RELATIVE_DATE_UNITS: readonly ["day", "week", "month", "quarter", "year"];
+/** `amount` bounds for `last` / `next`. */
+export declare const RELATIVE_DATE_MAX_AMOUNT = 3650;
+export type RelativeDateDirection = (typeof RELATIVE_DATE_DIRECTIONS)[number];
+export type RelativeDateUnit = (typeof RELATIVE_DATE_UNITS)[number];
+/**
+ * A date window relative to the moment the step runs ("last 30 days", "next
+ * 2 weeks", "this month"). Resolved at run time in UTC — never fixed at save.
+ */
+export interface RelativeDate {
+    direction: RelativeDateDirection;
+    /** Required for `last` / `next`: a whole number, 1..3650. */
+    amount?: number;
+    unit: RelativeDateUnit;
+    /** For `last` / `next`: include the current day/week/… (default true). */
+    includeCurrent?: boolean;
 }
-export interface QueryFilter {
+export type QueryJoinOperator = 'AND' | 'OR';
+/** One comparison: `field <operator> value` (or `<operator> valueField`). */
+export interface ConditionRow {
     id: string;
+    /** Joins this item to the previous sibling. Ignored on the first. Default AND. */
+    joinOperator?: QueryJoinOperator;
     field: string;
-    operator: FilterOperator;
+    operator: QueryConditionOperator;
+    /** A literal or a run-time value; for `between`, `[a, b]` (or `"a,b"`). */
     value?: unknown;
-    values?: unknown[];
-    logicalOperator?: LogicalOperator;
+    /** Compare with another field instead of a value. Exclusive with `value`. */
+    valueField?: string;
+    /** Only with `inRelative` / `notInRelative`. */
+    relative?: RelativeDate;
 }
-export interface QueryFilterGroup {
+/** A parenthesised group of conditions. Nesting depth ≤ `MAX_CONDITION_DEPTH`. */
+export interface ConditionGroup {
     id: string;
-    filters: (QueryFilter | QueryFilterGroup)[];
-    logicalOperator: LogicalOperator;
+    type: 'group';
+    joinOperator?: QueryJoinOperator;
+    conditions: Condition[];
+}
+export type Condition = ConditionRow | ConditionGroup;
+/** How deep groups may nest: a top-level group is depth 1. */
+export declare const MAX_CONDITION_DEPTH = 3;
+export declare const isConditionGroup: (c: unknown) => c is ConditionGroup;
+export declare const QUERY_AGGREGATE_FUNCTIONS: readonly ["COUNT", "COUNT_DISTINCT", "SUM", "AVG", "MIN", "MAX"];
+/** The editor stores the function lowercase (`count`); both cases are accepted. */
+export type QueryAggregateFn = (typeof QUERY_AGGREGATE_FUNCTIONS)[number] | Lowercase<(typeof QUERY_AGGREGATE_FUNCTIONS)[number]>;
+export interface QueryAggregate {
+    fn: QueryAggregateFn;
+    /** The column to aggregate. `*` (or empty) is "all rows", for COUNT only. */
+    field: string;
+    /** The output column name. Needed to refer to the aggregate in `having`. */
+    alias?: string;
+}
+export declare enum SortDirection {
+    Ascending = "asc",
+    Descending = "desc"
 }
 export interface QuerySort {
-    id: string;
+    id?: string;
     field: string;
-    direction: SortDirection;
+    direction: 'asc' | 'desc';
 }
+/** SQL databases only. */
 export interface QueryJoin {
     id: string;
-    type: JoinType;
     table: string;
-    leftField: string;
-    rightField: string;
+    type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+    onField: string;
+    targetField: string;
 }
-export interface QueryGroupBy {
-    id: string;
-    field: string;
-}
-export interface VisualQueryConfig {
+export interface VisualConfigV2 {
+    /** Every table with every column (SQL databases). Tables/fields are then empty. */
+    selectAll?: boolean;
+    /** The table or object to read. The builder reads one; joins add more. */
     tables: string[];
-    fields: QueryField[];
-    filters?: QueryFilterGroup;
+    /** `table.column` names. Empty when the query is aggregate-only. */
+    fields: string[];
+    conditions?: Condition[];
     joins?: QueryJoin[];
-    groupBy?: QueryGroupBy[];
+    /** Related objects whose fields may be read through a lookup (Salesforce, QuickBooks). */
+    relatedObjects?: string[];
+    /** `SELECT DISTINCT`. */
+    distinct?: boolean;
+    groupBy?: string[];
+    aggregates?: QueryAggregate[];
+    /** Filters on the grouped result, by aggregate alias or group column. Needs aggregates or groupBy. */
+    having?: ConditionRow[];
     sort?: QuerySort[];
+    /** Legacy single sort, still written as the first `sort` entry. */
+    orderBy?: {
+        field: string;
+        direction: string;
+    } | null;
+    /** The most rows a run reads (1..10,000; unset = 10,000). */
+    maxRows?: number;
+    /** Rows the preview shows. A run never reads it. */
     limit?: number;
-    offset?: number;
+    /** Only rows whose `watermarkField` advanced since the last successful run. */
+    incremental?: boolean;
+    watermarkField?: string;
+    /** One page per run, for a ForEach cursor loop. */
+    paged?: boolean;
+    pageSize?: number;
+    /** Google Sheets whose header is not in row 1. */
+    sheetCustomLayout?: boolean;
+    sheetHeaderRow?: number;
+    sheetColumns?: string;
 }
-export interface SQLQueryConfig {
+/** The name consumers already import. Same shape as `VisualConfigV2`. */
+export type VisualQueryConfig = VisualConfigV2;
+/**
+ * Compiled output — written by the editor or the server's compiler from
+ * `visualConfig`. Never authored.
+ */
+export interface CompiledQuery {
     sql: string;
+}
+/** @deprecated use `CompiledQuery`; kept for legacy reads. */
+export type SQLQueryConfig = CompiledQuery & {
     parameters?: Record<string, unknown>;
+};
+export interface BuildQueryConfig {
+    connectorId: string;
+    mode: QueryMode.Visual;
+    queryType: QueryType.Select;
+    visualConfig?: VisualConfigV2;
+    /** Derived. See `CompiledQuery`. */
+    sqlConfig?: CompiledQuery;
+    timeout?: number;
+    /** Legacy step-level field — not read at run; use `visualConfig.maxRows`. */
+    maxRows?: number;
+    /** MongoDB database / Google Sheets spreadsheet id. */
+    database?: string;
 }
 export interface TableSchema {
     name: string;
@@ -138,15 +226,6 @@ export interface ConnectorSchema {
     procedures?: string[];
     functions?: string[];
 }
-export interface BuildQueryConfig {
-    connectorId: string;
-    mode: QueryMode;
-    queryType: QueryType;
-    visualConfig?: VisualQueryConfig;
-    sqlConfig?: SQLQueryConfig;
-    timeout?: number;
-    maxRows?: number;
-}
 export interface QueryExecutionResult {
     success: boolean;
     data?: unknown[];
@@ -189,7 +268,6 @@ export interface QueryableConnector {
     id: string;
     name: string;
     type: ConnectorType;
-    supportsSQL: boolean;
     supportsVisualBuilder: boolean;
     schema?: ConnectorSchema;
 }

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

@@ -16,7 +16,12 @@ export interface ConditionFilter {
     id: string;
     field: string;
     operator: ConditionOperator;
-    value: string;
+    /**
+     * The right-hand side: a literal, a field path, or a `$` system variable.
+     * Numbers and booleans are literals in their own right — `0` and `false`
+     * are real values, not "missing" (DEV-540).
+     */
+    value: string | number | boolean;
     logicalOperator?: 'and' | 'or';
 }
 export interface ConditionConfigType {